> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/VineeTagarwaL-code/claude-code/llms.txt
> Use this file to discover all available pages before exploring further.
# Tools
> Reference for every built-in tool Claude Code can use, including file operations, shell execution, web access, and sub-agent spawning.
Claude Code gives Claude a set of built-in tools it can call to interact with your machine. Each tool call is subject to the active [permission mode and rules](/concepts/permissions). Below is a reference for every tool available by default.
## File tools
**Read a file from the local filesystem.**
Reads up to 2 000 lines by default. Supports an `offset` and `limit` for targeted reads of large files. Returns content in `cat -n` format with line numbers.
Also supports reading images (PNG, JPG, etc.) as visual input, PDF files (up to 20 pages at a time), and Jupyter notebooks (`.ipynb`).
Read-only. Always auto-approved in `default` mode.
**Perform exact string replacements in a file.**
Requires a prior `Read` call on the file in the same conversation. Replaces `old_string` with `new_string` — the match must be unique in the file. Use `replace_all: true` to rename across the entire file.
Fails if `old_string` appears more than once (unless `replace_all` is set). This precision prevents unintended edits.
**Create a new file or completely overwrite an existing one.**
For existing files, a prior `Read` call is required in the same conversation. Prefer `Edit` for modifying existing files — `Write` sends the entire file content and is better suited for new files or full rewrites.
**Find files by name pattern.**
Fast pattern matching that works on any codebase size. Returns matching file paths sorted by modification time (most recently modified first).
Supports patterns like `**/*.ts`, `src/**/*.test.js`, `**/CLAUDE.md`. For open-ended multi-step searches, use the `Task` tool instead.
Read-only. Always auto-approved.
## Shell tool
**Execute a shell command in a persistent shell session.**
Runs the command in a shell that persists across tool calls within a conversation — environment variables and working-directory changes carry over between calls. Supports a `timeout` parameter (default and max values are configurable).
Key behaviours:
* **Compound commands** (`&&`, `||`, `;`, `|`) are parsed and each sub-command is permission-checked independently.
* **Background execution** — pass `run_in_background: true` to run a long-running command without blocking. You are notified when it completes.
* **Output limits** — stdout/stderr is truncated if it exceeds the per-tool result size budget; a preview and file path are returned instead.
* **Search commands** (`find`, `grep`, `rg`) — for content search, prefer the dedicated `Grep` tool, which has optimised permissions and access.
Subject to permission prompts in `default` mode. Auto-approved in `acceptEdits` mode only for commands covered by an allow rule.
## Search tools
**Search file contents using regular expressions.**
Built on ripgrep. Supports full regex syntax (`log.*Error`, `function\s+\w+`), file-type filtering (`*.ts`, `**/*.py`), and three output modes:
* `files_with_matches` (default) — returns only file paths
* `content` — returns matching lines with context
* `count` — returns match counts per file
Multiline patterns are supported with `multiline: true`.
Read-only. Always auto-approved.
**List directory contents.**
Returns files and subdirectories in a structured format. Useful for exploring project structure before reading or editing files.
Read-only. Always auto-approved.
In bare-minimum mode (`CLAUDE_CODE_SIMPLE=1`) only `Bash`, `Read`, and `Edit` are available — use `ls` via `Bash` instead.
## Web tools
**Fetch a URL and extract information from it.**
Takes a URL and a prompt describing what to extract. Converts HTML to Markdown, then passes the content through a secondary model to produce a focused answer.
Features:
* HTTP URLs are automatically upgraded to HTTPS.
* Includes a 15-minute self-cleaning cache — repeated fetches of the same URL are fast.
* When a URL redirects to a different host, the tool returns the redirect URL for a follow-up request.
* For GitHub URLs, prefer the `gh` CLI via `Bash` (e.g., `gh pr view`, `gh api`).
Read-only. Prompts for approval in `default` mode.
**Search the web and return results.**
Returns search results with titles, snippets, and URLs formatted as Markdown links. Useful for accessing information beyond the model's training cutoff.
After answering, Claude automatically appends a `Sources:` section listing all referenced URLs.
Domain filtering is supported to include or exclude specific sites. Currently only available in the US.
Prompts for approval in `default` mode.
## Agent and task tools
**Spawn a sub-agent to complete a task.**
Starts a nested agentic loop in a separate context. The sub-agent has its own conversation history, its own tool set (optionally restricted), and runs to completion before returning a result to the parent agent.
Sub-agents can run:
* **Locally** — in-process, sharing the parent's filesystem and shell
* **Remotely** — on separate compute when remote agent eligibility criteria are met
Use `Task` for open-ended multi-step searches, parallel workstreams, or delegating distinct sub-problems to isolated agents.
The parent agent receives the sub-agent's final output as a tool result.
**Create and manage a structured task list.**
Writes a list of todo items with statuses (`pending`, `in_progress`, `completed`) to a persistent panel in the terminal UI. Helps Claude track progress on complex multi-step tasks and shows you what it is working on.
Use proactively for tasks with 3 or more distinct steps. Not necessary for simple single-step requests.
Results are rendered in the todo panel, not the conversation transcript.
## MCP tools
MCP (Model Context Protocol) servers can expose additional tools to Claude Code. Connected tools appear in the tool list alongside built-in tools and follow the same permission system.
MCP tools are named with a `mcp__` prefix:
```
mcp____
```
For example, a tool named `query` on a server named `mydb` appears as `mcp__mydb__query`.
Common MCP tool categories include:
* Database query and management tools
* Browser and web automation tools
* Cloud provider APIs (AWS, GCP, Azure)
* Issue tracker integrations (GitHub, Linear, Jira)
* Internal company tools and APIs
MCP servers are configured in `~/.claude/mcp_servers.json` or `.claude/mcp_servers.json`. Tools from a connected server are automatically included in Claude's context once the server is running.
To deny all tools from a specific MCP server, add a deny rule for the server prefix:
```json theme={null}
{
"permissions": {
"deny": ["mcp__untrusted-server"]
}
}
```
## Notebook tool
**Edit cells in a Jupyter notebook.**
Allows Claude to insert, replace, or delete cells in a `.ipynb` file with line-level precision. Read notebooks using the standard `Read` tool, which returns all cells and their outputs.
## Tool availability
Not all tools are available in every context. The active tool set is determined at startup and can be affected by:
* `CLAUDE_CODE_SIMPLE=1` — restricts to `Bash`, `Read`, and `Edit` only
* Permission deny rules — tools blanket-denied by a rule are removed from the tool list before the model sees them
* `isEnabled()` checks — each tool can self-disable based on environment conditions (e.g., `WebSearch` is gated by region)
* MCP server connection state — MCP tools are only available when the server is running and connected
You can inspect the active tool set with the `/tools` command in the REPL.