Skip to main content

Tools

A tool is an action that Claude can take, such as reading a file or running a shell command. Each tool has input fields and a few flags that tell Claude Code how to treat it. For example, Grep is read-only and safe to run in parallel, so Claude Code can run many searches at once. This page covers the shared rules. The other pages list every tool and every parameter.

At a Glance​

QuestionAnswer
Can you use it?Partly. Claude calls tools for you. You allow, ask, or deny them with permission rules.
Can you change it?✅ Yes. Permission rules, subagent tools and disallowedTools lists, and MCP servers change which tools Claude can use.
Can you turn it on or off?permissions.deny, ENABLE_TOOL_SEARCH, and tool-specific env vars such as CLAUDE_CODE_DISABLE_WEB_FETCH.
Where does it live?Built into the program. MCP tools come from servers you configure.
StatusDocumented Undocumented Differs Gated

Tool Pages​

PageWhat It Covers
Files, Search, and MemoryRead, Write, Edit, NotebookEdit, Glob, Grep, LSP, memory tools
Shell, Web, and Background TasksBash, PowerShell, Monitor, WebFetch, WebSearch, TaskStop, GetTask
Agents, Tasks, and PlanningAgent, SendMessage, task tools, cron, Workflow, worktrees, plan mode, AskUserQuestion
Gated and Surface-Specific ToolsOnboarding, design, connectors, self-hosted runner, notifications, StructuredOutput, MCP resource tools

How to Read the Tool Tables​

The inventory for 2.1.304 lists 70 tools. The program holds a few more, such as Agent, Monitor, ToolSearch, ScheduleWakeup, and StructuredOutput. Each tool table has three Yes or No columns.

ColumnYes MeansNo Means
Read-OnlyThe tool changes nothing, so Claude Code can skip some prompts for it.The tool can change things, or the program sets no flag.
ParallelClaude Code can run several calls of the tool at once.Calls run one after the other, or the program sets no flag.
DeferredThe tool is not loaded at the start. Claude finds it with ToolSearch first.The tool is loaded at the start.

A tool with no flag in its definition shows No for Read-Only and Parallel. Bash and PowerShell also show No for both, because the result depends on the command.

Common Properties​

Source: the program (the tool definitions).

PropertyValuesWhat It Means
backgroundingnever, self, detachself means the tool backgrounds itself (Bash, PowerShell, Agent). detach applies to WebFetch and WebSearch.
maxResultSizeChars100000 for most tools, 20000 for Grep, unbounded for ReadThe largest result the tool sends back.
stricttrue for Write, Edit, Read, Grep, Bash, PowerShell, TodoWrite, ReportFindingsThe tool schema is strict.
MCP tool namemcp__<server>__<tool>How a tool from an MCP server is named. See MCP.

ToolSearch​

ToolSearch loads the full schema of a deferred tool, so that Claude can call it. For example, the query select:Read,Edit,Grep fetches those three tools by name. Source: Tools Reference, Create Custom Subagents, and the program.

ItemStatusWhat It DoesHow It Works
ToolSearchDocumentedLoads the full schema of deferred tools.query (string, required) and max_results (int, optional, default 5). The result lists matches, total_deferred_tools, pending_mcp_servers, and failed_mcp_servers. Works in the main session and in subagents.
max_resultsDiffersAn old 2.1.296 capture showed it as required.In 2.1.304 it is optional with the default 5.
Query select:A,BUndocumentedFetches the named tools.The prompt gives select:Read,Edit,Grep. A tool that is already loaded returns a note.
Query keywordsUndocumentedSearches by keyword and returns up to max_results matches.The prompt gives notebook jupyter.
Query +term restUndocumentedRequires term in the tool name and ranks by the rest.The prompt gives +slack send.
Pending MCP serversDocumentedA search can wait for MCP servers that are still connecting.Name the server as mcp__server in the query.
Placeholder toolUndocumentedA dummy tool keeps deferred loading active.The text tells Claude never to call it.
Deny ruleDocumentedpermissions.deny with ToolSearch turns tool search off.Claude then uses WaitForMcpServers.
Failed servers noteDocumentedA no-match result names the servers that failed.failed_mcp_servers carries name, errorCode, and error.

