Tools - klaw

What are Tools?

Tools are the actions agents can take to interact with the world. They’re how agents read files, execute commands, search the web, and accomplish real tasks. When an agent receives a request, it decides which tools to use, calls them with appropriate parameters, receives the results, and uses that information to continue reasoning or respond to the user.

The Tool-Use Loop

┌──────────────────────────────────────────────────────────┐
│                     AGENT LOOP                            │
│                                                          │
│   User Input ──► LLM Decision ──► Tool Execution ──┐    │
│        ▲                                           │    │
│        │                                           │    │
│        └──────── Result Processing ◄───────────────┘    │
│                                                          │
│                  (Repeat until task complete)            │
└──────────────────────────────────────────────────────────┘

Receive Input

Agent receives a message from the user via a channel.

LLM Decision

The LLM analyzes the request and decides which tool(s) to use.

Tool Execution

klaw executes the tool with the provided parameters (2-minute timeout).

Result Processing

Tool output is formatted and fed back to the LLM.

Continue or Respond

LLM either calls more tools or generates a final response.

Built-in Tools

klaw includes 12 powerful tools out of the box:

Command Execution

bash

Execute shell commands with full system access.

{
  "tool": "bash",
  "input": {
    "command": "git status",
    "timeout": 30000
  }
}

Features:

2-minute default timeout
Working directory preservation
Exit code and output capture
Streaming output for long commands

File Operations

read

Read file contents with line numbers.

{
  "tool": "read",
  "input": {
    "path": "/src/main.go",
    "offset": 0,
    "limit": 100
  }
}

write

Create or overwrite files.

{
  "tool": "write",
  "input": {
    "path": "/src/new.go",
    "content": "package main..."
  }
}

edit

Precise string replacement in files.

{
  "tool": "edit",
  "input": {
    "path": "/src/main.go",
    "old_string": "func old()",
    "new_string": "func new()"
  }
}

glob

Find files by pattern.

{
  "tool": "glob",
  "input": {
    "pattern": "**/*.go",
    "path": "/src"
  }
}

Search

grep

Search file contents with regex.

{
  "tool": "grep",
  "input": {
    "pattern": "func.*Error",
    "path": "/src",
    "type": "go"
  }
}

web_search

Search the internet.

{
  "tool": "web_search",
  "input": {
    "query": "golang context best practices"
  }
}

Web

web_fetch

Fetch and process web content.

{
  "tool": "web_fetch",
  "input": {
    "url": "https://example.com/api/docs",
    "prompt": "Extract the authentication methods"
  }
}

Features:

HTML to markdown conversion
AI-powered content extraction
Redirect handling
15-minute cache

Agent Management

agent_spawn

Create persistent agent bindings for the orchestrator.

{
  "tool": "agent_spawn",
  "input": {
    "name": "researcher",
    "task": "Find best practices for API design"
  }
}

delegate

Spawn an ephemeral sub-agent to handle a task inline. The sub-agent runs independently with its own tool set and returns a text result.

{
  "tool": "delegate",
  "input": {
    "task": "Read all Go files in /src and summarize the architecture",
    "tools": ["read", "glob", "grep"]
  }
}

Features:

Runs inline — result returned directly to the parent agent
Optional tool allowlist to restrict sub-agent capabilities
Custom system prompt and max tokens per sub-agent
Depth-limited nesting (max 3 levels)
5-minute timeout, 30k char output truncation

skill

Install and manage skills.

{
  "tool": "skill",
  "input": {
    "action": "install",
    "name": "docker"
  }
}

Scheduling

cron

Schedule recurring tasks.

{
  "tool": "cron",
  "input": {
    "schedule": "0 9 * * *",
    "task": "Check for security updates"
  }
}

Tool Schema

Each tool defines a JSON schema for its parameters:

type Tool interface {
    // Name returns the tool identifier
    Name() string

    // Description explains what the tool does
    Description() string

    // Schema returns JSON schema for parameters
    Schema() map[string]interface{}

    // Execute runs the tool with given input
    Execute(ctx context.Context, input map[string]interface{}) (string, error)
}

