
News
Gemini API Tool Retrieval loads schemas only when an agent needs them
Google’s Gemini Interactions API can now defer tool and remote MCP schemas and load them on demand, with no separate Tool Retrieval fee.
Google launched Tool Retrieval in preview in the Gemini Interactions API on November 19, 2026. Agents can keep a large tool library on standby and load parameter schemas only when the current task needs them, instead of sending every full schema on every request.
Lucia Loher, product manager for the Gemini API, and Nora Kassner, a research scientist at Google DeepMind, wrote the announcement. The same day, Google for Developers pointed at the post and said Tool Retrieval lets you "scale to hundreds of tools without context bloat," load parameter schemas on demand, preserve selection accuracy, cut tokens, and keep the prefix cache intact.
The post is direct about the cost of the old pattern. When an agent connects to dozens or hundreds of tools, sending every full parameter schema inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows. The setup guide puts a figure on the same problem: a few dozen function declarations can consume tens of thousands of tokens on every request.
Server-side retrieval
The default path needs two changes and no index to host. Add a tool_search tool, and set defer_loading to true on the functions you want to hold back. The model still sees each deferred tool's name and description. The parameter schemas stay out of context until the model asks for a tool by name. The API then loads the full schema and the model emits the function call, all inside the same request.
Those steps land on interaction.steps as tool_search_call, tool_search_result, and function_call. Your code still runs the function and sends back a function_result. Frequent tools can stay loaded; the long tail can wait. Both the blog and the docs call gemini-4-hydrogen in the example.
The documentation adds constraints the announcement sample does not spell out. Tool retrieval is preview, requires the v1beta API version, and works only on the Interactions API. generateContent does not support it, and the API surface may change before general availability. You can include one tool_search entry per request. On a server-side tool_search, do not set name, description, or parameters. An optional short_description can replace a long description in the deferred list, and it is valid only when defer_loading is true.
MCP servers and client-side search
Set defer_loading to true on a remote mcp_server tool and every tool that server exposes is deferred, so you can connect a large server without listing its tools one by one. When the model retrieves and calls one of those tools, the API executes it on the remote server and returns mcp_server_tool_call and mcp_server_tool_result steps in the same response.
Client-side retrieval is the other mode. Declare tool_search with execution set to client, give it a name and description, and your application runs the lookup. That adds one round trip per search. Tools do not have to be declared up front, so you can introduce new tools mid-conversation when a user connects an integration. The docs' comparison table lists this mode as best for dynamic registries, namespaces, or per-user tools. Server-side retrieval is the fit for large, known libraries and remote MCP servers, especially when latency matters, because the search stays inside one API call. Static loading, with every schema sent on every request, is what that table recommends for fewer than 20 stable tools.
The two retrieval modes cannot be combined in the same request, and defer_loading applies only to server-side retrieval.
What you actually pay
There is no separate Tool Retrieval fee. Tokens are billed at the standard input, cached, and output rates for the model you call.
The announcement says turning on tool_search adds a small, fixed block of input tokens, and each schema the model loads is billed as input for the rest of the conversation, the same as a tool declared up front.
The documentation accounts for tokens separately. Deferred tools add only their name and short_description (or the first sentence of description) to total_input_tokens. Parameter schemas are not billed until they are loaded. Each server-side search also triggers an extra model call inside the request, with the full context plus the loaded schemas. Those prompt tokens are reported in total_tool_use_tokens and are billed at the input rate.
You save tokens when the schemas you never load outweigh the ones you do, which the post calls the usual case for large libraries. The docs add the other case: with a small library, or a very long context that searches on every turn, static loading can cost less. Measure it on your own traffic.
Deferred schemas stay out of the start of the prompt. Loaded schemas are appended later, so the cached prefix can stay stable from turn to turn. Shrinking the prompt can also drop a medium prompt below the model's minimum cacheable size, which means implicit caching may stop applying.
The announcement says the feature works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API. The documentation lists six supported IDs: gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, and gemini-3.6-flash. Calling an unsupported model returns an error that deferred loading is not supported for that model.
Limits that change how you wire it
Loaded tools stay in context for the rest of the conversation and cannot be unloaded. The model may issue several search calls in one turn when it needs several tools. A search that matches nothing produces a text response, not a structured error.
Tool declarations are not persisted across turns. Send the full tools array on every request, including follow-ups that return a function_result. If you manage history yourself with store set to false, replay tool_search_call and tool_search_result in their original order and keep each step's encrypted signature. Dropping a tool_search_call or stripping a signature returns a 400. Omitting tool_search_result does not error, but it drops the loaded schemas from context. Do not defer tools that your system instructions name; the model may call them without searching first.
Read the tool retrieval guide before you flip the flag on a production agent. It has the mode table, Python, JavaScript, and REST examples, and the error list. Start with server-side retrieval on a listed model in the Interactions API on v1beta, leave the tools you hit on most turns undeferred, and compare token counts with static loading before you defer an entire remote MCP server.
Sources
- Introducing Tool Retrieval in the Gemini API blog.google
- Tool retrieval — Gemini API documentation aistudio.google.com
- Google for Developers on X x.com