Deferral Rules​

Claude Code checks these rules in order to decide if a tool is deferred.

  1. A hook or a server-side override can set the state first.
  2. A tool with alwaysLoad set to true is not deferred.
  3. A tool in the never-defer set is not deferred. The set holds ToolSearch, StructuredOutput, Agent when fork mode is on, the brief tool, EnterWorktree in a bg session, and PushNotification for a remote_trigger entry point. A server-side list can add more built-in tools.
  4. An MCP tool is deferred.
  5. A tool in a server-side defer list is deferred.
  6. Otherwise the shouldDefer value of the tool decides.

Source: Connect Claude Code to Tools via MCP and Environment Variables. Set them in the shell or in env in settings.

ItemStatusWhat It DoesHow It Works
ENABLE_TOOL_SEARCH unsetDocumentedMCP tools are deferred.Since 2.1.304 this also holds behind a custom ANTHROPIC_BASE_URL. If the gateway answers 400 or 422, Claude Code retries the request without tool search. Source: the program and the release notes.
ENABLE_TOOL_SEARCH=trueDocumentedMCP tools stay deferred, also on a proxy host.-
ENABLE_TOOL_SEARCH=auto and auto:NDocumentedTools load at the start while their definitions fit in N percent of the window.The default is 10. auto:0 acts like true. auto:100 acts like false. N stays between 0 and 100.
ENABLE_TOOL_SEARCH=falseDocumentedEvery MCP tool loads at the start.-
ENABLE_TOOL_SEARCH=forceDocumented GatedForces tool search on, also when betas are off.Needs a first-party provider.
alwaysLoadDocumentedExempts a tool or a whole server from deferral.Set it on the server in .mcp.json or plugin MCP config. An MCP tool sets it from _meta key anthropic/alwaysLoad.
Server-side never-defer listUndocumented GatedNames built-in tools that must never be deferred.The default is an empty list. You cannot set it.
Server-side defer listUndocumented GatedDefers ReportFindings, Workflow, and ShareOnboardingGuide.You cannot set it.

Which Built-In Tools Are Deferred​

  • Deferred: WebFetch, WebSearch, NotebookEdit, TodoWrite, LSP, Monitor, EnterPlanMode, ExitPlanMode, EnterWorktree, ExitWorktree, TaskCreate, TaskGet, TaskUpdate, TaskList, TaskStop, SendMessage, SendFile, CronCreate, CronDelete, CronList, PushNotification, RemoteTrigger, EndConversation, ProposeGoal, FetchInboxMessage, PublishPlugin, OfferChromeSetup, DesignSync, SearchMcpRegistry, SuggestConnectors, ListConnectors, the three MCP resource tools, and the nine self-hosted runner tools.
  • A runtime check decides: SuggestPluginInstall, SuggestSkills, SendUserFile.
  • Not deferred: Read, Write, Edit, Glob, Grep, Bash, PowerShell, Agent, Skill, AskUserQuestion, ListAgents, Workflow, ReportFindings, ToolSearch, StructuredOutput, SubagentHandback, ScheduleWakeup, memory_*, and the rest of the gated tools.
  • The old capture of 2.1.296 lacked Glob and Grep. In 2.1.304 they are not deferred.
  • In the 2.1.304 capture, the main prompt lists 12 tools (the site's captures use a local stub as ANTHROPIC_BASE_URL, and tool search is on behind a custom base URL, so it is not 20 as before). CronCreate, CronDelete, CronList, EnterWorktree, ExitWorktree, NotebookEdit, SendMessage, TaskStop, WebFetch, and WebSearch sit behind ToolSearch. See Tools per Variant.

Example​

Hide web tools from Claude, and keep MCP tools loaded at the start when they are small.

.claude/settings.json
{
  "permissions": {
    "deny": ["WebFetch", "WebSearch"]
  },
  "env": {
    "ENABLE_TOOL_SEARCH": "auto:10"
  }
}

How It Works​

Claude Code builds the tool list for each request. A deferred tool appears only as a name, so the request stays small. When Claude needs a deferred tool, it calls ToolSearch. Claude Code then loads the full schema, and Claude calls the tool. Permission rules run when a tool is called, not when it is listed.