Tools Module - IronClaw

Overview

The tools module provides an extensible system for agent capabilities. Tools can:

Call external APIs
Interact with the marketplace
Execute sandboxed code (via WASM)
Delegate tasks to other services
Build new software and tools dynamically

Tools execute in different domains (orchestrator vs. container) with safety controls, rate limiting, and approval requirements.

Core Types

Tool Trait

The main trait that all tools must implement.

#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    
    async fn execute(
        &self,
        params: serde_json::Value,
        ctx: &JobContext,
    ) -> Result<ToolOutput, ToolError>;
    
    fn estimated_cost(&self, params: &serde_json::Value) -> Option<Decimal> {
        None
    }
    
    fn approval_requirement(&self, params: &serde_json::Value) -> ApprovalRequirement {
        ApprovalRequirement::Never
    }
    
    fn domain(&self) -> ToolDomain {
        ToolDomain::Orchestrator
    }
    
    fn rate_limit_config(&self) -> Option<ToolRateLimitConfig> {
        None
    }
}

Methods

fn(&self) -> &str

Return the tool name (must be unique in registry)

fn(&self) -> &str

Human-readable description of what the tool does

fn(&self) -> serde_json::Value

JSON Schema defining the tool’s parameters

async fn(&self, params: Value, ctx: &JobContext) -> Result<ToolOutput>

Execute the tool with given parameters and context

fn(&self, params: &Value) -> Option<Decimal>

Estimate the cost of running this tool (optional)

fn(&self, params: &Value) -> ApprovalRequirement

Whether this invocation requires approval

fn(&self) -> ToolDomain

Where this tool should execute (Orchestrator or Container)

fn(&self) -> Option<ToolRateLimitConfig>

Rate limiting configuration for this tool

Example

use ironclaw::tools::{Tool, ToolOutput, ToolError};
use async_trait::async_trait;

struct EchoTool;

#[async_trait]
impl Tool for EchoTool {
    fn name(&self) -> &str {
        "echo"
    }
    
    fn description(&self) -> &str {
        "Echo back the input message"
    }
    
    fn parameters_schema(&self) -> serde_json::Value {
        serde_json::json!({
            "type": "object",
            "properties": {
                "message": {
                    "type": "string",
                    "description": "Message to echo"
                }
            },
            "required": ["message"]
        })
    }
    
    async fn execute(
        &self,
        params: serde_json::Value,
        _ctx: &JobContext,
    ) -> Result<ToolOutput, ToolError> {
        let message = params["message"].as_str()
            .ok_or_else(|| ToolError::InvalidParameters(
                "message must be a string".to_string()
            ))?;
        
        Ok(ToolOutput::text(message, Duration::from_millis(1)))
    }
}

ToolRegistry

Manages the collection of available tools.

fn() -> Self

Create a new empty tool registry

fn(&mut self, tool: Arc<dyn Tool>) -> Result<()>

fn(&self, name: &str) -> Option<Arc<dyn Tool>>

Get a tool by name

fn(&self) -> Vec<&str>

List all registered tool names

fn(&self) -> Vec<ToolDefinition>

Get all tool schemas for LLM function calling

Example

use ironclaw::tools::ToolRegistry;

let mut registry = ToolRegistry::new();
registry.register(Arc::new(EchoTool))?;
registry.register(Arc::new(TimeTool))?;

// List all tools
for name in registry.list() {
    println!("Available: {}", name);
}

// Get a tool
if let Some(tool) = registry.get("echo") {
    let output = tool.execute(params, &ctx).await?;
}

ToolOutput

Result returned by tool execution.

serde_json::Value

The result data (JSON value)

Option<Decimal>

Cost incurred (if any)

Duration

Time taken to execute

Option<String>

Raw output before sanitization (for debugging)

Constructors

fn(result: Value, duration: Duration) -> Self

Create a successful output with JSON result

fn(text: impl Into<String>, duration: Duration) -> Self

Create a text output (convenience for string results)

fn(self, cost: Decimal) -> Self

Add cost information to the output

fn(self, raw: impl Into<String>) -> Self

Add raw output for debugging

