> ## 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.

# 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.

```json theme={null}
{
  "message": "hello world"
}
```

**Domain**: Orchestrator\
**Approval**: Never\
**Rate Limit**: None

### time

**Location**: `src/tools/builtin/time.rs`

Returns current timestamp and timezone information.

```json theme={null}
{}
```

Returns:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "path": "src",
  "recursive": false,
  "include_hidden": false
}
```

Returns:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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**:

```rust theme={null}
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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "query": "github",
  "type": "wasm",
  "limit": 10
}
```

### tool\_install

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

Install a WASM tool or MCP server.

```json theme={null}
{
  "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).

```json theme={null}
{
  "tool_name": "github"
}
```

### tool\_activate

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

Activate an installed tool.

```json theme={null}
{
  "tool_name": "github"
}
```

### tool\_list

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

List all installed tools.

```json theme={null}
{
  "status": "active"
}
```

### tool\_remove

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

Remove an installed tool.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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:

```rust theme={null}
// 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:

```rust theme={null}
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

<CardGroup cols={2}>
  <Card title="WASM Tools" icon="cube" href="/tools/wasm">
    Build sandboxed tools with WebAssembly
  </Card>

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