> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool System Overview

> IronClaw's extensible tool architecture for adding capabilities to AI agents

IronClaw provides a powerful, security-first tool system that allows agents to interact with external services, execute code, manage data, and extend their capabilities through custom tools.

## Architecture

The tool system is built on three pillars:

```text theme={null}
┌─────────────────────────────────────────────────────────────────────────────┐
│                          IronClaw Tool System                                │
│                                                                              │
│   Built-in Tools ──────▶ Core functionality (HTTP, shell, files, memory)   │
│   (Rust native)                                                              │
│                                                                              │
│   WASM Tools ──────────▶ Sandboxed extensions with capability control       │
│   (Sandboxed)           • Fuel metering   • Memory limits                   │
│                         • Allowlists      • Credential injection             │
│                                                                              │
│   MCP Servers ─────────▶ External tool providers via JSON-RPC               │
│   (External process)    • Pre-built servers  • Any language                 │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Tool Trait

All tools implement the `Tool` trait defined in `src/tools/tool.rs`:

```rust theme={null}
#[async_trait]
pub trait Tool: Send + Sync {
    /// Get the tool name.
    fn name(&self) -> &str;

    /// Get a description of what the tool does.
    fn description(&self) -> &str;

    /// Get the JSON Schema for the tool's parameters.
    fn parameters_schema(&self) -> serde_json::Value;

    /// Execute the tool with the given parameters.
    async fn execute(
        &self,
        params: serde_json::Value,
        ctx: &JobContext,
    ) -> Result<ToolOutput, ToolError>;

    /// Whether this tool requires user approval.
    fn requires_approval(&self, _params: &serde_json::Value) -> ApprovalRequirement {
        ApprovalRequirement::Never
    }

    /// Where this tool should execute (Orchestrator or Container).
    fn domain(&self) -> ToolDomain {
        ToolDomain::Orchestrator
    }

    /// Per-invocation rate limit configuration.
    fn rate_limit_config(&self) -> Option<ToolRateLimitConfig> {
        None
    }
}
```

**Location**: `src/tools/tool.rs:178-266`

## Tool Domains

Tools are separated by execution domain for security:

| Domain | Description | Examples | Risk |
| - | - | - | - |
| **Orchestrator** | Safe for main process | `echo`, `time`, `json`, `http`, `memory_*` | Low |
| **Container** | Must run in sandbox | `shell`, `read_file`, `write_file`, `apply_patch` | High |

**Location**: `src/tools/tool.rs:64-74`

Orchestrator tools run in the main agent process and have no filesystem access. Container tools run inside Docker containers with isolated filesystems.

## Tool Registry

The `ToolRegistry` manages all available tools and provides registration methods for different tool types.

**Location**: `src/tools/registry.rs:74-87`

```rust theme={null}
pub struct ToolRegistry {
    tools: RwLock<HashMap<String, Arc<dyn Tool>>>,
    builtin_names: RwLock<HashSet<String>>,
    credential_registry: Option<Arc<SharedCredentialRegistry>>,
    secrets_store: Option<Arc<dyn SecretsStore>>,
    rate_limiter: RateLimiter,
}
```

### Registration Methods

```rust theme={null}
// Register built-in tools (echo, time, json, http, web_fetch)
registry.register_builtin_tools();

// Register container tools (shell, file operations)
registry.register_container_tools();

// Register memory tools (requires workspace)
registry.register_memory_tools(workspace);

// Register job management tools
registry.register_job_tools(context_manager, scheduler, ...);

