Tool Reference
The tool catalog is sent to the provider as structured tool schemas. Tool names and input fields are part of the user-visible contract, but output may be capped or summarized for the transcript.
The public catalog is derived from the built-in tool registry in thndrs_core::tools.
Schema descriptions and examples below should match the tool modules that parse and execute them.
Configured MCP tools are appended to the same provider catalog at runtime. They are
always namespaced as mcp__{server}__{tool} so external tools cannot replace built-in tool names.
Session records keep both the configured server name and the original MCP tool name for inspection.
MCP definitions come from server tools/list responses.
Their JSON input schemas are passed through to the provider under the namespaced tool name, and tool-call results are converted back into the agent’s domain model.
find_files
Section titled “find_files”Locate files by name or glob under the workspace root.
Inputs:
pattern: file name or glob pattern.glob: optional additional glob filter.extensions: optional extension filter.max_depth: optional traversal depth.include_hidden: include hidden files.follow_symlinks: follow symlinks.
Hidden files and symlinks are off by default. Results are capped.
list_searchable_files
Section titled “list_searchable_files”Enumerate files that are reasonable candidates for content search.
Inputs:
glob: optional glob filter.include_hidden: include hidden files.
Prefer find_files when the target name is known and search_text when the
target content is known.
search_text
Section titled “search_text”Search file contents with a regex and return file:line:text matches.
Inputs:
pattern: regex pattern.glob: optional glob filter.extensions: optional extension filter.context_lines: optional surrounding line count.include_hidden: include hidden files.
rg exit code 1 is treated as no matches. Matches and line length are capped.
read_file_range
Section titled “read_file_range”Read a 1-indexed line range from a file.
Inputs:
path: path relative to the workspace root.start_line: first line to read.end_line: optional final line.
Prefer targeted ranges over reading large files.
web_search
Section titled “web_search”Search the web for current information when the workspace does not contain the answer.
Inputs:
query: search query.max_results: optional result cap.
Search uses the configured application-owned backend (duckduckgo, searxng,
or none). Results are capped, normalized, and followed by best-effort
Lectito extraction of public result URLs. Private result URLs are reported as
per-result extraction failures.
read_url
Section titled “read_url”Fetch a public http or https URL and extract readable text.
Inputs:
url: public URL to fetch.
Private-network targets, unsupported schemes, binary content, oversized responses, and redirect chains beyond the configured limit are rejected.
create_file
Section titled “create_file”Create a new file with full content.
Inputs:
path: path relative to the workspace root.content: full file content.
The tool fails if the file already exists and creates parent directories when needed. It writes the complete content to a same-directory temporary file before installation, so a failed create leaves no partial target. If a target appears after validation, the no-clobber install fails instead of overwriting it.
replace_range
Section titled “replace_range”Replace one unique exact string occurrence in an existing file.
Inputs:
path: path relative to the workspace root.old_string: exact string to find.new_string: replacement string.
The edit fails if old_string appears zero or multiple times. Failed edits
leave the file unchanged.
The write is assembled in a same-directory temporary file and installed only after the complete content is synchronized.
Target permissions are preserved where the platform exposes them.
write_patch
Section titled “write_patch”Unified write entry point for create, replace, and exact edit operations.
Inputs:
patches: non-empty array of patch objects.
Each patch contains:
op:create,replace, oredit.path: path relative to the workspace root.content: full content, required forcreateandreplace.old_string: exact string, required foredit.new_string: replacement string, required foredit.expected_before_hash: optional stale-content guard foreditandreplace.
Use edit for small exact replacements, create for new files, and replace
only when overwriting the full file is intentional. A call may contain one
create or replace patch, or one or more edit patches for the same file.
Every edit matches the original file content. The tool validates the full batch
before writing, so a failed batch leaves the file unchanged. Writes use a
same-directory temporary file and a final install after the content is
synchronized. create never clobbers a target that appears during validation.
run_shell
Section titled “run_shell”Run a local program in the workspace and capture stdout, stderr, status, and timing.
Inputs:
argv: non-empty array containing the program followed by its arguments.cwd: optional working directory relative to the workspace root.timeout_ms: optional timeout in milliseconds.background: start a long-lived process owned by the interactive application and return immediately with its process id.
Commands run as the local thndrs process, not in a sandbox. Output is capped,
truncated, and redacted where deterministic redaction is possible. Use :bg
to list live background processes and :bg cancel <id> to cancel one. Quitting
the TUI cancels and reaps every owned background child. A background start is
recorded as running. A later shell_exec record records its terminal
ok, failed, timeout, or cancelled state.
Side-Effect Records
Section titled “Side-Effect Records”Every tool call has a tool_started and tool_finished session record. Write
tools also append file_write audit metadata with operation, path, hashes, byte
counts, and status. run_shell also appends shell_exec metadata with command,
working directory, optional process id, process kind, exit status, elapsed time,
and cancellation or background state.
Background commands append one start record and one terminal record. Full file contents and uncapped stdout/stderr are not stored in those side-effect records.
MCP tool output follows the same transcript/session limits as built-in tool output: lines and bytes are capped, deterministic secret redaction is applied, timeouts become stable tool failures, and failed calls still append normal tool start/finish records.