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

> Discover how tools are defined and used in the Prime Agent 'tools' package. Learn about the modular factory pattern and type-safe registration for efficient tool management.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/ipython.ts) exports `createIpythonToolDefinition` for the metadata/schema and `createIpythonTool` for the callable implementation. Similarly, [`bash.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/bash.ts) provides shell execution capabilities, [`edit.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/edit.ts) handles file editing, and [`truncate.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/index.ts))

The [`packages/coding-agent/src/core/tools/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/mytool.ts)) exporting `createMyToolDefinition` and `createMyTool` functions.
2. **Import the exports** in [`packages/coding-agent/src/core/tools/index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/ipython.ts), [`bash.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/bash.ts), [`edit.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/edit.ts)) export paired creation functions for maximum modularity.
- [`index.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/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.