Google Puts Tool Retrieval in the Gemini API: Defer Tool Schemas and Let the Server Load Them on Demand
Tool Retrieval is in preview in the Gemini Interactions API: add a tool_search tool, set defer_loading on the long tail, and the server loads parameter schemas on demand. What that changes for tokens, prefix caching, MCP catalogs and debugging — and where the saving does not show up.
Google put Tool Retrieval into preview in the Gemini Interactions API on Nov. 19, 2026. Turning it on takes two edits to a request: add a tool_search tool, and set defer_loading: true on the tools you want held back. The model still knows every tool exists. It just stops carrying every parameter schema.
For anyone running an agent against a large tool catalog, that is the difference between a context window full of JSON you mostly ignore and one that holds names and descriptions until a task actually needs more.

The problem Google is naming
Google’s announcement is blunt about the failure mode. When an agent connects to dozens or hundreds of tools, sending every full parameter schema on every request “adds up fast”: it inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows.
Tool Retrieval splits what the model sees. A deferred tool keeps its name and description in context; its parameter schema stays out. When the model needs that tool it asks for it by name, the API loads the full schema, and the model emits the function call — all inside the same request.
Two details carry most of the practical weight:
- No index to build or host. Gemini runs the search on its own servers. The only changes to your code are the new tool and a flag on the tools you defer.
- No extra round trip in the default mode. Search, schema load and function call all happen inside one interaction.
That is a different division of labor from the coding-agent side of the market. Claude Code’s overview docs and Qwen Code’s both present MCP as the way the harness reaches external systems — Google Drive, Jira, Slack, your own tooling — which means the harness is what enumerates and declares those tools. Tool Retrieval moves the narrowing to the provider, inside the request.
Turning it on
The announcement’s sample defers a long tail of functions while leaving the frequent ones loaded up front:
tools = [
{"type": "tool_search"},
{
"type": "function",
"name": "issue_refund",
"description": "Refund an order to the original payment method.",
"defer_loading": True,
"parameters": {"type": "object", "properties": {...}},
},
# ... 50+ other deferred functions (leave frequent tools undeferred)
]
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Order A-1042 arrived damaged. Please refund 40 dollars.",
tools=tools,
)
Inside that single call the model searches for issue_refund, the API loads its schema, and the model emits the call. All three moves land in interaction.steps:
[
{"type": "tool_search_call", "id": "tsc_7f2a",
"arguments": {"function_names": ["issue_refund"]}},
{"type": "tool_search_result", "call_id": "tsc_7f2a",
"result": [{"type": "function", "name": "issue_refund", "parameters": {...}}]},
{"type": "function_call", "id": "fc_91c3", "name": "issue_refund",
"arguments": {"order_id": "A-1042", "amount": 40}}
]
Read that array as a debugging surface, not just plumbing. Google frames it explicitly as a way to inspect which tools the model considered when you are fixing a tool name or description. In a harness-side setup you infer that from behavior; here it is in the response.
Five things to do with it
- Defer the long tail, keep the hot path loaded. Google’s own sample comment says to leave frequent tools undeferred. Deferring a tool the model needs every turn buys nothing and adds a search step.
- Point one flag at a whole MCP server. Setting
defer_loading: trueon anmcp_servertool defers every tool that server exposes, so a large remote server no longer has to be listed tool by tool. - Re-check your prefix cache breakpoints. Deferred schemas stay out of the start of the prompt and loaded ones arrive later in the conversation, which Google says keeps the cached prefix identical from turn to turn. If you positioned cache breakpoints around a big tool block, that block is no longer there.
- Use client-side execution when you own the lookup. Declaring
tool_searchwith"execution": "client"and your own search parameters keeps a registry, an embedding index or a per-user permission filter in your code. It costs one round trip per search — and because tools no longer need to be declared up front, you can expose a new tool mid-conversation when a user connects an integration. - Log the steps from day one.
tool_search_callsays what the model asked for;tool_search_resultsays what came back. Those two entries are the shortest route to a description rewrite.
What it costs
There is no separate charge: input and output tokens bill at the standard rate for the model you call. Two things change the arithmetic.
Turning on tool_search adds a small, fixed block of input tokens, and Google does not publish its size. And every schema the model loads is billed as input for the rest of the conversation, exactly like a tool declared up front.
That second point is the one to plan around. A loaded schema is not a one-off charge; it recurs every turn from the moment it loads. Deferring is a bet that a tool will not be needed, and losing the bet costs what declaring it would have cost — plus the search block.
Google’s own conclusion is conditional: you save tokens when the schemas you never load outweigh the ones you do, which it calls “the usual case for large libraries,” followed immediately by “measure it against your own traffic.” Take that as the instruction it is.
Constraints before you plan around it
| Item | Status in the announcement |
|---|---|
| Availability | Preview, in the Interactions API |
| Models | Gemini 3.6 and later, including all Gemini 4 models |
| Pricing | No separate charge, standard token rates |
| Accuracy claim | Asserted, no benchmark published in the post |
tool_search block size |
Not published |
The samples call client.interactions.create with model="gemini-4-hydrogen", and the post links out to a full setup guide in Google’s AI Studio docs rather than carrying reference detail itself.
Why it matters past Google’s API
Tool sprawl is the tax every operator of a large MCP catalog already pays, and the usual answers are all yours to build: hand-curate a subset, split work across subagents with narrower rosters, or put a gateway in front of the catalog. Harness engineering treats a bloated tool list as a design failure for exactly this reason — every exposed tool costs window space and decision noise, not only tokens. Server-side retrieval is the provider taking that problem off your side of the boundary.
If you build on the Gemini API, the change is small enough to test this week: mark the long tail deferred, read the steps on a real task, and compare a week of bills before you believe the saving. If you build on MCP elsewhere, the sharper question is who narrows the tool list next — your harness, your gateway, or the model provider.
Sources: Google, Introducing Tool Retrieval in the Gemini API · Claude Code overview docs · Qwen Code overview docs. Related reading: prompt caching and context engineering.