Combining MCP Toolsets with defer_loading to Control Context Cost

Every tool you give Claude has a definition — name, description, argument schema — and every definition normally sits in the context window on every request, billed as input tokens whether the tool gets called or not. With hand-written tools you feel this cost and keep it in check. With the MCP connector, you inherit whatever a server exposes, and Model Context Protocol (MCP) servers happily expose dozens of tools each. Anthropic's tool search documentation puts numbers on the problem: a typical multi-server setup can consume around 55,000 tokens in definitions alone, and — separate from cost — tool selection accuracy degrades once more than 30–50 tools are loaded. Big toolsets are both expensive and counterproductive.

How defer_loading works

The fix is a per-tool flag: defer_loading. Inside an mcp_toolset, it lives in the same two-layer config system as enabled — set it in default_config to defer every tool on a server, or in per-tool configs to defer selectively, with the per-tool entry always winning (see the filtering article for the precedence rules).

The crucial mental model: deferral controls what enters the context window, not what you send. Deferred tools remain fully declared in the request; the API simply keeps their definitions out of Claude's prompt until they are needed. That is why the topic title says "without removing them from the request" — nothing about your request assembly changes, only what Claude sees up front.

The other half: the tool search tool

Deferred tools would be useless if Claude could never discover them, so defer_loading pairs with the server-side tool search tool. When Claude decides it needs a capability it can't see, it searches the deferred pool; matching tools come back as tool_reference blocks that the API expands into full definitions automatically. Two variants exist: tool_search_tool_regex_20251119 (Claude writes Python re.search() patterns, case-insensitive, max 200 characters) and tool_search_tool_bm25_20251119 (natural-language queries, max 500 characters). Searches match against tool names, descriptions, argument names, and argument descriptions, and each search returns up to 5 matching tools by default.

{
  "tools": [
    {"type": "tool_search_tool_bm25_20251119", "name": "tool_search"},
    {
      "type": "mcp_toolset",
      "mcp_server_name": "crm",
      "default_config": {"defer_loading": true},
      "configs": {"search_contacts": {"defer_loading": false}}
    }
  ]
}

This example defers everything on the server except search_contacts, which stays eagerly loaded because it is used in almost every session. That is the recommended shape: keep the handful of hot-path tools loaded, defer the long tail. Anthropic's docs report tool search typically cuts definition token usage by over 85% in large setups.

Rules and limits to design around

At least one tool must stay non-deferred — normally the search tool itself. Deferring everything returns a 400 error.
Ceiling: up to 10,000 deferred tools per request.
Caching plays nicely: discovered definitions are appended, so your cached system-prompt prefix is preserved rather than invalidated. But a deferred tool cannot itself carry cache_control — that combination is a 400.
Billing: tool search is not metered as a separate server tool; definitions that get loaded simply bill as normal input tokens.
Empty results aren't errors: a search with no matches returns an empty tool_references array.

Rule of thumb: if a request carries more than roughly 30–50 loaded tool definitions, defer the rest. Below that, deferral adds a search round-trip for little benefit; above it, you are paying tokens to make Claude worse at picking tools.

Platform note

This combination inherits the MCP connector's availability: the Claude API, Claude Platform on AWS, and Foundry Hosted-on-Anthropic deployments only — not Bedrock or Vertex AI. The tool search tool by itself travels further (it works with ordinary client tools on Bedrock via the InvokeModel API and on Vertex), so the deferral pattern survives a platform move even where the connector does not; see the tool search deep dive.

Where to go next

For the cost side of tool definitions generally, see tool schema optimization; for the broader request anatomy, start at inside the MCP connector request.

Sources

← All articles