Built-in Tools Reference

Complete reference for IronClaw’s built-in tool set

Built-in tools are implemented in Rust and compiled directly into IronClaw. They provide core functionality for agent operations.

Location: src/tools/builtin/

Core Utility Tools

echo

Location: src/tools/builtin/echo.rs

Echoes back the input message. Useful for testing.

{
  "message": "hello world"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

time

Location: src/tools/builtin/time.rs

Returns current timestamp and timezone information.

{}

Returns:

{
  "timestamp": "2026-03-03T15:30:45Z",
  "unix": 1772783445,
  "timezone": "UTC",
  "formatted": "Tuesday, March 3, 2026 at 3:30 PM"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

json

Location: src/tools/builtin/json.rs

Validates and formats JSON data.

{
  "data": {"any": "json", "value": [1, 2, 3]},
  "format": "pretty"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

HTTP & Web Tools

http

Location: src/tools/builtin/http.rs

Make HTTP requests with credential injection support.

{
  "method": "POST",
  "url": "https://api.example.com/data",
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {API_TOKEN}"
  },
  "body": {"query": "test"},
  "timeout_secs": 30
}

Features:

• Credential placeholder injection ({SECRET_NAME})
• Automatic host-based credential matching
• Integrates with WASM tool credential registry
• Leak detection on responses

Domain: Orchestrator
Approval: UnlessAutoApproved
Rate Limit: 60/min, 1000/hour

Location: src/tools/builtin/http.rs:28-467

web_fetch

Location: src/tools/builtin/web_fetch.rs

Fetch web pages and convert HTML to clean markdown.

{
  "url": "https://example.com/page",
  "include_links": true,
  "timeout_secs": 10
}

Features:

• HTML to Markdown conversion via html2md
• Link preservation
• Configurable timeouts
• User-Agent spoofing

Domain: Orchestrator
Approval: UnlessAutoApproved
Rate Limit: 30/min, 500/hour

File Operations (Container Domain)

read_file

Location: src/tools/builtin/file.rs:26-160

Read file contents from the workspace.

{
  "path": "src/main.rs",
  "encoding": "utf8"
}

Domain: Container
Approval: Never
Rate Limit: None

write_file

Location: src/tools/builtin/file.rs:162-322

Write content to a file in the workspace.

{
  "path": "output.txt",
  "content": "file contents",
  "create_dirs": true,
  "encoding": "utf8"
}

Domain: Container
Approval: UnlessAutoApproved
Rate Limit: 30/min, 500/hour

list_dir

Location: src/tools/builtin/file.rs:324-466

List directory contents with metadata.

{
  "path": "src",
  "recursive": false,
  "include_hidden": false
}

Returns:

{
  "entries": [
    {
      "name": "main.rs",
      "path": "src/main.rs",
      "type": "file",
      "size": 1024,
      "modified": "2026-03-03T10:00:00Z"
    }
  ]
}

Domain: Container
Approval: Never
Rate Limit: None

apply_patch

Location: src/tools/builtin/file.rs:468-693

Apply unified diff patches to files.

{
  "file_path": "src/lib.rs",
  "patch": "--- a/src/lib.rs\n+++ b/src/lib.rs\n@@ -1,3 +1,4 @@\n+use std::io;\n fn main() {\n     println!(\"Hello\");\n }"
}

Domain: Container
Approval: UnlessAutoApproved
Rate Limit: 20/min, 300/hour

Shell Execution

shell

Location: src/tools/builtin/shell.rs

Execute shell commands in the workspace.

{
  "command": "cargo build --release",
  "workdir": "/workspace",
  "timeout_secs": 300,
  "capture_output": true
}

Security:

• Destructive commands require ApprovalRequirement::Always
• Non-destructive commands use ApprovalRequirement::UnlessAutoApproved
• Configurable timeout (default 60s, max 600s)
• Output sanitization

Destructive patterns detected:

const DESTRUCTIVE_PATTERNS: &[&str] = &[
    "rm -rf", "rm -fr", "rm -r",
    "format", "mkfs",
    "dd if=",
    "> /dev/",
    "shutdown", "reboot", "poweroff",
    "iptables -F", "iptables -X",
];

Domain: Container
Approval: Conditional (based on command)
Rate Limit: 30/min, 500/hour

Location: src/tools/builtin/shell.rs:49-500

Memory System

Memory tools provide persistent key-value storage for agents.

memory_write

Location: src/tools/builtin/memory.rs:28-152

Write data to long-term memory.

{
  "key": "user_preferences",
  "value": {"theme": "dark", "language": "en"},
  "ttl_secs": 86400,
  "tags": ["settings", "user"]
}

Domain: Orchestrator
Approval: Never
Rate Limit: 30/min, 1000/hour

memory_read

Location: src/tools/builtin/memory.rs:154-238

Read data from long-term memory.

{
  "key": "user_preferences"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

memory_search

Location: src/tools/builtin/memory.rs:240-357

Search memory entries by tags or key patterns.

{
  "query": "user",
  "tags": ["settings"],
  "limit": 10
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

memory_tree

Location: src/tools/builtin/memory.rs:359-446

List all memory keys in a tree structure.

{
  "prefix": "config/"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

Job Management

Job tools allow agents to create and manage sub-tasks.

create_job

Location: src/tools/builtin/job.rs:64-768

Create a new job (sub-task) for execution.

{
  "description": "Analyze codebase and generate report",
  "instructions": "Read all .rs files and create a summary",
  "context": {"project": "ironclaw"},
  "container": {
    "image": "rust:1.75",
    "workspace_path": "/workspace"
  }
}

Features:

• Creates isolated job context
• Optional Docker container execution
• Job monitoring and event streaming
• Integration with scheduler

Domain: Orchestrator
Approval: UnlessAutoApproved
Rate Limit: 10/min, 100/hour

list_jobs

Location: src/tools/builtin/job.rs:770-863

List all jobs with status.

{
  "status": "running",
  "limit": 10
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

job_status

Location: src/tools/builtin/job.rs:865-950

Get detailed status of a specific job.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

cancel_job

Location: src/tools/builtin/job.rs:952-1034

Cancel a running job.

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason": "User requested cancellation"
}

Domain: Orchestrator
Approval: Never
Rate Limit: None

Extension Management

Extension tools allow agents to install and manage WASM tools and MCP servers.

tool_search

Location: src/tools/builtin/extension_tools.rs:28-150

Search for available tools in the marketplace.

{
  "query": "github",
  "type": "wasm",
  "limit": 10
}

tool_install

Location: src/tools/builtin/extension_tools.rs:152-320

Install a WASM tool or MCP server.

{
  "source": "https://tools.ironclaw.dev/github-tool.wasm",
  "name": "github",
  "auto_activate": true
}

tool_auth

Location: src/tools/builtin/extension_tools.rs:322-450

Authenticate a tool (OAuth or manual token entry).

{
  "tool_name": "github"
}

tool_activate

Location: src/tools/builtin/extension_tools.rs:452-520

Activate an installed tool.

{
  "tool_name": "github"
}

tool_list

Location: src/tools/builtin/extension_tools.rs:522-600

List all installed tools.

{
  "status": "active"
}

tool_remove

Location: src/tools/builtin/extension_tools.rs:602-680

Remove an installed tool.

{
  "tool_name": "github",
  "force": false
}

Skill Management

Skill tools manage prompt-level skills (specialized agent behaviors).

skill_list

Location: src/tools/builtin/skill_tools.rs:28-120

List installed skills.

skill_search

Location: src/tools/builtin/skill_tools.rs:122-230

Search for available skills.

skill_install

Location: src/tools/builtin/skill_tools.rs:232-350

Install a skill from the catalog.

skill_remove

Location: src/tools/builtin/skill_tools.rs:352-420

Remove an installed skill.

Routine Management

Routine tools manage scheduled and event-driven tasks.

routine_create

Location: src/tools/builtin/routine.rs:28-200

Create a new routine.

{
  "name": "daily_report",
  "schedule": "0 9 * * *",
  "action": "create_job",
  "params": {"description": "Generate daily report"}
}

routine_list

Location: src/tools/builtin/routine.rs:202-280

List all routines.

routine_update

Location: src/tools/builtin/routine.rs:282-400

Update a routine configuration.

routine_delete

Location: src/tools/builtin/routine.rs:402-470

Delete a routine.

routine_history

Location: src/tools/builtin/routine.rs:472-550

View routine execution history.

Message Tool

message

Location: src/tools/builtin/message.rs

Send messages to communication channels.

{
  "channel": "slack",
  "target": "#engineering",
  "text": "Build completed successfully",
  "metadata": {"build_id": "123"}
}

Features:

• Per-turn context setting (default channel/target)
• Multi-channel support
• Metadata attachment

Domain: Orchestrator
Approval: UnlessAutoApproved
Rate Limit: 30/min, 500/hour

Software Builder

build_software

Location: src/tools/builder/core.rs

Build software using LLM-driven code generation.

{
  "requirement": "Create a WASM tool that checks GitHub PR status",
  "software_type": "wasm_tool",
  "language": "rust",
  "output_path": "/workspace/github-pr-tool",
  "test_cases": [
    {"input": "owner=rust-lang repo=rust pr=12345", "expected": "status: open"}
  ]
}

Supported types:

• wasm_tool - Sandboxed WASM tools
• cli_app - Command-line applications
• library - Reusable libraries
• script - Single-file scripts

Domain: Container
Approval: Always
Rate Limit: 5/min, 20/hour

Helper Functions

The tool module provides helper functions for parameter extraction:

// Extract required string parameter
pub fn require_str<'a>(params: &'a Value, name: &str) -> Result<&'a str, ToolError>

// Extract required parameter of any type
pub fn require_param<'a>(params: &'a Value, name: &str) -> Result<&'a Value, ToolError>

Location: src/tools/tool.rs:268-288

Example usage:

async fn execute(&self, params: Value, ctx: &JobContext) -> Result<ToolOutput, ToolError> {
    let path = require_str(&params, "path")?;
    let content = require_str(&params, "content")?;
    
    // ... implementation
}

Next Steps

WASM Tools

Build sandboxed tools with WebAssembly

MCP Integration

Connect external tool servers