Tools
OpenCrust's agent runtime gives the LLM access to built-in tools and dynamically registered MCP tools. When the LLM decides to use a tool, the runtime executes it and feeds the result back into the conversation.
Tool Loop
The agent processes each message through a tool loop that runs for up to 10 iterations. In each iteration:
- The LLM generates a response, optionally including tool calls
- If tool calls are present, the runtime executes them
- Tool results are appended to the conversation and sent back to the LLM
- The loop continues until the LLM responds without tool calls or the iteration limit is reached
Built-in Tools
bash
Execute shell commands. Uses bash -c on Unix and powershell -Command on Windows.
| Property | Value |
|---|---|
| Timeout | 30 seconds |
| Max output | 32 KB (truncated if exceeded) |
Input:
{ "command": "ls -la /tmp" }
Both stdout and stderr are captured. Stderr is prefixed with STDERR: in the output. Non-zero exit codes are reported as errors.
file_read
Read the contents of a file.
| Property | Value |
|---|---|
| Max file size | 1 MB |
| Path traversal | Rejected (.. components blocked) |
Input:
{ "path": "/home/user/notes.txt" }
Files exceeding the size limit return an error rather than truncating.
file_write
Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Parent directories are created automatically.
| Property | Value |
|---|---|
| Max content size | 1 MB |
| Path traversal | Rejected (.. components blocked) |
Input:
{ "path": "/home/user/output.txt", "content": "Hello, world!" }
web_fetch
Fetch the content of a web page. Returns the raw response body (HTML, JSON, plain text).
| Property | Value |
|---|---|
| Timeout | 30 seconds |
| Max response size | 1 MB (truncated if exceeded) |
Input:
{ "url": "https://example.com" }
Non-2xx HTTP status codes are reported as errors. An optional blocked_domains list can be configured to restrict which domains the agent can access.
web_search
Search the web using the Brave Search API. Only available when a Brave API key is configured.
| Property | Value |
|---|---|
| Timeout | 15 seconds |
| Default results | 5 |
| Max results | 10 |
| Requires | BRAVE_API_KEY |
Input:
{ "query": "rust async runtime comparison", "count": 5 }
The count parameter is optional (defaults to 5, clamped to 1-10). Results are returned as formatted markdown with title, snippet, and URL for each result.
The tool is only registered at startup if a Brave API key is found (config key brave or env var BRAVE_API_KEY).
schedule_heartbeat
Schedule a future wake-up for the agent. Useful for reminders, follow-ups, or checking back on long-running tasks.
| Property | Value |
|---|---|
| Max delay | 30 days (2,592,000 seconds) |
| Max pending per session | 5 |
Input:
{ "delay_seconds": 3600, "reason": "Check if the deployment finished" }
The delay must be a positive integer. Heartbeats cannot be scheduled from within a heartbeat execution context (no recursive self-scheduling). The scheduled task is stored in SQLite and the scheduler polls for due tasks.
MCP Tools
In addition to built-in tools, the agent can use tools from connected MCP servers. MCP tools are discovered at startup and registered with namespaced names in the format server.tool_name.
For example, a filesystem MCP server named fs exposing a read_file tool would appear as fs.read_file.
MCP tools have the same interface as built-in tools from the LLM's perspective - they receive JSON input and return text output.
See MCP for configuration details.