08 Tools

Tools

Relevant source files

The following files were used as context for generating this wiki page:

Purpose and Scope

This page documents ZeroClaw's tool system, which provides the agent with 70+ capabilities spanning file operations, memory management, browser automation, external integrations, hardware control, and sub-agent orchestration. Tools are the primary mechanism by which the agent interacts with the external world.

For information about:

Tool execution security and authorization, see Security Model
How tools are invoked during the agent turn cycle, see Tool Execution
Specific tool configurations, see Configuration File Reference

Tool Architecture

ZeroClaw implements tools using a trait-driven design where every tool implements the Tool trait, enabling uniform discovery, validation, and execution by the agent core.

Tool Trait Interface

classDiagram
    class Tool {
        <<trait>>
        +name() String
        +description() String
        +parameters_schema() Value
        +spec() ToolSpec
        +execute(args: Value) Result~ToolResult~
    }
    
    class ToolResult {
        +success: bool
        +output: String
        +error: Option~String~
    }
    
    class ToolSpec {
        +name: String
        +description: String
        +parameters: Value
    }
    
    Tool ..> ToolResult : returns
    Tool ..> ToolSpec : generates

Sources: src/tools/traits.rs, src/tools/mod.rs:1-62

Tool Registry Factory

The tool registry is constructed by factory functions that conditionally include tools based on configuration flags:

flowchart TB
    Start["Factory Call"] --> DefaultCheck{"Function?"}
    
    DefaultCheck -->|default_tools| CoreOnly["Core Tools Only"]
    DefaultCheck -->|all_tools| FullRegistry["Full Registry"]
    
    CoreOnly --> Core["ShellTool<br/>FileReadTool<br/>FileWriteTool"]
    
    FullRegistry --> CoreFull["Core Tools"]
    FullRegistry --> Memory["MemoryStoreTool<br/>MemoryRecallTool<br/>MemoryForgetTool"]
    FullRegistry --> Cron["CronAddTool<br/>CronListTool<br/>CronRemoveTool<br/>CronUpdateTool<br/>CronRunTool<br/>CronRunsTool"]
    FullRegistry --> Git["GitOperationsTool"]
    FullRegistry --> Schedule["ScheduleTool<br/>PushoverTool<br/>ProxyConfigTool"]
    FullRegistry --> BrowserCheck{"browser.enabled?"}
    FullRegistry --> HttpCheck{"http_request.enabled?"}
    FullRegistry --> WebSearchCheck{"web_search.enabled?"}
    FullRegistry --> ComposioCheck{"composio_key?"}
    FullRegistry --> DelegateCheck{"agents configured?"}
    FullRegistry --> Vision["ScreenshotTool<br/>ImageInfoTool"]
    
    BrowserCheck -->|Yes| Browser["BrowserOpenTool<br/>BrowserTool"]
    BrowserCheck -->|No| Skip1["Skip"]
    
    HttpCheck -->|Yes| Http["HttpRequestTool"]
    HttpCheck -->|No| Skip2["Skip"]
    
    WebSearchCheck -->|Yes| WebSearch["WebSearchTool"]
    WebSearchCheck -->|No| Skip3["Skip"]
    
    ComposioCheck -->|Yes| Composio["ComposioTool"]
    ComposioCheck -->|No| Skip4["Skip"]
    
    DelegateCheck -->|Yes| Delegate["DelegateTool"]
    DelegateCheck -->|No| Skip5["Skip"]
    
    Core --> Output["Vec~Box~dyn Tool~~"]
    CoreFull --> Output
    Memory --> Output
    Cron --> Output
    Git --> Output
    Schedule --> Output
    Browser --> Output
    Http --> Output
    WebSearch --> Output
    Composio --> Output
    Delegate --> Output
    Vision --> Output
    Skip1 --> Output
    Skip2 --> Output
    Skip3 --> Output
    Skip4 --> Output
    Skip5 --> Output

Sources: src/tools/mod.rs:72-238

Factory Function	Purpose	Tool Count
`default_tools()`	Minimal set for basic agent operations	3
`default_tools_with_runtime()`	Minimal set with custom runtime adapter	3
`all_tools()`	Full registry based on configuration	15-25+
`all_tools_with_runtime()`	Full registry with custom runtime adapter	15-25+

