Does lazy loading change what tools an agent can use?

No. Every tool remains callable; lazy loading only changes when its full definition enters the model's context. The agent can still search for and call any tool the server exposes.

Do I need to configure anything to get lazy loading in Claude Code?

No. Tool search is enabled by default for supported models (Claude Sonnet 4.5, Haiku 4.5, Opus 4.5, and later). It's disabled automatically in a few edge cases, like a non-first-party ANTHROPIC_BASE_URL, and can be controlled explicitly with the ENABLE_TOOL_SEARCH environment variable.

How much does lazy loading actually save?

Measured reductions run over 85% in token usage on tool definitions for sessions connecting many MCP servers, compared to loading every tool's full description upfront.

Should I mark my own MCP tools for deferred loading?

If you're calling the API directly and have more than a handful of tools, yes: use defer_loading: true on the less frequently used ones and write clear server instructions so the model knows when to search for them.

What Is Lazy Loading for MCP Tools?

Lazy loading for MCP tools means an AI client loads only tool names and short server instructions into context at the start of a session, then fetches a tool's full description and schema only at the moment the agent decides it might need it.

The alternative (loading every connected server's full tool catalog upfront) is what most MCP clients did by default until recently, and it quietly ate tens of thousands of tokens before a user typed a single question.

This piece covers how lazy loading works, the token math behind it, and when eager loading is still the better choice. It also looks at what changes for MCP server authors, and how it plays out on a live Wati MCP connection.

The Problem Lazy Loading Solves

Every MCP tool a server exposes carries three pieces of metadata the calling model needs before it can ever use that tool. That's an identifying name, a plain-English explanation of what it does, and a schema spelling out its expected parameters.

An MCP client has to hand all of that to the underlying model before the model can call any of it. That's simply how tool-calling works.

The question is when. Historically, the answer was "immediately, for every connected server, whether or not the session ever touches half of them," and that default scales badly.

A developer running even a handful of MCP servers, say a project tracker, a database tool, and a messaging platform, can end up with dozens of tool definitions loaded before the conversation starts.

Documented setups with seven-plus servers have consumed over 67,000 tokens purely on tool descriptions. That's context budget spent on tools that might never get called in that session, competing directly with the room needed for actual conversation history and retrieved data.

How Lazy Loading Actually Works

Instead of sending full tool definitions upfront, a lazy-loading client sends only tool names and brief server-level instructions when a session starts.

When the model's task looks like it might need a specific capability, it searches (using a dedicated search mechanism rather than scanning full definitions) and only then receives the complete description and schema for the matching tool or tools.

The model calls the tool the same way it always would. The difference is purely in when the definition enters its context.

Anthropic's implementation exposes this as a configuration option. Each tool in an MCP toolset can be marked with defer_loading: true, which withholds its description from the model initially and requires the Tool search tool to retrieve it before use.

Claude Code applies the same idea automatically to MCP connections, where tool search is on by default for models that support it (Claude Sonnet 4.5, Haiku 4.5, Opus 4.5, and later), and it requires no configuration from the person connecting a server.

Token Savings: What Tool Search Actually Cuts

The measured effect is a reduction of around 85% in tokens spent on tool definitions for sessions with many connected servers, because only the tools actually searched for and used ever get their full definitions loaded.

This isn't a rounding improvement: it's the difference between a server connection costing a few hundred tokens versus tens of thousands, and it's why Claude Code's own documentation states plainly that adding more MCP servers has "minimal impact" on context usage once tool search is active.

Server count stops being the operative number here; what you're actually spending, and budgeting for, is context window space.

There's a threshold-based middle ground too. Setting ENABLE_TOOL_SEARCH=auto loads tool definitions upfront only while their combined size stays under a percentage of the context window, 10% by default, configurable via auto:N, then switches to deferring once that threshold is crossed.

This matters if you're running a small number of lightweight servers where the eager-loading overhead is negligible and you'd rather skip the extra search round-trip.

What Server Authors Should do Differently

Lazy loading changes what the model sees first, which means server instructions carry more weight than they used to.

Instead of the model reading every tool's full description to decide relevance, it reads a short server instruction and a bare tool name, then decides whether to search further.

Anthropic's guidance for server authors is direct. Write server instructions that state what category of tasks your tools handle, when Claude should search for them, and your key capabilities, and keep it concise, since both tool descriptions and server instructions truncate at 2KB.

Front-load the decision-relevant details. Anything after the truncation point never reaches the model at all.

Loading mode	What loads at session start	Context cost	Best for
Eager (no tool search)	Full name + description + schema, every tool	Grows linearly with server count	Very few servers, or clients without tool search support
Lazy / deferred	Tool names + short server instructions only	Roughly flat regardless of server count	Multiple servers, large tool catalogs
Threshold (auto:N)	Full definitions until N% of context window, then defers	Mixed	A small, known set of lightweight servers

How Lazy Loading Shows Up on a Wati MCP Connection

A Wati MCP session spans several distinct task categories. These include contact management, template sending, campaign review, conversation and message history, and Astra AI Agent operations.

Loaded eagerly, that's a lot of tool text competing for space on every single message, most of it irrelevant to whatever the user actually asked. With lazy loading active, the default behavior in Claude Code and available through defer_loading on the API, the assistant sees short names for all of it at session start.

It then pulls the full schema for send_template only when a request actually calls for sending a template, not for every unrelated question about contacts or campaigns.

When Eager Loading Still Makes Sense

Lazy loading isn't free. It costs a search round-trip the first time the model needs a tool in a given session.

If you're connecting a single MCP server with four or five tools total, the overhead of eager loading is small enough that the extra search step isn't worth it, which is exactly what the auto threshold mode is designed to detect and skip automatically.

The decision matters most once you're running multiple servers or a server with a genuinely large tool catalog: that's the regime where lazy loading's token savings become the difference between a usable session and one that runs out of context budget before real work starts.

See It In Action on Your Own Wati Workspace

Connect Claude to Wati's MCP server, and you will see lazy loading in action. Only the tool names show up until a request calls for something specific; then the full schema loads.

Want a walkthrough first? Book a free demo, and we will show you exactly how it works.