How Tools Are Defined and Used in the Prime Agent `tools` Package

The tools package in Prime Agent employs a modular factory pattern where individual modules export paired creation functions for definitions and runtime instances, while index.ts centrally registers them under a type-safe ToolName union with switch-based factory functions.

The Prime Agent repository (PrimeIntellect-ai/prime-agent) organizes its agent capabilities into a dedicated tools package located at packages/coding-agent/src/core/tools/. This architecture enforces a strict separation between tool definitions (metadata, schemas, and configuration) and runtime tools (executable implementations), enabling type-safe tool discovery and instantiation throughout the coding agent.

Architecture of the Tools Package

The package structure divides responsibilities across specialized modules, ensuring that adding new capabilities requires minimal changes to existing code.

Individual Tool Modules

Each tool resides in its own file and exports two distinct factory functions. For example, ipython.ts exports createIpythonToolDefinition for the metadata/schema and createIpythonTool for the callable implementation. Similarly, bash.ts provides shell execution capabilities, edit.ts handles file editing, and truncate.ts supplies text truncation utilities (truncateHead, truncateTail). While these modules exist, only the IPython tool is currently fully wired into the central factory; others are prepared for future integration.

Central Registration Hub (index.ts)

The packages/coding-agent/src/core/tools/index.ts file serves as the single source of truth for available tools. It declares the ToolName union type (currently "ipython"), maintains an allToolNames Set for validation, and implements the core factory logic:

export type ToolName = "ipython";
export const allToolNames: Set<ToolName> = new Set(["ipython"]);

export function createToolDefinition(
    toolName: ToolName,
    cwd: string,
    options?: ToolsOptions,
): ToolDef {
    switch (toolName) {
        case "ipython":
            return createIpythonToolDefinition(cwd, options?.ipython);
        default:
            throw new Error(`Unknown tool name: ${toolName}`);
    }
}

export function createTool(
    toolName: ToolName,
    cwd: string,
    options?: ToolsOptions,
): Tool {
    switch (toolName) {
        case "ipython":
            return createIpythonTool(cwd, options?.ipython);
        default:
            throw new Error(`Unknown tool name: ${toolName}`);
    }
}

Type Safety and Wrapping

The tool-definition-wrapper.ts file provides generic helpers that ensure every raw tool definition conforms to the ToolDefinition interface expected by the agent core. This wrapper bridges the gap between individual tool implementations and the central AgentTool type used throughout the system.

Creating Tool Definitions and Runtime Instances

Developers interact with the package through two primary factory functions exported from index.ts.

Single Tool Instantiation

Use createToolDefinition when you need the schema and metadata for a specific tool, and createTool when you need the executable instance:

import { createTool, createToolDefinition } from "@prime-agent/coding-agent/src/core/tools/index.js";

// Get the definition (schema + metadata)
const ipythonDef = createToolDefinition("ipython", "/my/project");

// Get the runtime tool (executable)
const ipythonTool = createTool("ipython", "/my/project");

Configuration via ToolsOptions

The ToolsOptions interface allows passing per-tool configuration. Currently, only IPython accepts options, but the structure supports future extensions:

export interface ToolsOptions {
    ipython?: IpythonToolOptions;
}

Working with All Tools at Once

For convenience, the package provides createAllToolDefinitions and createAllTools to instantiate every supported tool for a given working directory:

import { createAllTools, createAllToolDefinitions } from "@prime-agent/coding-agent/src/core/tools/index.js";

// Create definitions for all supported tools
const defs = createAllToolDefinitions("/my/project");
// → { ipython: <ToolDefinition> }

// Instantiate all runtime tools
const tools = createAllTools("/my/project");
// → { ipython: <AgentTool> }

// Execute code through the IPython tool
await tools.ipython.run({
  code: "print('Hello, Prime Agent!')",
});

Adding a New Tool to the Package

Extending the package requires four steps according to the source code architecture:

1. Create a module (e.g., mytool.ts) exporting createMyToolDefinition and createMyTool functions.
2. Import the exports in packages/coding-agent/src/core/tools/index.ts.
3. Expand the type system by adding the tool name to the ToolName union and allToolNames Set.
4. Extend the factories by adding cases to the switch statements in both createToolDefinition and createTool.

This pattern ensures that the rest of the codebase can request tools by name without importing implementation details directly.

Integration with the Agent Core

While the tools package handles definition and creation, packages/coding-agent/src/utils/tools-manager.ts manages the lifecycle of tools during agent execution. It caches instances, validates tool names against the allToolNames Set, and propagates configuration options from the session runtime to the individual tool factories.

Summary

• The tools package lives at packages/coding-agent/src/core/tools/ and follows a strict factory pattern separating definitions from runtime implementations.
• Individual tool modules (like ipython.ts, bash.ts, edit.ts) export paired creation functions for maximum modularity.
• index.ts centralizes registration via the ToolName union and switch-based factories (createToolDefinition and createTool).
• Bulk operations are supported through createAllToolDefinitions and createAllTools, returning records keyed by tool name.
• Adding new tools requires only extending the ToolName type and updating the two factory switches in index.ts.
• ToolsOptions provides a type-safe configuration mechanism for per-tool settings.

Frequently Asked Questions

How do I instantiate a specific tool by name in Prime Agent?

Import createTool from packages/coding-agent/src/core/tools/index.ts and pass the tool name as the first argument along with the working directory. For example: const tool = createTool("ipython", "/project/path"). The function uses a switch statement to return the appropriate AgentTool instance.

What is the difference between a tool definition and a runtime tool?

A tool definition (created via createToolDefinition) contains the metadata, JSON schema, and configuration options required by the LLM to understand the tool's capabilities. A runtime tool (created via createTool) is the actual callable implementation that executes logic, such as running Python code in an IPython REPL or executing shell commands.

How does the tools package handle configuration options?

The package uses the ToolsOptions interface defined in index.ts to pass optional configurations to individual tools. When calling createTool or createToolDefinition, you can provide an options object that the factory functions destructure and pass to specific tool creators, such as options?.ipython for the IPython tool.

Where are tools actually executed during an agent session?

While the tools package handles creation and definitions, execution management occurs in packages/coding-agent/src/utils/tools-manager.ts. This utility caches tool instances, validates tool names against the allToolNames Set, and ensures that the correct working directory and options are propagated to each tool during the agent's runtime lifecycle.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}