Sources: src/tools/mod.rs:72-117

Core Tool Categories

File and Shell Operations

graph LR
    ShellTool["ShellTool<br/>(shell)"] --> Runtime["RuntimeAdapter"]
    FileReadTool["FileReadTool<br/>(file_read)"] --> Security["SecurityPolicy"]
    FileWriteTool["FileWriteTool<br/>(file_write)"] --> Security
    
    Security --> PathValidation["workspace_only check<br/>forbidden_paths check<br/>symlink escape detection"]
    Runtime --> NativeRuntime["NativeRuntime"]
    Runtime --> DockerRuntime["DockerRuntime"]

Core file/shell tools:

ShellTool (shell): Execute shell commands via runtime adapter with sandboxing support
FileReadTool (file_read): Read file contents with path security validation
FileWriteTool (file_write): Write file contents with path security validation

Sources: src/tools/mod.rs:82-84, src/tools/mod.rs:136-138

Memory Management Tools

graph TB
    MemoryStoreTool["MemoryStoreTool<br/>(memory_store)"] --> MemoryBackend["Memory Backend"]
    MemoryRecallTool["MemoryRecallTool<br/>(memory_recall)"] --> MemoryBackend
    MemoryForgetTool["MemoryForgetTool<br/>(memory_forget)"] --> MemoryBackend
    
    MemoryBackend --> SQLite["SQLite<br/>(hybrid search)"]
    MemoryBackend --> Postgres["PostgreSQL"]
    MemoryBackend --> Lucid["Lucid Bridge"]
    MemoryBackend --> Markdown["Markdown Files"]

Memory tools:

MemoryStoreTool (memory_store): Store conversation or context data with automatic embedding
MemoryRecallTool (memory_recall): Query memory using hybrid vector + keyword search
MemoryForgetTool (memory_forget): Delete specific memory entries

Sources: src/tools/mod.rs:145-147

Cron and Scheduling Tools

graph TB
    CronAddTool["CronAddTool<br/>(cron_add)"]
    CronListTool["CronListTool<br/>(cron_list)"]
    CronRemoveTool["CronRemoveTool<br/>(cron_remove)"]
    CronUpdateTool["CronUpdateTool<br/>(cron_update)"]
    CronRunTool["CronRunTool<br/>(cron_run)"]
    CronRunsTool["CronRunsTool<br/>(cron_runs)"]
    ScheduleTool["ScheduleTool<br/>(schedule)"]
    
    CronAddTool --> CronConfig["Config::cron"]
    CronListTool --> CronConfig
    CronRemoveTool --> CronConfig
    CronUpdateTool --> CronConfig
    CronRunTool --> CronConfig
    CronRunsTool --> CronConfig
    ScheduleTool --> CronConfig
    
    CronConfig --> JobPersistence["TOML persistence<br/>~/.zeroclaw/config.toml"]

Cron/schedule tools:

CronAddTool (cron_add): Add recurring cron job (shell or agent prompt)
CronListTool (cron_list): List all scheduled jobs with next run times
CronRemoveTool (cron_remove): Delete a scheduled job by ID
CronUpdateTool (cron_update): Modify existing job schedule or payload
CronRunTool (cron_run): Trigger immediate one-time execution of a job
CronRunsTool (cron_runs): List execution history for a job
ScheduleTool (schedule): High-level scheduling interface

Sources: src/tools/mod.rs:139-144, src/tools/mod.rs:148

Git Operations

GitOperationsTool (git_operations): Execute git commands within workspace with security scoping.

Sources: src/tools/mod.rs:150-153

Browser and HTTP Tools

Browser Automation Backends

ZeroClaw supports three pluggable browser automation backends:

