Skip to main content
Operator OS agents reason and act through tools. When the LLM decides it needs to take an action — run a command, read a file, search the web, or delegate to another agent — it emits a tool call. The runtime dispatches that call to the matching tool, executes it, and feeds the result back into the conversation. No plumbing code is required in your agent definition. Tools are registered in a ToolRegistry at startup. Each tool exposes a name, a plain-English description, and a JSON Schema for its parameters; this is what the LLM sees when it decides which tool to invoke.
MCP tools and installed Skills tools are added to the same registry automatically when their servers connect or their packages are loaded. The agent cannot tell the difference between a built-in tool and an MCP or Skills tool.

​
Tool categories

Shell

Run arbitrary shell commands inside the agent workspace with configurable safety guards.

Filesystem

Read, write, edit, and list files and directories within the workspace boundary.

Web

Search the web via Brave, DuckDuckGo, or Perplexity, and fetch full page content.

Scheduling

Schedule one-off or recurring tasks using cron expressions or relative intervals.

Agents

Spawn sub-agents to execute tasks independently and report results back asynchronously.

Messaging

Send messages to users across any configured channel (Telegram, Discord, Slack, etc.).

Hardware I/O

Communicate with I2C and SPI bus peripherals directly from agent logic. Linux only.

MCP & Skills

Extend the agent with external MCP servers or installable Skill packages from ClawHub.

​
Shell

ToolDescription
execExecute a shell command in the agent workspace.
The exec tool runs commands through the host shell and returns combined stdout/stderr. It enforces a deny-list of dangerous patterns by default (destructive deletes, privilege escalation, remote execution pipes, etc.) and optionally restricts commands to paths inside the workspace. 
{
  "tools": {
    "exec": {
      "enable_deny_patterns": true,
      "custom_deny_patterns": ["\\brm\\s+-r\\b", "\\bkillall\\s+python"]
    }
  }
}
​
enable_deny_patterns
boolean
default:"true"
When true, a built-in set of regex patterns blocks destructive commands such as rm -rf, sudo, docker run, git push, and pipe-to-shell constructs. Set to false to disable all default blocking.
​
custom_deny_patterns
array
Additional regular expressions to block. Commands matching any pattern are rejected before execution.

​
Filesystem

ToolDescription
read_fileRead the full contents of a file.
write_fileWrite content to a file (creates or overwrites).
edit_fileReplace an exact substring inside a file without rewriting the whole thing.
list_dirList files and subdirectories at a given path.
All filesystem tools share a workspace-restriction flag. When restriction is enabled, any path that resolves — including through symlinks — outside the workspace root is rejected with an access-denied error.

​
Web

ToolDescription
web_searchSearch the web and return a ranked list of results (title, URL, snippet).
web_fetchFetch a URL and return the extracted text content of the page.
Three search providers are supported. At least one must be enabled for web_search to function. web_fetch works independently of any provider.
Free, no API key required. Enabled by default.
{
  "tools": {
    "web": {
      "duckduckgo": {
        "enabled": true,
        "max_results": 5
      }
    }
  }
}
​
enabled
boolean
default:"true"
Enable DuckDuckGo search.
​
max_results
integer
default:"5"
Maximum number of search results returned per query.
You can enable multiple providers simultaneously. The agent selects the provider that best fits the context, or you can guide it via the system prompt.
An optional proxy field is available under tools.web for routing all web requests through an HTTP/SOCKS proxy: 
{
  "tools": {
    "web": {
      "proxy": "http://127.0.0.1:7890"
    }
  }
}

​
Scheduling

ToolDescription
cronSchedule a one-off reminder, a recurring task, or a shell command on a cron expression.
The cron tool accepts three scheduling modes:
  • at_seconds — run once after N seconds (e.g. at_seconds: 600 for “in 10 minutes”)
  • every_seconds — repeat every N seconds (e.g. every_seconds: 3600 for “every hour”)
  • cron_expr — a standard cron expression for complex schedules (e.g. "0 9 * * 1-5" for weekday mornings)
{
  "tools": {
    "cron": {
      "exec_timeout_minutes": 5
    }
  }
}
​
exec_timeout_minutes
integer
default:"5"
Maximum runtime for shell commands triggered by a cron job. Set to 0 for no limit.

​
Agent delegation

ToolDescription
spawnSpawn a sub-agent to handle a task in the background. Returns immediately; the sub-agent reports back when done.
The spawn tool delegates work to a separate agent instance. It accepts a task description, an optional label for display purposes, and an optional agent_id to route the task to a specific named agent. Sub-agents run asynchronously. The parent agent receives a completion callback once the sub-agent finishes and can continue its own work in the meantime.

​
Messaging

ToolDescription
messageSend a message to the user on a chat channel.
The message tool posts content back to the originating channel (Telegram, Discord, Slack, etc.) and optionally to a different channel or chat ID. The agent uses this tool whenever it wants to communicate proactively rather than waiting for the next turn.

​
Hardware I/O

Hardware tools are only registered on Linux hosts. They are intended for edge deployments where the agent runs directly on embedded or IoT hardware.
ToolDescription
i2cInteract with I2C bus devices: detect buses, scan for devices, read bytes, write bytes.
spiInteract with SPI bus devices: list devices, perform full-duplex transfers, read bytes.
Write operations on i2c and spi require explicit confirmation ("confirm": true) as a safety guard against accidental peripheral writes.

​
MCP tools

When MCP is enabled and servers are connected, each tool exposed by a connected server is registered automatically as mcp_<server>_<tool>. The agent can call these tools exactly like any built-in tool. See Model Context Protocol for configuration details.

​
Skills tools

Installed skills can contribute additional tools to the registry. After a skill is installed, the agent gains access to all tools the skill provides. See Skills for how to discover and install skills from ClawHub.

Build docs developers (and LLMs) love

Get started for freeTalk to us