// Register WASM tool from bytes
registry.register_wasm(WasmToolRegistration {
    name: "my_tool",
    wasm_bytes: &bytes,
    runtime: &runtime,
    capabilities: caps,
    ..Default::default()
}).await?;
```

**Locations**:

* Built-in: `src/tools/registry.rs:210-224`
* Container: `src/tools/registry.rs:236-242`
* Memory: `src/tools/registry.rs:274-285`
* WASM: `src/tools/registry.rs:470-539`

## Protected Tool Names

Certain built-in tools cannot be shadowed by dynamic registrations to prevent security bypasses:

```rust theme={null}
const PROTECTED_TOOL_NAMES: &[&str] = &[
    "echo", "time", "json", "http", "shell",
    "read_file", "write_file", "list_dir", "apply_patch",
    "memory_search", "memory_write", "memory_read", "memory_tree",
    "create_job", "list_jobs", "job_status", "cancel_job",
    "build_software", "tool_search", "tool_install", "tool_auth",
    "web_fetch", "message", ...
];
```

**Location**: `src/tools/registry.rs:36-72`

## Approval Requirements

Tools can specify when they need user approval:

```rust theme={null}
pub enum ApprovalRequirement {
    Never,                    // No approval needed
    UnlessAutoApproved,       // Needs approval unless session auto-approve enabled
    Always,                   // Always requires explicit approval
}
```

**Location**: `src/tools/tool.rs:13-21`

Example from `ShellTool`:

```rust theme={null}
fn requires_approval(&self, params: &serde_json::Value) -> ApprovalRequirement {
    let command = params.get("command")
        .and_then(|v| v.as_str())
        .unwrap_or("");
    
    if is_destructive(command) {
        ApprovalRequirement::Always
    } else {
        ApprovalRequirement::UnlessAutoApproved
    }
}
```

## Rate Limiting

Tools can specify per-user rate limits:

```rust theme={null}
pub struct ToolRateLimitConfig {
    pub requests_per_minute: u32,
    pub requests_per_hour: u32,
}

impl Default for ToolRateLimitConfig {
    fn default() -> Self {
        Self {
            requests_per_minute: 60,
            requests_per_hour: 1000,
        }
    }
}
```

**Location**: `src/tools/tool.rs:31-62`

Read-only tools (echo, time, json, file\_read) return `None` for rate limits. Write/external tools (shell, http, file\_write) return sensible limits.

## Tool Output

Tools return structured output with metadata:

```rust theme={null}
pub struct ToolOutput {
    pub result: serde_json::Value,
    pub cost: Option<Decimal>,
    pub duration: Duration,
    pub raw: Option<String>,
}

impl ToolOutput {
    pub fn success(result: serde_json::Value, duration: Duration) -> Self;
    pub fn text(text: impl Into<String>, duration: Duration) -> Self;
    pub fn with_cost(mut self, cost: Decimal) -> Self;
    pub fn with_raw(mut self, raw: impl Into<String>) -> Self;
}
```

**Location**: `src/tools/tool.rs:101-147`

## Schema Validation

All tool parameter schemas are validated at registration time:

```rust theme={null}
pub fn validate_tool_schema(schema: &serde_json::Value, path: &str) -> Vec<String>
```

**Location**: `src/tools/tool.rs:314-378`

**Rules enforced**:

1. Top-level must have `"type": "object"`
2. Top-level must have `"properties"` as an object
3. Every key in `"required"` must exist in `"properties"`
4. Nested objects follow the same rules recursively
5. Array properties should have `"items"` defined

Properties without a `"type"` field are allowed (freeform/any-type), used by tools like `json` and `http` for OpenAI compatibility.

## Extension Points

The tool system provides multiple extension points:

### 1. Built-in Tools (Rust)

Create new Rust tools by implementing the `Tool` trait.

**See**: [Built-in Tools Reference](/tools/builtin)

### 2. WASM Tools (Sandboxed)

Build sandboxed tools in Rust that compile to WebAssembly.

**See**: [WASM Tool System](/tools/wasm)

### 3. MCP Servers (External)

Connect to external tool servers using the Model Context Protocol.

**See**: [MCP Integration](/tools/mcp)

### 4. Software Builder (LLM-driven)

Use the `build_software` tool to create new tools using AI.

**See**: [Building Custom Tools](/tools/building)

## Next Steps

<CardGroup cols={2}>
  <Card title="Built-in Tools" icon="wrench" href="/tools/builtin">
    Explore the complete reference of built-in tools
  </Card>

  <Card title="WASM Tools" icon="cube" href="/tools/wasm">
    Learn about the sandboxed WASM tool system
  </Card>

  <Card title="MCP Integration" icon="plug" href="/tools/mcp">
    Connect external tool servers via MCP
  </Card>

  <Card title="Build Tools" icon="hammer" href="/tools/building">
    Create custom tools using the builder
  </Card>
</CardGroup>