Defer Loading and Tool Search

Definition

defer_loading withholds a tool's description from the initial model context; the server-side Tool search tool then fetches definitions on demand, keeping large tool catalogs cheap.

Key points

• defer_loading: true (default false) — when true, the tool's description is not sent to the model initially; it is discovered via the Tool search tool.
• Used with large tool sets to save context tokens.
• Available both as a per-tool field on custom tool definitions and inside mcp_toolset per-tool configs.
• The Tool search tool is a server tool (runs on Anthropic infra; no handler code).

Why it matters for the exam

• Tested as the context-efficiency answer when a server exposes dozens/hundreds of tools.
• Pairs conceptually with Adaptive Thinking and Effort and caching as a context-budget lever.

Common gotchas

• defer_loading is a token/context optimization, not an access control — use MCPToolset Allowlist and Denylist to actually restrict tools.
• Deferred tools cannot be called until the Tool search tool has surfaced their schema.

See also

• MCPToolset Allowlist and Denylist
• MCP Connector
• Tool Definition Schema
• Prompt Caching

Sources

• docs-tools-agents
• netlight-study-guide