Gemini API Tool Retrieval Preview: Load Tool Schemas On Demand, Supported on Gemini 3.6 and Newer Models
Google has announced Tool Retrieval for the Gemini Interactions API in preview, letting agents load tool parameter schemas only when needed to reduce input tokens and latency. It works with Gemini 3.6 and newer models at no extra charge.
News date: About 6 min read
Contents
On November 19, 2026, Google announced Tool Retrieval for the Gemini API's Interactions API. It is currently in preview, not generally available. The feature targets AI agents, meaning programs that can call external functions (such as looking up an order or issuing a refund) to complete tasks. Each callable function comes with a parameter schema describing the input fields it needs; as the number of tools grows, these descriptions consume many tokens (the unit models use to measure text and bill usage). Google says Tool Retrieval aims to reduce the per-request token load and latency, and to avoid picking the wrong tool as the tool count grows.
What does Tool Retrieval change?
Google notes that when an agent connects to dozens or even hundreds of tools, sending every full parameter schema with each request raises input token counts, adds latency, and lowers tool-selection accuracy as the candidate list gets longer. Tool Retrieval lets the agent keep the full tool library on standby and load the matching parameter schema only when the current task needs it.
According to Google, the model can still see the name and description of every deferred tool, so it knows which tools are available. When needed, the model requests a tool by name, the API loads the full schema, and the model then issues the function call within the same request. All three steps appear in interaction.steps, making it easy to see during debugging which tools the model considered.
How do you enable it, and how do server-side and client-side retrieval differ?
Google says you enable it by adding the tool_search tool to the request and setting defer_loading: true on the tools you want to defer. The most frequently used tools can stay preloaded, with only long-tail tools (the many less frequently used ones) deferred. An MCP server is a way of exposing a whole set of tools to an AI model; with a remote MCP server, setting defer_loading: true on the mcp_server tool makes all tools the server exposes load on demand, without listing them one by one.
| Aspect | Server-side retrieval | Client-side retrieval |
|---|---|---|
| Setup | Add tool_search and set defer_loading: true on tools | Declare tool_search with "execution": "client" and define your own search parameters |
| Index | Google says you need not build or host an index; Gemini runs the search on the server side | Suited to those who maintain their own tool registry, embedding index, or per-user permission filters |
| Extra round trips | Google says search and function call complete within the same request | One extra round trip per search, because the application runs the query |
| Tool declaration | Deferred tools must still be declared (with name and description) | Tools need not be declared in advance and can be added mid-conversation |
Which models are supported, and how is it billed?
Google says Tool Retrieval in the Interactions API works with Gemini 3.6 and newer models, including all Gemini 4 models. There is no separate charge for the feature; input and output tokens are billed at the standard rates of the model being called.
Google also explains that enabling tool_search adds a small fixed number of input tokens, and each schema the model loads is billed as input for the rest of the conversation, just like a tool declared up front. You save tokens when the schemas you never load outweigh the ones you do, and Google recommends evaluating this against your own traffic.
What does it mean for the development workflow?
For teams that already have a large tool library, the main change is one extra tool and one flag in the request, rather than rebuilding a retrieval system. Prefix caching means reusing the unchanged beginning of a prompt to avoid reprocessing it. Google says deferred schemas are not at the start of the prompt and loaded schemas are appended later in the conversation, so the feature is compatible with prefix caching, and the cached prefix stays unchanged across turns.
How do you get started?
- Add the tool_search tool to the tools in your request.
- Set defer_loading: true on the tools you want to defer (for a remote MCP server, set it on the mcp_server tool).
- If you want custom retrieval, declare tool_search with "execution": "client" and define the search parameters.
- See Google's full setup documentation and model comparison, and send feedback to the team on Discord.
Frequently asked questions
Is Tool Retrieval generally available now?
No. Google says it is in preview in the Gemini Interactions API.
How much code needs to change?
With server-side retrieval, Google says you only add the tool_search tool and a defer_loading flag on the tools to defer, with no index to build or host. If you want your own tool registry or permission filtering, you can use client-side retrieval, but each search costs an extra round trip.
Will enabling it always save money?
Not necessarily. Google says there is no separate charge, but tool_search adds a small fixed number of input tokens and loaded schemas are billed as input; you save tokens when the schemas you never load outweigh the ones you do.
How can I see which tool the model chose?
Google says the three steps (the search tool, schema loading, and the function call) all appear in interaction.steps, which you can use to check which tools the model considered and to adjust tool names or descriptions.
Can it be used with MCP servers?
Yes. Google says that setting defer_loading: true on the mcp_server tool makes all of that server's tools load on demand.
Browse the latest news in this topic
Found this guide helpful? Share it with someone who needs it
Claude Code 2.1.329: Code Mode Works With Telemetry, /tasks Lists Scheduled Tasks, macOS Computer Use Gets Stricter Safety Rules
Anthropic's changelog lists Claude Code 2.1.329, covering Code Mode behavior changes, new diagnostics in /tasks and /mcp, /code-review changes, and new safety rules for macOS computer use.
Kimi Code CLI v2.7.0 Adds a Native Amazon Bedrock Provider: Use Your AWS Credentials Instead of a Separate API Key
AWS Rounds Up 13 SageMaker Inference Features: Managed NVIDIA Dynamo on HyperPod, MIG GPU Partitioning, Cross-Region Routing
BMW Group Shares How It Governs AI Agents: 12,500+ Developers, Three Autonomy Levels and a Four-Stage CI/CD Gate
Sources
Compiled from the references and verification dates listed above; fares, schedules, product features, and terms can change, so please confirm the latest details on the relevant official website before travelling, booking, or purchasing.