Reference: Tool Schemas

What this page is

Every built-in tool in internal/tools/builtin/*.go publishes an InputSchema() method that returns a JSON Schema map. This page reproduces those schemas exactly, plus one paragraph on each tool's runtime contract.

The five built-in tools are: read, write, edit, grep, bash. All five are constructed in the daemon wiring; the approver (internal/agent/approver.go) sits between the model's tool call and the tool's Execute method.

read

Source: internal/tools/builtin/read.go.

Description (surfaced to the model): Read the contents of a UTF-8 text file. Input: absolute path. Returns file contents or an error.

Input schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute filesystem path to the file to read."
    }
  },
  "required": ["path"]
}

Contract. The path must be absolute (filepath.IsAbs). The tool reads the whole file into memory and rejects it if the first 512 bytes contain a NUL byte (isLikelyText). Returns the file contents as a string on success; an error otherwise. No line-count or size limit is enforced at the tool level — approval policies are the right place to bound file sizes.

write

Source: internal/tools/builtin/write.go.

Description (surfaced to the model): Write UTF-8 text to a file, replacing existing contents. Creates parent directories as needed. Input: absolute path + content.

Input schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute filesystem path to write."
    },
    "content": {
      "type": "string",
      "description": "The complete file contents to write."
    }
  },
  "required": ["path", "content"]
}

Contract. Full-file overwrite. Creates parent directories with mode 0o755. Writes with mode 0o644. Absolute path required. Returns "wrote N bytes to /path". There is deliberately no atomic-swap dance — pattern-mode approvers pin the write target to a specific directory tree; the tool itself does not try to be clever about filesystem safety.

edit

Source: internal/tools/builtin/edit.go.

Description (surfaced to the model): Replace exactly one occurrence of old_string with new_string in a file. old_string must be unique in the file; if it appears zero or multiple times the edit fails. Preserve indentation exactly.

Input schema:

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Absolute filesystem path to the file to edit."
    },
    "old_string": {
      "type": "string",
      "description": "Exact text to find. Must be unique in the file."
    },
    "new_string": {
      "type": "string",
      "description": "Text to replace old_string with."
    }
  },
  "required": ["path", "old_string", "new_string"]
}

Contract. Exact-string replacement, not regex. old_string must appear exactly once in the file — zero matches or multiple matches both fail with a descriptive error, which is intentional (borrowed from Claude Code's Edit tool). Prevents accidental mass-replace and forces the model to include enough surrounding context to disambiguate. old_string == new_string also errors. Returns "edited /path (1 replacement)".

grep

Source: internal/tools/builtin/grep.go.

Description (surfaced to the model): Search files under a directory for a Go regular expression. Skips binary files and files larger than the configured limit. Returns 'path:line: matched_line' rows.

Input schema:

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "description": "Go RE2 regular expression to match."
    },
    "path": {
      "type": "string",
      "description": "Absolute directory to search under."
    },
    "include": {
      "type": "string",
      "description": "Optional filename glob (e.g. '*.go'). Applied to the base name."
    },
    "ignore_case": {
      "type": "boolean",
      "description": "Case-insensitive match. Defaults to false."
    }
  },
  "required": ["pattern", "path"]
}

Contract. RE2 regex, not PCRE. Case-insensitive when ignore_case: true (implemented by prefixing (?i)). Skips directories named .git, node_modules, vendor, .venv, __pycache__, dist, build. Skips files larger than MaxFileBytes (default 4 MiB). Truncates output at MaxMatches (default 200) and appends a (truncated at N matches) footer when it hits the cap. Skips files that contain a NUL byte on the current line (rough binary detection).

bash

Source: internal/tools/builtin/bash.go.

Description (surfaced to the model): Execute a shell command via /bin/sh -c. Returns combined stdout+stderr with exit status.

Input schema:

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "The shell command to execute."
    }
  },
  "required": ["command"]
}

Contract. /bin/sh -c <command>. Combined stdout + stderr, capped at whatever fits in a bytes.Buffer (i.e. RAM). 60-second timeout by default (configurable at construction). On timeout: returns partial output plus a bash: timed out after 60s error. No sandboxing at the tool level. The daemon's OS user, filesystem view, network posture, and seccomp profile are the containment. Pattern-mode approvers are how you narrow the allowed commands — see Tutorial: Harden the approver.

MCP-exposed tools

Rousseau's stdio MCP server (rousseau mcp) exposes a different set of tools — read-only queries against the session store and cron jobs. See MCP: Exposed tools for rousseau_search_sessions, rousseau_list_sessions, rousseau_read_session, rousseau_cron_list.

Related

• User Guide: Tools — the operator-facing view.
• Guides: File management — how write/edit interact with bind mounts and SELinux.
• Guides: Audit + approval policies — how pattern regexes constrain each tool's input.
• Developer Guide: Add a tool — extend this set.