Chapter 8
Tools
Complete reference for built-in tool interfaces. Use these when configuring tool permissions or building custom integrations.
Bash
Executes bash commands in a persistent shell session with optional timeout and background execution.
| Property | Type | Required | Description |
|---|---|---|---|
command | string | Yes | The command to execute |
timeout | number | No | Optional timeout in milliseconds (max 600000) |
description | string | No | Clear, concise description of what this command does in 5-10 words |
run_in_background | boolean | No | Set to true to run this command in the background |
BashOutput
Retrieves output from a running or completed background bash shell.
| Property | Type | Required | Description |
|---|---|---|---|
bash_id | string | Yes | The ID of the background shell to retrieve output from |
filter | string | No | Optional regex to filter output lines |
Edit
Performs exact string replacements in files.
| Property | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | The absolute path to the file to modify |
old_string | string | Yes | The text to replace |
new_string | string | Yes | The text to replace it with (must be different from old_string) |
replace_all | boolean | No | Replace all occurrences of old_string (default false) |
Read
Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks.
| Property | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | The absolute path to the file to read |
offset | number | No | The line number to start reading from |
limit | number | No | The number of lines to read |
Write
Writes a file to the local filesystem, overwriting if it exists.
| Property | Type | Required | Description |
|---|---|---|---|
file_path | string | Yes | The absolute path to the file to write |
content | string | Yes | The content to write to the file |
Glob
Fast file pattern matching that works with any codebase size.
| Property | Type | Required | Description |
|---|---|---|---|
pattern | string | Yes | The glob pattern to match files against |
path | string | No | The directory to search in (defaults to cwd) |
Grep
Powerful search tool built on ripgrep with regex support.
| Property | Type | Required | Description |
|---|---|---|---|
pattern | string | Yes | The regular expression pattern to search for |
path | string | No | File or directory to search in (defaults to cwd) |
glob | string | No | Glob pattern to filter files (e.g. "*.js") |
type | string | No | File type to search (e.g. "js", "py", "rust") |
output_mode | 'content' | 'files_with_matches' | 'count' | No | Output mode: "content", "files_with_matches", or "count" |
-i | boolean | No | Case insensitive search |
-n | boolean | No | Show line numbers (for content mode) |
-B | number | No | Lines to show before each match |
-A | number | No | Lines to show after each match |
-C | number | No | Lines to show before and after each match |
head_limit | number | No | Limit output to first N lines/entries |
multiline | boolean | No | Enable multiline mode |
KillBash
Kills a running background bash shell by its ID.
| Property | Type | Required | Description |
|---|---|---|---|
shell_id | string | Yes | The ID of the background shell to kill |
NotebookEdit
Edits cells in Jupyter notebook files.
| Property | Type | Required | Description |
|---|---|---|---|
notebook_path | string | Yes | The absolute path to the Jupyter notebook file |
new_source | string | Yes | The new source for the cell |
cell_id | string | No | The ID of the cell to edit |
cell_type | 'code' | 'markdown' | No | The type of the cell (code or markdown) |
edit_mode | 'replace' | 'insert' | 'delete' | No | The type of edit (replace, insert, delete) |
WebFetch
Fetches content from a URL and processes it with an AI model.
| Property | Type | Required | Description |
|---|---|---|---|
url | string | Yes | The URL to fetch content from |
prompt | string | Yes | The prompt to run on the fetched content |
WebSearch
Searches the web and returns formatted results.
| Property | Type | Required | Description |
|---|---|---|---|
query | string | Yes | The search query to use |
allowed_domains | string[] | No | Only include results from these domains |
blocked_domains | string[] | No | Never include results from these domains |
TodoWrite
Creates and manages a structured task list for tracking progress.
| Property | Type | Required | Description |
|---|---|---|---|
todos | TodoItem[] | Yes | The updated todo list |
TodoItem structure:
| Property | Type | Description |
|---|---|---|
content | string | The task description |
status | 'pending' | 'in_progress' | 'completed' | The task status |
activeForm | string | Active form of the task description |
ExitPlanMode
Exits planning mode and prompts the user to approve the plan.
| Property | Type | Required | Description |
|---|---|---|---|
plan | string | Yes | The plan to run by the user for approval |
ListMcpResources
Lists available MCP resources from connected servers.
| Property | Type | Required | Description |
|---|---|---|---|
server | string | No | Optional server name to filter resources by |
ReadMcpResource
Reads a specific MCP resource from a server.
| Property | Type | Required | Description |
|---|---|---|---|
server | string | Yes | The MCP server name |
uri | string | Yes | The resource URI to read |
Tool Output Types
Documentation of output schemas for all built-in Claude Code tools. These types represent the actual response data returned by each tool.
ToolOutputUnion Type
This is a documentation-only type for clarity. It represents the union of all tool output types.
type ToolOutput = | TaskOutput | AskUserQuestionOutput | BashOutput | BashOutputToolOutput | EditOutput | ReadOutput | WriteOutput | GlobOutput | GrepOutput | KillBashOutput | NotebookEditOutput | WebFetchOutput | WebSearchOutput | TodoWriteOutput | ExitPlanModeOutput | ListMcpResourcesOutput | ReadMcpResourceOutput;
TaskOutput
Returns the final result from the subagent after completing the delegated task.
| Property | Type | Description |
|---|---|---|
result | string | Final result message from the subagent |
usage | UsageStats? | Token usage statistics (input_tokens, output_tokens, cache tokens) |
total_cost_usd | number? | Total cost in USD |
duration_ms | number? | Execution duration in milliseconds |
AskUserQuestionOutput
Returns the questions asked and the user's answers.
| Property | Type | Description |
|---|---|---|
questions | Question[] | The questions that were asked |
answers | Record<string, string> | Maps question text to answer string. Multi-select answers are comma-separated. |
BashOutput
Returns command output with exit status. Background commands return immediately with a shellId.
| Property | Type | Description |
|---|---|---|
output | string | Combined stdout and stderr output |
exitCode | number | Exit code of the command |
killed | boolean? | Whether the command was killed due to timeout |
shellId | string? | Shell ID for background processes |
BashOutputToolOutput
Returns incremental output from background shells.
| Property | Type | Description |
|---|---|---|
output | string | New output since last check |
status | 'running' | 'completed' | 'failed' | Current shell status |
exitCode | number? | Exit code (when completed) |
EditOutput
Returns confirmation of successful edits with replacement count.
| Property | Type | Description |
|---|---|---|
message | string | Confirmation message |
replacements | number | Number of replacements made |
file_path | string | File path that was edited |
ReadOutput
Returns file contents in format appropriate to file type.
Union type based on file type:
type ReadOutput = | TextFileOutput | ImageFileOutput | PDFFileOutput | NotebookFileOutput;
TextFileOutput
| Property | Type | Description |
|---|---|---|
content | string | File contents with line numbers |
total_lines | number | Total number of lines in file |
lines_returned | number | Lines actually returned |
ImageFileOutput
| Property | Type | Description |
|---|---|---|
image | string | Base64 encoded image data |
mime_type | string | Image MIME type |
file_size | number | File size in bytes |
PDFFileOutput
| Property | Type | Description |
|---|---|---|
pages | PageContent[] | Array of page contents (page_number, text, images) |
total_pages | number | Total number of pages |
NotebookFileOutput
| Property | Type | Description |
|---|---|---|
cells | Cell[] | Jupyter notebook cells (cell_type, source, outputs, execution_count) |
metadata | Record? | Notebook metadata |
WriteOutput
Returns confirmation after successfully writing the file.
| Property | Type | Description |
|---|---|---|
message | string | Success message |
bytes_written | number | Number of bytes written |
file_path | string | File path that was written |
GlobOutput
Returns file paths matching the glob pattern, sorted by modification time.
| Property | Type | Description |
|---|---|---|
matches | string[] | Array of matching file paths |
count | number | Number of matches found |
search_path | string | Search directory used |
GrepOutput
Returns search results in the format specified by output_mode.
Union type based on output_mode:
type GrepOutput = | GrepContentOutput | GrepFilesOutput | GrepCountOutput;
GrepContentOutput (output_mode: "content")
| Property | Type | Description |
|---|---|---|
matches | Match[] | Matching lines with context (file, line_number, line, before/after_context) |
total_matches | number | Total number of matches |
GrepFilesOutput (output_mode: "files_with_matches")
| Property | Type | Description |
|---|---|---|
files | string[] | Files containing matches |
count | number | Number of files with matches |
GrepCountOutput (output_mode: "count")
| Property | Type | Description |
|---|---|---|
counts | FileCount[] | Match counts per file (file, count) |
total | number | Total matches across all files |
KillBashOutput
Returns confirmation after terminating the background shell.
| Property | Type | Description |
|---|---|---|
message | string | Success message |
shell_id | string | ID of the killed shell |
NotebookEditOutput
Returns confirmation after modifying the Jupyter notebook.
| Property | Type | Description |
|---|---|---|
message | string | Success message |
edit_type | 'replaced' | 'inserted' | 'deleted' | Type of edit performed |
cell_id | string? | Cell ID that was affected |
total_cells | number | Total cells in notebook after edit |
WebFetchOutput
Returns the AI's analysis of the fetched web content.
| Property | Type | Description |
|---|---|---|
response | string | AI model's response to the prompt |
url | string | URL that was fetched |
final_url | string? | Final URL after redirects |
status_code | number? | HTTP status code |
WebSearchOutput
Returns web search results with titles, URLs, and snippets.
| Property | Type | Description |
|---|---|---|
results | SearchResult[] | Search results (title, url, snippet, metadata) |
total_results | number | Total number of results |
query | string | The query that was searched |