Claude Code Deferred Tools: Dynamic Tool Loading Explained (2026)

Connect a dozen MCP servers to Claude Code and you hit a wall fast: every tool's full schema — name, description, every parameter, every type — gets stuffed into the system prompt before the model reads a single line of your actual request. Slack, Notion, Vercel, Supabase, a handful of custom internal servers, and suddenly you're burning tens of thousands of tokens on tool definitions you'll use maybe twice a session.

Claude Code's answer is deferred tools. Instead of loading every tool's full JSON schema upfront, large MCP integrations show up as name-only entries in a lightweight list. The model calls a search tool to fetch the full schema for only the tools it actually needs, when it needs them. This guide covers how it works, what changes in practice, and how to write MCP servers that play well with it.

The Problem: Tool Schema Bloat

Every tool a model can call needs a schema in context — a JSON Schema description of its name, purpose, and parameters. For a handful of tools this costs nothing. For real-world setups with dozens of MCP servers (each often exposing 10-30 tools), the math stops working.

A single MCP server like a full CRM or cloud platform integration can easily define 40+ tools, each with multi-paragraph descriptions and nested parameter objects. Multiply that across every server you've connected — Slack, a CMS, a cloud provider, a payments platform, a handful of automation servers — and you can burn 30,000-50,000 tokens before the conversation even starts. That's context you can't spend on your actual codebase, your CLAUDE.md, or the task at hand.

This is a direct consequence of MCP's own success. The more useful the ecosystem gets, the more servers a power user connects, and the more expensive it becomes to hold every tool definition in memory at all times — most of which will never be called in a given session.

How Deferred Tools Work

Claude Code addresses this by splitting tool exposure into two tiers:

• Always-loaded tools. Core tools you use in nearly every session — Read, Edit, Bash, Grep, Glob, TodoWrite — keep their full schemas in context from the start. No lookup required.
• Deferred tools. Tools from large MCP integrations appear as name-only entries in an <available-deferred-tools> block. The model sees the tool exists but not its parameters, types, or full description.

When the model decides it needs a deferred tool, it calls a dedicated search function — a ToolSearch-style lookup — with a query describing what it's after. That query gets matched against the deferred tool list, and the matching tools' complete schemas are returned inline, becoming callable exactly like any tool defined at the start of the session.

Two query patterns handle most cases:

// Direct selection when you already know the tool name
{ "query": "select:Read,Edit,Grep", "max_results": 10 }

// Keyword search when you don't
{ "query": "slack send message", "max_results": 5 }

The select: prefix does an exact-name fetch — useful when the model already knows which tools it wants (often because it saw them mentioned in a deferred tool list and just needs the schema). Plain keyword queries rank by relevance, similar to retrieval-augmented search but scoped to tool names and descriptions instead of documents.

Why This Matters for Context Management

The token savings compound. If you've connected 15 MCP servers averaging 20 tools each with verbose schemas, that's 300 tool definitions. In a traditional setup, every one of those loads before the conversation starts, whether the task involves Slack, Stripe, or none of the above. With deferred tools, only the always-loaded core tools and whichever deferred tools actually get searched and fetched consume context.

This is the same tradeoff we cover in our context window guide: every token spent on unused tool definitions is a token not spent on your code, your conversation history, or your skills. Deferred tools apply lazy loading to the tool layer the same way pagination and chunking apply it to retrieval — load the metadata, fetch the payload on demand.

The practical effect for a session running dozens of MCP servers: you get the same tool access, but the model isn't drowning in unused schemas before you've typed a word. For solo developers with two or three MCP servers connected, this changes nothing — the always-loaded tier already covers the common case.

What This Means for MCP Server Authors

If you build MCP servers, deferred tools change what makes a tool discoverable. When your tool's full schema isn't in context until it's searched for, the tool's name and any summary text surfaced in the deferred list become the primary hook the model uses to decide whether to search for it at all.

Three practical adjustments:

1. Name tools for search, not just for humans. A tool named x7_proc is invisible to a keyword search for "send message." Names should contain the verbs and nouns a model — or a search query — would naturally use.
2. Front-load the distinguishing keywords. If a query search ranks by matching terms in the name and description, put your tool's most identifying words first, not buried after boilerplate.
3. Don't assume your schema is always visible. Any behavior your tool depends on the model already knowing (required parameter ordering, side effects, rate limits) needs to survive being invisible until searched for and fetched mid-conversation.

This is consistent with the broader MCP security and design guidance we've published: treat your tool definitions as a discoverability surface, not just an API contract. A model that can't find your tool through a reasonable search query effectively doesn't have access to it, deferred or not.

Deferred Tools vs Always-Loaded: When Each Applies

Deferral is decided by the harness, not something you toggle per-server. In practice, the pattern tracks with tool volume and session frequency:

• Core filesystem and shell tools (Read, Write, Edit, Bash, Grep, Glob) stay always-loaded — they're used in nearly every session, and deferring them would mean searching for them constantly, which defeats the purpose.
• High-volume MCP integrations (project management suites, CRMs, cloud platforms with 20+ endpoints) are natural deferred-tool candidates — most of their surface area goes unused in any given session.
• Small, focused MCP servers (a handful of tools, tightly scoped) often don't benefit much from deferral — the schema overhead was never the bottleneck.

If you're comparing MCP servers to add to your setup, tool count is now a real cost signal, not just a capability signal. A server with 60 tools and thin descriptions costs you more in indirect overhead (search calls, fetch round-trips) than a tightly-scoped server with 8 well-named tools, even if deferred tools mean the raw context hit is smaller than it used to be.

The Takeaway

Deferred tools are Claude Code applying the same lazy-loading discipline to tool schemas that good engineers already apply to data: don't load what you don't need yet. For anyone running a handful of MCP servers, this is invisible plumbing. For anyone running the full ecosystem — a dozen-plus servers, hundreds of combined tools — it's the difference between a system prompt that leaves room for your actual work and one that doesn't.

If you maintain an MCP server, treat this as a naming and discoverability exercise: assume every tool call starts with a search, and make sure your tool would actually surface in one.

Build With Us

Running a large MCP setup and hitting context limits? Our consulting team audits MCP tool surfaces and Claude Code configurations for teams running production agent workflows.