Example

use ironclaw::tools::ToolOutput;
use std::time::Duration;
use rust_decimal_macros::dec;

let output = ToolOutput::text("Hello, world!", Duration::from_millis(5))
    .with_cost(dec!(0.001));

ToolError

Error types for tool execution.

String

Parameters don’t match the schema or are invalid

String

Tool execution failed with an error

Duration

Tool execution exceeded timeout

String

User not authorized to use this tool

Option<Duration>

Rate limit exceeded, retry after duration

String

External service error (API, network, etc.)

String

Sandbox/WASM execution error

ApprovalRequirement

Defines how much approval a tool invocation needs.

()

No approval needed (safe, read-only tools)

()

Needs approval unless user has auto-approved this tool

()

Always requires explicit approval (destructive operations)

Example

use ironclaw::tools::ApprovalRequirement;

impl Tool for FileDeleteTool {
    fn approval_requirement(&self, _params: &Value) -> ApprovalRequirement {
        ApprovalRequirement::Always  // Destructive operation
    }
}

impl Tool for FileReadTool {
    fn approval_requirement(&self, _params: &Value) -> ApprovalRequirement {
        ApprovalRequirement::Never  // Safe read-only
    }
}

ToolDomain

Where a tool should execute.

()

Safe to run in the main agent process (pure functions, memory, job management)

()

Must run inside a sandboxed container (filesystem, shell, code execution)

use ironclaw::tools::ToolDomain;

impl Tool for MemoryWriteTool {
    fn domain(&self) -> ToolDomain {
        ToolDomain::Orchestrator  // Safe in main process
    }
}

impl Tool for ShellTool {
    fn domain(&self) -> ToolDomain {
        ToolDomain::Container  // Needs isolation
    }
}

ToolRateLimitConfig

Rate limiting configuration for tools.

u32

default:"60"

Maximum invocations per minute per user

u32

default:"1000"

Maximum invocations per hour per user

fn(requests_per_minute: u32, requests_per_hour: u32) -> Self

Create a custom rate limit config

fn() -> Self

Default: 60/min, 1000/hour

use ironclaw::tools::ToolRateLimitConfig;

impl Tool for HttpTool {
    fn rate_limit_config(&self) -> Option<ToolRateLimitConfig> {
        Some(ToolRateLimitConfig::new(30, 500))  // Conservative limits
    }
}

Schema Validation

validate_tool_schema

fn(schema: &Value, params: &Value) -> Result<()>

Validate parameters against a JSON Schema. Returns error if validation fails.

use ironclaw::tools::validate_tool_schema;

let schema = serde_json::json!({
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "age": { "type": "number" }
    },
    "required": ["name"]
});

let params = serde_json::json!({
    "name": "Alice",
    "age": 30
});

validate_tool_schema(&schema, &params)?;  // OK

Rate Limiting

RateLimiter

Per-user rate limiting for tool invocations.

fn() -> Self

Create a new rate limiter

fn(&self, user_id: &str, tool_name: &str, config: &ToolRateLimitConfig) -> Result<(), Duration>

Check if request is allowed and increment counter. Returns error with retry-after duration if rate limited.

use ironclaw::tools::RateLimiter;

let limiter = RateLimiter::new();
let config = ToolRateLimitConfig::default();

match limiter.check_and_increment("user_123", "http", &config) {
    Ok(()) => {
        // Proceed with tool execution
    }
    Err(retry_after) => {
        return Err(ToolError::RateLimited(Some(retry_after)));
    }
}

Software Builder

Dynamically build and deploy new tools at runtime.

SoftwareBuilder

Trait for building software from natural language specifications.

#[async_trait]
pub trait SoftwareBuilder: Send + Sync {
    async fn build(
        &self,
        requirements: &BuildRequirement,
    ) -> Result<BuildResult, Box<dyn std::error::Error>>;
}

LlmSoftwareBuilder

LLM-powered software builder that generates code from specs.

fn(llm: Arc<dyn LlmProvider>, config: BuilderConfig) -> Self

Create a new LLM-based software builder

async fn(&self, requirements: &BuildRequirement) -> Result<BuildResult>

Build software from requirements using LLM code generation

BuildRequirement

String

Name of the software/tool to build

String

What the software should do

Language

Target language (Rust, Python, JavaScript, etc.)

SoftwareType

Type (Tool, Library, Service, etc.)

Vec<String>

Required dependencies

Vec<TestCase>

Test cases to validate the implementation

BuildResult

String

Generated source code

BuildMetadata

Build information (language, version, etc.)

Vec<TestResult>

Results of running test cases

Vec<ValidationError>

Any validation errors found

Example

use ironclaw::tools::{LlmSoftwareBuilder, BuildRequirement, Language, SoftwareType};

let builder = LlmSoftwareBuilder::new(llm, BuilderConfig::default());

let req = BuildRequirement {
    name: "fibonacci".to_string(),
    description: "Calculate Fibonacci numbers".to_string(),
    language: Language::Rust,
    software_type: SoftwareType::Tool,
    dependencies: vec![],
    test_cases: vec![],
};

let result = builder.build(&req).await?;
println!("Generated code:\n{}", result.source_code);

MCP (Model Context Protocol)

Integration with external MCP servers for tool discovery.

McpClient

Client for connecting to MCP servers and loading tools.

async fn(server_url: &str) -> Result<Self>

Connect to an MCP server

async fn(&self) -> Result<Vec<ToolDefinition>>

List available tools from the MCP server

async fn(&self, name: &str) -> Result<Arc<dyn Tool>>

Load a specific tool from the MCP server

use ironclaw::tools::mcp::McpClient;

let client = McpClient::connect("http://localhost:3000").await?;
let tools = client.list_tools().await?;

for tool_def in tools {
    let tool = client.load_tool(&tool_def.name).await?;
    registry.register(tool)?;
}

WASM Tools

Load and execute tools compiled to WebAssembly.

WasmTool

A tool implementation that runs in a WASM sandbox.

async fn(wasm_bytes: &[u8]) -> Result<Self>

Load a WASM module as a tool

async fn(path: &Path) -> Result<Self>

Load a WASM module from a file

use ironclaw::tools::wasm::WasmTool;

let wasm_bytes = std::fs::read("tools/custom.wasm")?;
let tool = WasmTool::load(&wasm_bytes).await?;

registry.register(Arc::new(tool))?;

Built-in Tools

IronClaw includes several built-in tools in the builtin module:

EchoTool - Echo back input (testing)
TimeTool - Get current time
JsonTool - Parse and manipulate JSON
HttpTool - Make HTTP requests
MemoryReadTool - Read from workspace
MemoryWriteTool - Write to workspace
MemorySearchTool - Search workspace
ShellTool - Execute shell commands (container)
FileReadTool - Read files (container)
FileWriteTool - Write files (container)

See the source code for full details on each tool’s parameters and behavior.

Agent Module

Agent orchestration and tool execution

Workspace Module

Memory tools for persistent storage

​Overview

​Core Types

​Tool Trait

​Methods

​Example

​ToolRegistry

​Example

​ToolOutput

​Constructors

​Example

​ToolError

​ApprovalRequirement

​Example

​ToolDomain

​ToolRateLimitConfig

​Schema Validation

​validate_tool_schema

​Rate Limiting

​RateLimiter

​Software Builder

​SoftwareBuilder

​LlmSoftwareBuilder

​BuildRequirement

​BuildResult

​Example

​MCP (Model Context Protocol)

​McpClient

​WASM Tools

​WasmTool

​Built-in Tools

​Related Modules

Agent Module

Workspace Module

Overview

Core Types

Tool Trait

Methods

Example

ToolRegistry

Example

ToolOutput

Constructors

Example

ToolError

ApprovalRequirement

Example

ToolDomain

ToolRateLimitConfig

Schema Validation

validate_tool_schema

Rate Limiting

RateLimiter

Software Builder

SoftwareBuilder

LlmSoftwareBuilder

BuildRequirement

BuildResult

Example

MCP (Model Context Protocol)

McpClient

WASM Tools

WasmTool

Built-in Tools

Related Modules