graph TB
    BrowserTool["BrowserTool<br/>(browser)"] --> BackendSelector{"backend config"}
    BrowserOpenTool["BrowserOpenTool<br/>(browser_open)"] --> DirectOpen["Direct URL open"]
    
    BackendSelector -->|"agent_browser"| AgentBrowser["Agent-Browser CLI<br/>(default)"]
    BackendSelector -->|"rust_native"| RustNative["fantoccini WebDriver<br/>(feature: browser-native)"]
    BackendSelector -->|"computer_use"| ComputerUse["Computer-Use Sidecar<br/>(HTTP endpoint)"]
    BackendSelector -->|"auto"| AutoSelect["Auto-select<br/>based on availability"]
    
    AgentBrowser --> WebDriverServer["WebDriver Server<br/>(e.g., chromedriver)"]
    RustNative --> WebDriverServer
    ComputerUse --> SidecarAPI["Sidecar HTTP API<br/>POST /v1/actions"]

Browser tools:

BrowserOpenTool (browser_open): Simple URL opening with domain allowlist
BrowserTool (browser): Full automation (click, fill, scroll, screenshot) with pluggable backends

Actions supported by BrowserTool:

navigate: Navigate to URL
click: Click element by selector or coordinates
fill: Fill form field by selector
screenshot: Capture page screenshot
scroll: Scroll viewport
get_text: Extract text from element
execute_script: Run JavaScript

Computer-Use Sidecar Contract:

POST {browser.computer_use.endpoint}
{
  "action": "mouse_click",
  "params": {"x": 640, "y": 360, "button": "left"},
  "policy": {
    "allowed_domains": ["docs.rs"],
    "window_allowlist": [],
    "max_coordinate_x": 3840,
    "max_coordinate_y": 2160
  },
  "metadata": {
    "session_name": "zeroclaw-session",
    "source": "zeroclaw.browser",
    "version": "0.1.0"
  }
}

Sources: src/tools/mod.rs:160-185, src/config/mod.rs:11, README.md:562-588

HTTP Request Tool

HttpRequestTool (http_request): Make arbitrary HTTP requests with domain allowlist, size limits, and timeout controls.

Parameters:

method: GET, POST, PUT, DELETE, PATCH, HEAD
url: Target URL (must match allowed_domains)
headers: Optional request headers
body: Optional request body
follow_redirects: Boolean flag

Sources: src/tools/mod.rs:187-194

Web Search Tool

WebSearchTool (web_search): Search the web using configured provider (Brave Search API by default).

Configuration:

[web_search]
enabled = true
provider = "brave"  # Currently only Brave Search supported
brave_api_key = "..."
max_results = 10
timeout_secs = 15

Sources: src/tools/mod.rs:196-204, README.md:196-204

Integration Tools

Composio Multi-App Integration

ComposioTool provides OAuth-managed access to 1000+ third-party applications without storing raw credentials locally. It uses the Composio managed platform API with v3/v2 fallback for compatibility.

sequenceDiagram
    participant Agent
    participant ComposioTool
    participant ComposioAPIv3
    participant ComposioAPIv2
    participant ThirdPartyApp["Third-Party App<br/>(Gmail, GitHub, Notion, etc.)"]
    
    Agent->>ComposioTool: execute(action: "list", app: "gmail")
    ComposioTool->>ComposioAPIv3: GET /api/v3/tools?toolkits=gmail
    alt v3 success
        ComposioAPIv3-->>ComposioTool: 200 OK + tools list
        ComposioTool-->>Agent: ToolResult(actions)
    else v3 failure
        ComposioAPIv3-->>ComposioTool: 4xx/5xx error
        ComposioTool->>ComposioAPIv2: GET /api/v2/actions?appNames=gmail
        ComposioAPIv2-->>ComposioTool: 200 OK + actions list
        ComposioTool-->>Agent: ToolResult(actions)
    end
    
    Agent->>ComposioTool: execute(action: "execute", tool_slug: "gmail-fetch-emails")
    ComposioTool->>ComposioAPIv3: POST /api/v3/tools/gmail-fetch-emails/execute
    ComposioAPIv3->>ThirdPartyApp: OAuth request
    ThirdPartyApp-->>ComposioAPIv3: Response
    ComposioAPIv3-->>ComposioTool: Execution result
    ComposioTool-->>Agent: ToolResult(output)

Composio actions:

list: List available actions/tools for an app
execute: Execute action with parameters (requires tool_slug or action_name)
connect: Get OAuth connection URL for app authorization

API Endpoints:

v3: https://backend.composio.dev/api/v3/tools
v2: https://backend.composio.dev/api/v2/actions (fallback)

Sources: src/tools/composio.rs:19-20, src/tools/composio.rs:49-138, src/tools/composio.rs:385-584, src/tools/mod.rs:210-218

Delegation Tool (Sub-Agent Orchestration)

DelegateTool enables multi-agent workflows by delegating subtasks to purpose-built sub-agents with different provider/model configurations.

graph TB
    PrimaryAgent["Primary Agent<br/>(GPT-4)"] -->|delegate| DelegateTool
    
    DelegateTool --> DepthCheck{"depth < max_depth?"}
    DepthCheck -->|Yes| AgentLookup["Lookup agent config<br/>from agents map"]
    DepthCheck -->|No| DepthError["Return depth limit error"]
    
    AgentLookup --> ProviderCreation["Create Provider<br/>for sub-agent"]
    ProviderCreation --> SubAgent1["Researcher Sub-Agent<br/>(Ollama + Llama3)"]
    ProviderCreation --> SubAgent2["Coder Sub-Agent<br/>(Claude Sonnet)"]
    ProviderCreation --> SubAgent3["Summarizer Sub-Agent<br/>(GPT-3.5 Turbo)"]
    
    SubAgent1 --> Response["Return response<br/>with agent metadata"]
    SubAgent2 --> Response
    SubAgent3 --> Response
    
    Response --> PrimaryAgent

Depth limiting: Each DelegateTool instance tracks its depth in the delegation chain. When a sub-agent is created, its DelegateTool must be constructed with DelegateTool::with_depth(agents, cred, security, parent.depth + 1) to prevent infinite recursion.

Configuration example:

[agents.researcher]
provider = "ollama"
model = "llama3"
system_prompt = "You are a research assistant."
temperature = 0.3
max_depth = 3

[agents.coder]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-20250514"
api_key = "..."  # Optional per-agent credential
max_depth = 2

Parameters:

agent: Name of sub-agent to delegate to (must exist in config)
prompt: Task/prompt to send to sub-agent
context: Optional context to prepend (e.g., relevant code, prior findings)

Timeout: Sub-agent calls timeout after 120 seconds to prevent indefinite blocking.

Sources: src/tools/delegate.rs:19-58, src/tools/delegate.rs:60-266, src/tools/mod.rs:220-235

Notification Tool

PushoverTool (pushover): Send push notifications via Pushover API. Reads credentials from workspace .env file.

Required credentials in .env:

PUSHOVER_TOKEN=your_app_token
PUSHOVER_USER_KEY=your_user_key

Parameters:

message: Notification text (required)
title: Optional title
priority: -2 (silent), -1 (low), 0 (normal), 1 (high), 2 (emergency)
sound: Optional sound override

Sources: src/tools/pushover.rs:11-215, src/tools/mod.rs:154-157

Proxy Configuration Tool

ProxyConfigTool (proxy_config): Dynamically configure HTTP/SOCKS proxy settings at runtime.

Sources: src/tools/mod.rs:149

Vision Tools

ScreenshotTool (screenshot): Capture screen regions or full display with base64 encoding for vision-capable LLMs.

ImageInfoTool (image_info): Extract metadata and describe image contents.

Sources: src/tools/mod.rs:207-208

Tool Execution Flow

The agent core invokes tools through a standardized flow with security enforcement at multiple layers:

sequenceDiagram
    participant AgentCore["Agent Core<br/>(loop_.rs)"]
    participant SecurityPolicy
    participant Tool
    participant RuntimeAdapter
    participant ExternalSystem["External System<br/>(filesystem, API, etc.)"]
    
    AgentCore->>Tool: execute(args: Value)
    Tool->>Tool: Validate args against<br/>parameters_schema()
    
    alt Tool requires action permission
        Tool->>SecurityPolicy: can_act()?
        alt ReadOnly mode
            SecurityPolicy-->>Tool: false
            Tool-->>AgentCore: ToolResult(error: "read-only")
        else Full/Supervised mode
            SecurityPolicy-->>Tool: true
            Tool->>SecurityPolicy: record_action()?
            alt Rate limit exceeded
                SecurityPolicy-->>Tool: false
                Tool-->>AgentCore: ToolResult(error: "rate limit")
            else Within limit
                SecurityPolicy-->>Tool: true
                Tool->>Tool: Execute tool logic
            end
        end
    else Read-only tool
        Tool->>Tool: Execute tool logic
    end
    
    Tool->>RuntimeAdapter: Optional sandboxed execution
    RuntimeAdapter->>ExternalSystem: Perform action
    ExternalSystem-->>RuntimeAdapter: Result
    RuntimeAdapter-->>Tool: Result
    
    Tool->>Tool: Format ToolResult
    Tool-->>AgentCore: ToolResult(success, output, error)

