Tools API Reference

UltraSushiTron ships with 11 built-in tools. Each tool is defined in Rust and exposed to the LLM as a callable function with a JSON schema.

Tool Interface

All tools implement the Tool trait:

core/src/tools/mod.rs rust

pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn parameters_schema(&self) -> serde_json::Value;
    fn execute(&self, arguments: &str) -> Result<String>;
}

Read

Read a file from the filesystem. Returns contents with line numbers. Lines longer than 2,000 characters are truncated. Default limit is 2,000 lines.

Parameters

Name	Type	Required	Description
`file_path`	`string`	Yes	Absolute path to the file to read
`offset`	`integer`	No	Line number to start reading from (1-based)
`limit`	`integer`	No	Maximum number of lines to read (default: 2000)

Example json

{
  "file_path": "/home/user/project/src/main.rs",
  "offset": 10,
  "limit": 50
}

Write

Write content to a file, creating parent directories as needed. Overwrites existing files.

Parameters

Name	Type	Required	Description
`file_path`	`string`	Yes	Absolute path to the file to write
`content`	`string`	Yes	The content to write to the file

Example json

{
  "file_path": "/home/user/project/config.toml",
  "content": "[server]\nport = 8080\nhost = \"0.0.0.0\""
}

Edit

Perform exact string replacements in a file. Finds old_string and replaces it with new_string. Set replace_all to true to replace every occurrence.

Parameters

Name	Type	Required	Description
`file_path`	`string`	Yes	Absolute path to the file to edit
`old_string`	`string`	Yes	The exact text to find and replace
`new_string`	`string`	Yes	The replacement text
`replace_all`	`boolean`	No	Replace all occurrences (default: false)

Example json

{
  "file_path": "/home/user/project/src/lib.rs",
  "old_string": "fn old_name()",
  "new_string": "fn new_name()",
  "replace_all": true
}

Bash

Execute a bash command with an optional timeout. Default timeout is 120 seconds (max 600s). Output is capped at 30,000 bytes.

Parameters

Name	Type	Required	Description
`command`	`string`	Yes	The bash command to execute
`timeout`	`integer`	No	Timeout in seconds (default: 120, max: 600)

Example json

{
  "command": "cargo test --release",
  "timeout": 300
}

Grep

Search file contents using regular expressions. Supports output modes: 'content' (matching lines), 'files' (file paths only), 'count' (match counts).

Parameters

Name	Type	Required	Description
`pattern`	`string`	Yes	Regular expression pattern to search for
`path`	`string`	No	Directory or file to search in (default: current dir)
`output_mode`	`string`	No	'content', 'files', or 'count' (default: 'content')

Example json

{
  "pattern": "fn\\s+execute",
  "path": "/home/user/project/src",
  "output_mode": "files"
}

Find

Search for files using glob patterns. Returns up to 200 matching file paths sorted by modification time.

Parameters

Name	Type	Required	Description
`pattern`	`string`	Yes	Glob pattern (e.g., '*/.rs', 'src/*/.toml')
`path`	`string`	No	Base directory to search from (default: current dir)

Example json

{
  "pattern": "**/*.proto",
  "path": "/home/user/project"
}

HttpFetch

Fetch content from a URL. Includes SSRF protection (blocks private/reserved IPs). Response body is capped at 100KB. Supports HTML stripping.

Parameters

Name	Type	Required	Description
`url`	`string`	Yes	The URL to fetch
`method`	`string`	No	HTTP method: GET, POST, PUT, DELETE (default: GET)
`headers`	`object`	No	HTTP headers as key-value pairs
`body`	`string`	No	Request body (for POST/PUT)
`strip_html`	`boolean`	No	Strip HTML tags from response (default: false)

Example json

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "headers": { "Accept": "application/json" },
  "strip_html": false
}

WebSearch

Search the web using DuckDuckGo. Returns up to 10 results with titles, URLs, and snippets.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	The search query
`num_results`	`integer`	No	Number of results (default: 5, max: 10)

Example json

{
  "query": "Rust async runtime comparison 2024",
  "num_results": 5
}

Diff

Compare two files or two text strings and produce a unified diff. Specify either file paths or text content.

Parameters

Name	Type	Required	Description
`file_a`	`string`	No	Path to the first file
`file_b`	`string`	No	Path to the second file
`text_a`	`string`	No	First text content (alternative to file_a)
`text_b`	`string`	No	Second text content (alternative to file_b)
`context_lines`	`integer`	No	Lines of context around changes (default: 3)

Example json

{
  "file_a": "/home/user/old_config.toml",
  "file_b": "/home/user/new_config.toml",
  "context_lines": 5
}

Patch

Apply a unified diff patch to a file. Supports dry-run mode to preview changes without modifying the file.

Parameters

Name	Type	Required	Description
`file_path`	`string`	Yes	Path to the file to patch
`patch`	`string`	Yes	Unified diff content to apply
`dry_run`	`boolean`	No	Preview changes without writing (default: false)

Example json

{
  "file_path": "/home/user/project/src/main.rs",
  "patch": "--- a/main.rs\n+++ b/main.rs\n@@ -1,3 +1,3 @@\n fn main() {\n-    println!(\"old\");\n+    println!(\"new\");\n }",
  "dry_run": true
}

ListDir

List directory contents as a tree. Skips common non-essential directories (.git, node_modules, target). Supports depth limit and hidden files.

Parameters

Name	Type	Required	Description
`path`	`string`	Yes	Directory path to list
`depth`	`integer`	No	Maximum depth to recurse (default: 2)
`show_hidden`	`boolean`	No	Include hidden files/dirs (default: false)

Example json

{
  "path": "/home/user/project",
  "depth": 3,
  "show_hidden": false
}