Tools

The built-in capabilities Claude uses to read files, run commands, search the web, and interact with your system.

Tools are the actions Claude can take during a session. When you ask Claude to do something, it selects and calls the appropriate tools to accomplish the task — reading a file, running a shell command, searching the codebase, or fetching a web page.

Each tool call is visible in the terminal as it happens. Depending on your permission settings, Claude may ask for your approval before running certain tools.

Available tools

Bash

Executes shell commands and returns their output. The working directory persists between commands; shell state does not.

Read

Reads files from the local filesystem, including images, PDFs, and Jupyter notebooks.

Write

Creates new files or completely overwrites existing files on disk.

Edit

Performs exact string replacements in existing files — sends only the diff, not the full file.

Glob

Finds files by glob pattern (e.g., **/*.ts), sorted by modification time.

Grep

Searches file contents with regular expressions, powered by ripgrep.

WebFetch

Fetches a URL, converts HTML to Markdown, and processes it with a prompt.

WebSearch

Searches the web and returns relevant results.

Agent

Spawns a sub-agent to handle complex, multi-step tasks autonomously.

MCPTool

Calls tools exposed by connected MCP servers.

TodoWrite

Creates and manages a structured task list for the current session.

Tool reference

Bash

Executes a bash command and returns its output. The working directory persists between commands, but shell state (variables, functions) does not — the shell environment is re-initialized from the user’s profile on each call.

Bash({
  command: string,          // The command to execute
  timeout?: number,         // Timeout in milliseconds (default: 2 minutes)
  description?: string,     // Human-readable description shown in the UI
  run_in_background?: boolean // Run without blocking the current turn
})

When Claude uses Bash: For git operations, running tests, installing packages, starting servers, and any task that requires shell access. Claude prefers dedicated tools (Read, Glob, Grep) over Bash for file and search operations.

Long-running commands can be sent to the background with run_in_background: true. Claude receives a notification when the command completes and can read the output at any time.

---

Read

Reads a file from the local filesystem. Supports text files, images (PNG, JPG, etc.), PDFs, and Jupyter notebooks (.ipynb). Returns content with line numbers prefixed in cat -n format.

Read({
  file_path: string,   // Absolute path to the file
  offset?: number,     // Line number to start reading from (1-indexed)
  limit?: number,      // Maximum number of lines to read (default: 2000)
  pages?: string       // For PDFs: page range, e.g. "1-5" (required for large PDFs)
})

When Claude uses Read: Whenever it needs to examine file contents. Claude must read a file before editing it.

---

Write

Writes content to a file on the local filesystem. Creates the file if it does not exist, or overwrites it entirely if it does.

Write({
  file_path: string,  // Absolute path to the file
  content: string     // Full content to write
})

When Claude uses Write: To create new files. For modifying existing files, Claude prefers Edit because it sends only the changed portion.

Write always reads the file first if it already exists. Skipping the read step causes the tool call to fail.

---

Edit

Performs an exact string replacement in a file. Claude must have read the file at least once in the current conversation before editing it.

Edit({
  file_path: string,    // Absolute path to the file
  old_string: string,   // Exact string to replace (must be unique in the file)
  new_string: string,   // Replacement string
  replace_all?: boolean // Replace every occurrence instead of just the first
})

When Claude uses Edit: For targeted changes to existing files — bug fixes, adding a function, updating configuration. The old_string must exactly match the content as it appears in the file, including whitespace.

---

Glob

Finds files matching a glob pattern. Returns matching paths sorted by modification time (most recently modified first).

Glob({
  pattern: string,  // Glob pattern, e.g. "**/*.ts" or "src/**/*.tsx"
  path?: string     // Directory to search in (defaults to current working directory)
})

When Claude uses Glob: To find files by name or extension before reading or editing them. Faster than running find through Bash.

---

Grep

Searches file contents using regular expressions, powered by ripgrep. Supports several output modes: files_with_matches (default), content, or count.

Grep({
  pattern: string,         // Regex pattern to search for
  path?: string,           // Directory to search in
  include?: string,        // Glob filter for file types, e.g. "*.ts"
  type?: string,           // File type filter, e.g. "js", "py", "rust"
  output?: string,         // "content" | "files_with_matches" | "count"
  multiline?: boolean      // Match patterns across line boundaries
})

When Claude uses Grep: To find where a symbol is defined or used, locate a specific pattern, or search across a large codebase. For open-ended searches that may need multiple rounds, Claude uses the Agent tool instead.

---

WebFetch

Fetches a URL, converts the HTML to Markdown, and processes it with a prompt using a fast secondary model. Results are cached for 15 minutes.

WebFetch({
  url: string,    // Fully-formed URL (HTTP is upgraded to HTTPS automatically)
  prompt: string  // Describes what information to extract from the page
})

When Claude uses WebFetch: To read documentation, check an API reference, or retrieve any web content it needs to complete a task. When a URL redirects to a different host, the tool reports the redirect and Claude makes a new request to the target URL.

---

WebSearch

Searches the web and returns relevant results.

WebSearch({
  query: string  // Search query
})

When Claude uses WebSearch: When it needs current information that may not be in its training data, or when looking up a library, package, or external resource.

---

Agent

Spawns a sub-agent to handle complex tasks autonomously. The agent runs in a separate context with its own tool budget. See Agents for a full description of agent types and coordination.

Agent({
  prompt: string,             // Task description for the agent
  subagent_type?: string,     // Agent type (e.g., "general-purpose", "Explore")
  description?: string,       // Short description shown in the UI (3-5 words)
  run_in_background?: boolean,// Run without waiting for the result
  isolation?: "worktree"      // Run in an isolated git worktree
})

---

MCPTool

Calls a tool exposed by a connected MCP server. The tool name, description, and input schema come from the MCP server itself. See MCP Servers for how to configure MCP servers.

---

TodoWrite

Creates and updates a structured task list for the current session. Claude uses this tool proactively for complex, multi-step tasks so you can track progress in real time.

TodoWrite({
  todos: Array<{
    id: string,
    content: string,       // Imperative form: "Run tests"
    activeForm: string,    // Present continuous form: "Running tests"
    status: "pending" | "in_progress" | "completed"
  }>
})

When Claude uses TodoWrite: For tasks with three or more distinct steps, when you provide a list of things to do, or when you explicitly ask Claude to use a todo list. Claude keeps exactly one task in_progress at a time and marks tasks complete immediately after finishing them.

Tool permissions

By default, Claude asks for approval before running tools that modify files or execute commands. You can configure which tools are always allowed, always denied, or require approval on a per-session or per-project basis.

See Permissions for the full reference on configuring tool approval rules, including wildcard patterns for Bash commands.

Permission modes

Mode	Behavior
Default	Asks before write operations, destructive commands, and new tool types
acceptEdits	Auto-approves file edits; still asks for shell commands
bypassPermissions	Auto-approves everything (use with caution)

You can set the permission mode for a session with the --permission-mode flag, or configure allowedTools and deniedTools in your settings file.