Tools

Tool Reference

Overview

fiz runs an agent loop that lets the language model call built-in tools to read the filesystem, run shell commands, search code, and edit files. Each tool has a JSON Schema; the schema is what the model sees when it decides which tool to invoke and with what arguments. Tool results stream back into the conversation as the next turn’s context.

The tool set is gated by the active prompt preset. Different presets optimize for different cost/capability tradeoffs (see the CLI reference for --preset). Today every preset bundles the same registry, but the matrix below is regenerated from source so it stays accurate as that changes.

To add a new tool, edit internal/tool/builtin.go and append it to the slice returned by BuiltinToolsForPreset. The next make docs-tools run will pick it up.

Preset matrix

The columns are presets; the rows are tool names. An x means the preset includes the tool; — means it does not.

Tool	default	smart	cheap	minimal
`bash`	x	x	x	x
`edit`	x	x	x	x
`find`	x	x	x	x
`grep`	x	x	x	x
`ls`	x	x	x	x
`patch`	x	x	x	x
`read`	x	x	x	x
`task`	x	x	x	x
`write`	x	x	x	x

Tools

bash

Execute a shell command for targeted repo operations such as builds, tests, or git. Do not use this for file discovery or file reading; use the find, grep, ls, and read tools instead. Returns stdout, stderr, and exit code.

Parallel-safe: no

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "Shell command to execute"
    },
    "timeout_ms": {
      "type": "integer",
      "description": "Timeout in milliseconds (default 120000)"
    }
  },
  "required": [
    "command"
  ]
}

edit

Make targeted edits to a file using exact string replacement.

Parallel-safe: no

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "path": {
      "type": "string",
      "description": "File path (relative to working directory or absolute)"
    },
    "edits": {
      "type": "array",
      "description": "One or more targeted replacements. Each edit is matched against the original file, not incrementally. Do not include overlapping or nested edits. If two changes touch the same block or nearby lines, merge them into one edit instead.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "oldText",
          "newText"
        ],
        "properties": {
          "oldText": {
            "type": "string",
            "description": "Exact text to find (must be unique in the file and must not overlap with other edits)"
          },
          "newText": {
            "type": "string",
            "description": "Replacement text"
          }
        }
      }
    },
    "old_string": {
      "type": "string",
      "description": "Legacy: exact string to find (use edits[] instead)"
    },
    "new_string": {
      "type": "string",
      "description": "Legacy: replacement string (use edits[] instead)"
    }
  },
  "required": [
    "path"
  ]
}

find

Find files by path pattern. Use this instead of shell find or ls when locating files by name.

Parallel-safe: yes

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "description": "Path pattern to match (e.g. '**/*.go', 'cmd/**/main.go'). Use ** to match across directories."
    },
    "dir": {
      "type": "string",
      "description": "Directory to search in (relative to working directory or absolute; defaults to working directory)"
    },
    "exclude_dirs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Override default excluded directories. By default, skips .git, .hg, .svn, node_modules, and vendor/. Set to empty array [] to search all directories."
    }
  },
  "required": [
    "pattern"
  ]
}

grep

Search file contents for a regex pattern. Use instead of grep/rg shell commands.

Parallel-safe: yes

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "description": "Regular expression to search for"
    },
    "dir": {
      "type": "string",
      "description": "Directory to search in (relative or absolute; defaults to working directory)"
    },
    "glob": {
      "type": "string",
      "description": "Restrict to files whose base names match this glob (e.g. '*.go', '*.ts')"
    },
    "case_insensitive": {
      "type": "boolean",
      "description": "Case-insensitive matching (default false)"
    },
    "exclude_dirs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Override default excluded directories. By default, skips .git, .hg, .svn, node_modules, and vendor/. Set to empty array [] to search all directories."
    }
  },
  "required": [
    "pattern"
  ]
}

ls

List directory contents. Use instead of ls.

Parallel-safe: yes

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Directory to list (relative to working directory or absolute; defaults to working directory)"
    }
  }
}

patch

Make targeted edits to a file. Supports: replace (default), replace_all, prepend, and append operations.

Parallel-safe: no

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "path": {
      "type": "string",
      "description": "File path (relative to working directory or absolute)"
    },
    "search": {
      "type": "string",
      "description": "Exact text to find in the file. Must match exactly (including whitespace). Will match first occurrence."
    },
    "content": {
      "type": "string",
      "description": "Replacement text, or text to prepend/append"
    },
    "operation": {
      "type": "string",
      "description": "One of: 'replace' (default, search must be unique), 'replace_all' (replace every occurrence), 'prepend' (insert at file start), 'append' (insert at file end)",
      "enum": [
        "replace",
        "replace_all",
        "prepend",
        "append"
      ]
    }
  },
  "required": [
    "path",
    "content"
  ]
}

read

Read file contents. Use instead of cat/head/tail.

Parallel-safe: yes

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "File path (relative to working directory or absolute)"
    },
    "offset": {
      "type": "integer",
      "description": "0-based line offset to start reading from"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of lines to return"
    }
  },
  "required": [
    "path"
  ]
}

task

Track subtasks in a multi-step plan: create, update, get, list.

Parallel-safe: no

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "operation": {
      "type": "string",
      "enum": [
        "create",
        "update",
        "get",
        "list"
      ],
      "description": "The operation to perform"
    },
    "id": {
      "type": "string",
      "description": "Task ID (required for update/get, ignored for create/list)"
    },
    "title": {
      "type": "string",
      "description": "Task title (required for create)"
    },
    "description": {
      "type": "string",
      "description": "Optional task description"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "completed"
      ],
      "description": "New status (required for update)"
    }
  },
  "required": [
    "operation"
  ]
}

write

Create or overwrite a file with the given content. Creates parent directories as needed.

Parallel-safe: no

Parameter schema (JSON Schema, validated by the provider before the call reaches Execute):

{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "File path (relative to working directory or absolute)"
    },
    "content": {
      "type": "string",
      "description": "Content to write to the file"
    }
  },
  "required": [
    "path",
    "content"
  ]
}

Adding a new tool

Implement the agent.Tool interface in internal/tool/. The contract is Name(), Description(), Schema() json.RawMessage, Execute(ctx, params) (string, error), and Parallel() bool.
Register it in internal/tool/builtin.go so it ships with the relevant preset(s).
Run make docs-tools to regenerate this page.