闭架书库的索书条

Deferred tool loading is Claude Code's answer to tool-schema bloat. Instead of expanding every tool definition into every request, the harness marks a subset of tools as deferred: their schemas ride to the API with defer_loading: true — a beta field on the tool schema (claude-code/src/utils/api.ts:69-78) set at serialization time (claude-code/src/utils/api.ts:223-226) — and the model is told about them by name only. One always-loaded tool, named ToolSearch (claude-code/src/tools/ToolSearchTool/constants.ts:1), is the retrieval interface: the model calls it with a query string plus an optional max_results defaulting to 5 (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:21-34), and the result carries tool_reference content blocks that the API expands into full tool definitions (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:444-470).

Which tools are deferred is decided by isDeferredTool, in strict order: alwaysLoad: true opts out first, every MCP tool is deferred, ToolSearch itself never is (the model needs it to load everything else), a few communication-critical tools are exempted behind build features, and otherwise the tool's own shouldDefer flag decides (claude-code/src/tools/ToolSearchTool/prompt.ts:62-108). The per-tool fields involved — searchHint, isMcp, shouldDefer, alwaysLoad — are declared on the Tool type (claude-code/src/Tool.ts:378,436,442,449).

How it works

A layered enablement gate. Registration is optimistic: ToolSearchTool.isEnabled() just calls isToolSearchEnabledOptimistic() (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:304-313), which only rules out the definitely-off cases: standard mode, or — when ENABLE_TOOL_SEARCH is unset — a first-party provider whose ANTHROPIC_BASE_URL points at a non-Anthropic proxy, since such proxies typically reject tool_reference blocks; setting any non-empty value overrides this heuristic (claude-code/src/utils/toolSearch.ts:270-320). The mode itself maps ENABLE_TOOL_SEARCH to 'tst' | 'tst-auto' | 'standard' — auto/auto:1-99 → tst-auto, true/auto:0 → tst, false/auto:100 → standard, unset → tst — with CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS acting as a kill switch that forces standard (claude-code/src/utils/toolSearch.ts:172-198). The same kill switch also strips defer_loading (and every other non-allowlisted beta field) at the one choke point all tool schemas pass through, so no beta shape reaches the wire (claude-code/src/utils/api.ts:232-243).

The definitive per-request check, isToolSearchEnabled, layers three more gates: the model must support tool_reference — a negative test defaulting to ['haiku'], live-overridable via the GrowthBook feature tengu_tool_search_unsupported_models (claude-code/src/utils/toolSearch.ts:204,239-252,419-426); ToolSearchTool must actually be in the tool list, respecting disallowedTools (claude-code/src/utils/toolSearch.ts:429-435); and finally the mode switch, where tst-auto additionally measures total deferred-tool description size against a threshold (claude-code/src/utils/toolSearch.ts:437-473). The query path in claude.ts runs this check per request (claude-code/src/services/api/claude.ts:1120-1126), precomputes the deferred name set once (claude-code/src/services/api/claude.ts:1128-1134), and disables tool search when there is nothing to defer and no MCP servers are still connecting (claude-code/src/services/api/claude.ts:1139-1148).

Request assembly. With tool search on, filteredTools keeps every non-deferred tool, always keeps ToolSearch, and keeps a deferred tool only if it appears in extractDiscoveredToolNames(messages) (claude-code/src/services/api/claude.ts:1154-1172) — the code comments that this "removes limits on tool quantity" because deferred tools no longer need to be predeclared upfront (claude-code/src/services/api/claude.ts:1155-1157). A provider-specific beta header is pushed (Bedrock routes it through body params instead) (claude-code/src/services/api/claude.ts:1177-1182). Each surviving tool is serialized via toolToAPISchema(tool, { deferLoading: willDefer(tool), ... }) (claude-code/src/services/api/claude.ts:1232-1246), which sets schema.defer_loading = true (claude-code/src/utils/api.ts:223-226). One subtlety: the full tools list — not filteredTools — is passed into schema generation, so ToolSearch's own prompt can describe all MCP tools even though only discovered ones are actually sent (claude-code/src/services/api/claude.ts:1232-1234).

Two announcement channels. How the model learns the deferred names depends on isDeferredToolsDeltaEnabled() — USER_TYPE === 'ant' or the GrowthBook flag tengu_glacier_2xr (claude-code/src/utils/toolSearch.ts:629-634). With the flag off, claude.ts prepends an ephemeral meta user message wrapping the sorted name list in <available-deferred-tools> tags on every call (claude-code/src/services/api/claude.ts:1330-1345). With it on, getDeferredToolsDeltaAttachment emits a persisted deferred_tools_delta attachment instead (claude-code/src/utils/attachments.ts:1455-1475), rendered to the model as a system-reminder listing newly available and newly removed tools (claude-code/src/utils/messages.ts:4178-4193). The delta is computed by replaying all prior delta attachments to reconstruct the announced set, then diffing against the current pool — and a tool that was announced but has since stopped being deferred, yet is still in the pool, is deliberately not reported as removed, because it's now loaded directly and "no longer available" would be a lie (claude-code/src/utils/toolSearch.ts:646-706). Each announced line is just the tool name; searchHint is intentionally omitted after an A/B test showed no benefit (claude-code/src/tools/ToolSearchTool/prompt.ts:110-117). ToolSearch's own prompt duplicates the delta gate by hand to tell the model where the names appear, and carries a comment that it must stay in sync (claude-code/src/tools/ToolSearchTool/prompt.ts:35-42).