Example Schema (bash)

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "The command to execute"
    },
    "timeout": {
      "type": "integer",
      "description": "Timeout in milliseconds",
      "default": 120000
    },
    "workdir": {
      "type": "string",
      "description": "Working directory for command"
    }
  },
  "required": ["command"]
}

Tool Execution Flow

When an agent calls a tool:

┌─────────────────────────────────────────────────────────────┐
│ Tool Call: bash                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ $ git log --oneline -5                                  │ │
│ └─────────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────────┤
│ Result:                                                     │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ a1b2c3d Fix authentication bug                          │ │
│ │ e4f5g6h Add user dashboard                              │ │
│ │ i7j8k9l Update dependencies                             │ │
│ │ m0n1o2p Initial commit                                  │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Tool Permissions

Control which tools agents can access:

# Agent with limited tools
[agent.restricted]
name = "restricted"
tools = ["read", "glob", "grep"]  # Read-only access

Permission Levels

Level	Tools	Use Case
Read-only	read, glob, grep	Code review, analysis
File ops	+ write, edit	Development
Full	+ bash, web	Automation, devops
Admin	+ agent_spawn, skill	Agent management

Custom Tools

Create custom tools by implementing the Tool interface:

package tools

type MyCustomTool struct{}

func (t *MyCustomTool) Name() string {
    return "my_tool"
}

func (t *MyCustomTool) Description() string {
    return "Does something custom"
}

func (t *MyCustomTool) Schema() map[string]interface{} {
    return map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "input": map[string]interface{}{
                "type":        "string",
                "description": "The input to process",
            },
        },
        "required": []string{"input"},
    }
}

func (t *MyCustomTool) Execute(ctx context.Context, input map[string]interface{}) (string, error) {
    // Your logic here
    return "Result", nil
}

registry := tool.NewRegistry()
registry.Register(&MyCustomTool{})

Tool Output Formatting

Tool results are formatted for LLM consumption:

╭──────────────────────────────────────────╮
│ Tool: bash                               │
│ Command: ls -la /src                     │
├──────────────────────────────────────────┤
│ total 32                                 │
│ drwxr-xr-x  5 user  staff  160 Dec 14    │
│ -rw-r--r--  1 user  staff  1234 Dec 14   │
│ ...                                      │
╰──────────────────────────────────────────╯

Timeouts and Limits

Setting	Default	Description
Tool timeout	2 minutes	Max execution time per tool
Output limit	30,000 chars	Truncation threshold
Concurrent tools	All	Approved tools execute in parallel
Delegate timeout	5 minutes	Max execution time for sub-agents

Override in config:

[tools]
timeout = 300000  # 5 minutes
output_limit = 50000

Best Practices

Minimize bash access

Only grant bash access when truly needed. Use specific file tools when possible.

Set appropriate timeouts

Long-running commands should have explicit timeouts to prevent hanging.

Use working directories

Set workdir to limit file operations to specific directories.

Review tool outputs

Tool outputs are visible in the conversation. Sensitive data may be exposed.

Next Steps

Skills

Compose tools into capability bundles

Custom Tools Guide

Build your own tools

​What are Tools?

​The Tool-Use Loop

​Built-in Tools

​Command Execution

bash

​File Operations

read

write

edit

glob

​Search

grep

web_search

​Web

web_fetch

​Agent Management

agent_spawn

delegate

skill

​Scheduling

cron

​Tool Schema

​Example Schema (bash)

​Tool Execution Flow

​Tool Permissions

​Permission Levels

​Custom Tools

​Tool Output Formatting

​Timeouts and Limits

​Best Practices

​Next Steps

Skills

Custom Tools Guide

What are Tools?

The Tool-Use Loop

Built-in Tools

Command Execution

File Operations

Search

Web

Agent Management

Scheduling

Tool Schema

Example Schema (bash)

Tool Execution Flow

Tool Permissions

Permission Levels

Custom Tools

Tool Output Formatting

Timeouts and Limits

Best Practices

Next Steps