Sources: src/tools/composio.rs:490-500, src/tools/delegate.rs:174-183, src/tools/pushover.rs:115-129

Tool Parameter Validation

All tools define a JSON Schema for parameter validation:

graph LR
    ToolSpec["ToolSpec"] --> Name["name: String"]
    ToolSpec --> Description["description: String"]
    ToolSpec --> Parameters["parameters: Value<br/>(JSON Schema)"]
    
    Parameters --> Schema["type: object<br/>properties: {...}<br/>required: [...]"]
    Schema --> Validation["LLM validates before call<br/>Agent validates at runtime"]

Example schema from DelegateTool:

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "minLength": 1,
      "description": "Name of agent to delegate to..."
    },
    "prompt": {
      "type": "string",
      "minLength": 1,
      "description": "Task/prompt to send..."
    },
    "context": {
      "type": "string",
      "description": "Optional context..."
    }
  },
  "required": ["agent", "prompt"]
}

Sources: src/tools/delegate.rs:72-102, src/tools/traits.rs

Tool Testing Strategy

Tools include comprehensive unit and integration tests:

Test Category	Purpose	Example
Schema validation	Verify parameters_schema() is well-formed	src/tools/mod.rs:364-380
Security enforcement	Confirm ReadOnly mode blocks actions	src/tools/composio.rs:842-861
Rate limiting	Verify max_actions_per_hour enforcement	src/tools/delegate.rs:479-495
Parameter validation	Reject missing/invalid parameters	src/tools/delegate.rs:337-348
Depth limiting	Prevent infinite delegation loops	src/tools/delegate.rs:362-382
Credential handling	Parse .env files securely	src/tools/pushover.rs:274-293

Sources: src/tools/mod.rs:240-510, src/tools/composio.rs:763-959, src/tools/delegate.rs:269-577, src/tools/pushover.rs:217-433

Hardware Tools

Hardware tools are enabled with the hardware feature flag (default enabled):

Available hardware tools:

HardwareBoardInfoTool (hardware_board_info): Query board metadata
HardwareMemoryMapTool (hardware_memory_map): Inspect memory layout
HardwareMemoryReadTool (hardware_memory_read): Read from hardware memory addresses

Optional features:

peripheral-rpi: Raspberry Pi GPIO support via rppal
probe: STM32/Nucleo debug probe support via probe-rs

Sources: src/tools/mod.rs:14-16, Cargo.toml:145-158

Tool Implementation Checklist

When implementing a new tool:

Create tool module in src/tools/
Implement Tool trait with all five methods
Define JSON Schema for parameters with descriptions
Add security checks (autonomy level, rate limiting, path validation)
Handle errors gracefully (return ToolResult with error field, never panic)
Add unit tests (schema validation, security enforcement, parameter validation)
Export from mod.rs and add to appropriate factory function
Document in README under Architecture table and Features section

Sources: src/tools/traits.rs, src/tools/mod.rs:1-62, src/tools/mod.rs:88-238

Home

08 Tools

Tools

Purpose and Scope

Tool Architecture

Tool Trait Interface

Tool Registry Factory

Core Tool Categories

File and Shell Operations

Memory Management Tools

Cron and Scheduling Tools

Git Operations

Browser and HTTP Tools

Browser Automation Backends

HTTP Request Tool

Web Search Tool

Integration Tools

Composio Multi-App Integration

Delegation Tool (Sub-Agent Orchestration)

Notification Tool

Proxy Configuration Tool

Vision Tools

Tool Execution Flow

Tool Parameter Validation

Tool Testing Strategy

Hardware Tools

Tool Implementation Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!