The search itself. call() recomputes deferredTools = tools.filter(isDeferredTool) and invalidates a description cache memoized by tool name whenever the deferred name-set changes (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:328-332,66-105). A select: query is comma-split and each name resolved with findToolByName — which matches primary names or aliases (claude-code/src/Tool.ts:348-360) — against the deferred set first, then the full set; missing names are tolerated, and selecting an already-loaded tool is a designed no-op that "lets the model proceed without retry churn" (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:358-406). Keyword queries go through searchToolsWithKeywords: an exact-name fast path over deferred then full tools (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:199-204), an mcp__ prefix branch for server-name queries (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:208-216), a +term partition where +-prefixed terms are required and pre-filter the candidates (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:218-257), and finally scoring: exact name-part match scores 10 (12 for MCP), substring 5 (6 for MCP), full-name fallback 3, a word-boundary hit in searchHint 4, and in the tool description 2 (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:266-301). Names are decomposed by parseToolName, which splits mcp__server__action on underscores and regular tool names on CamelCase (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:132-161). An empty result includes pending_mcp_servers (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:37-47,335-339) so the model knows to retry once servers finish connecting.

Delivering and keeping tools live. Matches are mapped into a tool_result whose content is a list of { type: 'tool_reference', tool_name } blocks — cast through as unknown as ToolResultBlockParam because tool_reference is a beta content type absent from the SDK types (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:444-470). The API expands these into real definitions, but the next request is rebuilt from scratch — so extractDiscoveredToolNames re-scans the message history for tool_result → tool_reference blocks each turn to decide which deferred tools stay in filteredTools (claude-code/src/utils/toolSearch.ts:545-592). Compaction would destroy that evidence (the summary preserves no tool_reference blocks), so the compactor snapshots the discovered set onto the boundary marker's compactMetadata.preCompactDiscoveredTools (claude-code/src/services/compact/compact.ts:605-610), and the scanner reads it back from any compact-boundary message it encounters (claude-code/src/utils/toolSearch.ts:553-560).

Why it matters

Context economy at scale. MCP servers can contribute hundreds of tools, each with a description and JSON schema. Deferral means the initial prompt carries a name list instead of full schemas, and the model pays the schema cost only for tools it actually fetches — which is exactly why the code notes this "eliminates the need to predeclare all deferred tools upfront and removes limits on tool quantity" (claude-code/src/services/api/claude.ts:1155-1157).

Prompt-cache friendliness. The two announcement channels exist because the ephemeral <available-deferred-tools> prepend "busts cache whenever the pool changes"; the persisted delta attachment only appends increments (claude-code/src/services/api/claude.ts:1327-1330; claude-code/src/utils/toolSearch.ts:624-634).

Defensive engineering against a beta wire format. Because defer_loading and tool_reference are beta API shapes, the harness hedges at every layer: proxies that would 400 on tool_reference are heuristically detected (claude-code/src/utils/toolSearch.ts:282-311), the kill switch strips beta fields at a single choke point (claude-code/src/utils/api.ts:232-243), unsupported models like Haiku are excluded by a live-updatable negative list (claude-code/src/utils/toolSearch.ts:204,239-252), and select: on an already-loaded tool is a graceful no-op precisely because subagents and post-compaction turns were observed doing it (claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts:194-204,358-362).

A reusable pattern. The shape — announce names cheaply, retrieve schemas on demand, persist discovery in the transcript, carry it across compaction — is the harness's general recipe for making an unbounded resource pool fit a bounded context window.

Read the source

Suggested order:

1. claude-code/src/tools/ToolSearchTool/prompt.ts — start with isDeferredTool (prompt.ts:62-108) to see exactly what gets deferred, then the tool's own prompt text and the hand-synced location hint (prompt.ts:35-51,110-121).
2. claude-code/src/utils/toolSearch.ts — the mode mapping (172-198), model support (239-252), optimistic vs. definitive gates (270-320, 385-473), the discovery scan (545-592), and the delta diff (629-706).
3. claude-code/src/services/api/claude.ts:1118-1182,1232-1246,1330-1345 — the per-request assembly: gate, deferredToolNames, filteredTools, beta header, schema serialization, and the ephemeral announcement.
4. claude-code/src/tools/ToolSearchTool/ToolSearchTool.ts — schemas (21-47), the description cache (66-105), name parsing and scoring (132-161, 186-302), call() with the select: branch (328-434), and the tool_reference result mapping (444-470).
5. claude-code/src/utils/api.ts:69-78,215-243 — how defer_loading reaches the wire, and how the kill switch strips it.
6. claude-code/src/utils/attachments.ts:1455-1475, claude-code/src/utils/messages.ts:4178-4193, claude-code/src/services/compact/compact.ts:605-610 — the persisted announcement channel and compaction survival.