Deferred MCP tool schema loading definition
Deferred tool schema loading is a technique where an AI agent starts with only a lightweight index of its available tools and loads a tool's full definition and parameter schema into the context window on demand, once a search or selection step finds that tool relevant to the task.
Deferred tool schema loading keeps a large MCP tool catalog out of the context window. The agent first sees a lightweight index, such as a search tool or tool names with short descriptions. A tool's full JSON Schema loads only when a search step matches it to the request. In Sanity, a Context MCP endpoint applies the same principle to content: initial_context returns a compressed schema overview, and schema_explorer loads one type's fields only when the agent asks for them.

Why do large MCP tool catalogs fill the context window?
Large MCP tool catalogs fill the context window because every tool definition is text the model has to read before it can do anything. Under the MCP specification, a server's tools/list response returns each tool's name, its description, and its full inputSchema, which is the JSON Schema that describes the tool's parameters. In Code execution with MCP, Anthropic writes that "most MCP clients load all tool definitions upfront directly into context." As a result, token cost grows with every server an agent connects to.
Those costs add up quickly. In Introducing advanced tool use, Anthropic describes a setup with five servers (GitHub, Slack, Sentry, Grafana, and Splunk) that adds up to 58 tools and about 55,000 tokens before the conversation even starts. The same post says Anthropic has seen tool definitions take up 134,000 tokens before optimization.
The second cost is accuracy. Anthropic's tool search documentation says Claude's ability to pick the right tool degrades once it has more than 30 to 50 tools available. The advanced tool use post names the most common failures as choosing the wrong tool and filling in the wrong parameters, especially when tools have similar names. So a bloated tool catalog costs tokens, adds latency, and leaves less room for conversation history. It also makes the agent worse at choosing tools.
How does deferred tool schema loading work step by step?
Deferred tool schema loading splits the tool catalog into two parts: a small set the model always sees, and a larger set it searches for. In the Anthropic Messages API and the OpenAI Responses API, the process has five steps.
First, the client declares every tool but marks most of them with defer_loading: true. Second, the model starts with a tool search tool plus any tools that are not deferred. Anthropic requires at least one tool, normally the search tool itself, to stay non-deferred. Third, when the model needs a capability, it searches the catalog. Anthropic's search covers tool names, descriptions, argument names, and argument descriptions. Fourth, the API returns references to the matching tools and expands them into full definitions. In Anthropic's API these are tool_reference blocks, up to five by default. Fifth, the model calls the tool it found.
What the model sees at the start depends on the implementation. OpenAI's tool search guide explains that the model still sees the name and description of each deferred function, so in practice tool search mostly defers the parameter schema. A deferred namespace or MCP server shows only its own name and description at first. In Anthropic's version, the model initially sees only the search tool and any non-deferred tools.
Anthropic reports large savings. With its Tool Search Tool, only the search tool loads upfront, at about 500 tokens, and three to five relevant tools load on demand. That brings its example from about 77,000 tokens down to about 8,700, an 85% reduction. On Anthropic's MCP evaluations, accuracy with tool search rose from 49% to 74% for Claude Opus 4 and from 79.5% to 88.1% for Opus 4.5.
How is deferred tool loading different from progressive disclosure, tool gating, and context compression?
Deferred tool schema loading is a form of progressive disclosure, the design principle of showing a summary first, and the details on demand. Deferred loading applies that principle specifically to tool definitions. Tool gating and context compression are different techniques that solve related problems.
Tool gating, also called tool filtering, is a fixed decision by the developer or by a policy about which tools an agent may see at all. Gating removes tools from the catalog. Deferred loading keeps every tool reachable, and only delays loading its schema. Teams often combine the two, for example by filtering an MCP server's tools in the client, and then deferring the rest.
Context compression, sometimes called compaction, shrinks content that is already in the context window, for example by summarizing older conversation turns or trimming long tool results. Deferred loading keeps tool definitions out of the context in the first place. Compression reduces what is already there, while deferral prevents it from arriving.
Progressive disclosure can also work without a search tool. Anthropic's Code execution with MCP post presents MCP tools as files in a code tree, so the agent reads only the tool files it needs. Anthropic reports that this cut token usage in its example from 150,000 tokens to 2,000, a 98.7% reduction. Code execution also targets a different cost, the tokens spent on intermediate tool results rather than on tool definitions.
Is deferred tool loading the same as retrieval-based tool selection?
Deferred tool schema loading and retrieval-based tool selection are closely related because both search the tool catalog to find relevant tools. The difference is where that search happens.
RAG-MCP uses semantic retrieval over a tool registry to choose relevant tools before the prompt is built. Semantic retrieval means matching by meaning rather than exact keywords. The authors report that compared with a baseline that exposed every tool, this cut prompt tokens by more than 50% and raised tool-selection accuracy from 13.62% to 43.13%.
Deferred loading with a tool search tool moves the search inside the agent loop. The model runs the search itself when it decides it needs a capability. Then the API loads the full definitions of the tools that match.
Does the MCP specification define deferred tool loading?
No. The MCP specification does not define deferred tool schema loading. Deferral is a behavior of the client or the model API, layered on top of MCP. Anthropic's tool search tool and OpenAI's tool_search implement it at the API level, and Claude Code applies tool search to MCP tools. The MCP server itself still returns full definitions from tools/list.
Two features in the MCP specification are easy to confuse with deferral. The first is pagination: tools/list can split a long list across several requests using cursor and nextCursor, but that alone does not keep schemas out of the model's context. The second is the notifications/tools/list_changed message, which tells clients that a server's tool list has changed. That keeps the client's catalog current, but it does not delay loading anything.
Because deferral happens in the client, MCP server authors cannot turn it on themselves. What they control is the size and clarity of the tool catalog they expose.
How should an MCP server over structured content limit its tool catalog?
In our experience, the most practical way to keep an MCP server over structured content cheap in tokens is to expose a few focused tools, and let the content schema carry the detail. Sanity is the AI Content Operating System, the intelligent back end for companies building AI content operations at scale. Its Context MCP, the MCP surface of Sanity Context, follows this pattern. An endpoint over a Content Lake dataset serves four tools: initial_context, schema_explorer, groq_query, and array_field_reader. A Knowledge Base source, currently in beta, serves three tools: initial_context, knowledge_base_read, and knowledge_base_search.
Sanity Context applies progressive disclosure to the content schema, not to tool schemas. The initial_context tool returns a compressed overview of the schema plus instructions for querying the content. The schema_explorer tool returns the detailed fields and references for a single type, and only when the agent asks for it. As a result, the agent's starting view of the content stays compact.
The client still decides which of these tools the agent sees. A Context MCP endpoint serves every tool its sources offer, and teams that want fewer can filter them in their client. A common case is dropping initial_context after copying its output directly into the
Discover More with Sanity
Now that you've learned about Deferred MCP tool schema loading, why not start exploring what Sanity has to offer? Dive into our platform and see how it can support your content needs.
Last updated: