What is Gemini API Tool Retrieval?
Tool Retrieval in the Gemini Interactions API loads tool schemas on demand via tool_search and defer_loading, cutting input tokens and keeping tool selection accurate.
Updated ·
Gemini API Tool Retrieval: On-Demand Tool Schemas in the Interactions API
Announcement date:
Tool Retrieval is a preview feature in the Gemini Interactions API that loads tool parameter schemas on demand instead of sending your entire tool library in every prompt. You enable it by adding a tool_search tool to the request and setting defer_loading to true on the tools you want held back. The model still sees each deferred tool's name and description, so it knows what exists, but the full schemas stay out of context until the model asks for one by name. Gemini runs the search on the server, so there is no index to build or host, and there is no separate charge beyond standard token billing.

What Tool Retrieval is and the problem it solves
As an agent grows, its tool library grows with it. Sending every tool's full parameter schema in every prompt inflates input tokens and can make tool selection less reliable. Tool Retrieval is designed to address both: it loads tool parameter schemas on demand rather than shipping the whole library each time, aiming to reduce input tokens and keep tool selection accurate as the agent scales.
The feature is available in preview in the Gemini Interactions API. It is a server-side capability: Gemini performs the search itself, so there is no index for you to build or host.
- Loads tool parameter schemas on demand instead of sending the full tool library in every prompt
- Aims to reduce input tokens and preserve tool selection accuracy as an agent scales
- Available in preview in the Gemini Interactions API
- Server-side search means no index to build or host
How to enable Tool Retrieval with tool_search and defer_loading
Enabling Tool Retrieval takes two changes to your request. First, add a tool_search tool to the request. Second, set defer_loading to true on each tool whose schema you want to hold back. Because Gemini runs the search on the server, those are the only code changes required.
Deferring a tool does not hide it. The model still sees the name and description of every deferred tool, so it knows what is available, but the parameter schemas stay out of context. When the model needs a tool, it asks for it by name, the API loads the full schema, and the model calls the function, all inside the same request.
- Add a tool_search tool to the request
- Set defer_loading: true on the tools you want to hold back
- Names and descriptions of deferred tools remain visible to the model
- Schemas load on demand and the function call completes within the same request
Using Tool Retrieval with remote MCP servers
Tool Retrieval works with remote MCP servers. Instead of listing a server's tools one by one, you set defer_loading to true on the mcp_server tool, and every tool that server exposes is loaded on demand. This makes it practical to connect a large MCP server without enumerating its entire tool surface up front.
- Set defer_loading: true on an mcp_server tool
- Every tool the server exposes is then loaded on demand
- Useful for connecting a large server without listing its tools individually
Server-side versus client-side retrieval
By default the retrieval runs on Gemini's side, which is why no index has to be built or hosted. Client-side retrieval is declared by setting execution to client, and in that mode your application performs the lookup. The trade-off is latency: client-side retrieval adds one round trip per search because your app runs the lookup.
- Server-side retrieval: Gemini runs the search, no index to host
- Client-side retrieval: declared with execution set to client, your app runs the lookup
- Client-side retrieval adds one round trip per search
Pricing and model support
Tool Retrieval has no separate charge. Input and output tokens are billed at the standard rates for the model you call. 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.
In the Interactions API, Tool Retrieval works with Gemini 3.6 and later models, including all Gemini 4 models.
- No separate charge for Tool Retrieval
- Standard input and output token rates apply
- tool_search adds a small fixed input token block
- Loaded schemas are billed as input for the rest of the conversation
- Supported on Gemini 3.6 and later, including all Gemini 4 models, in the Interactions API
Getting started
Because the feature is in preview, the practical starting point is a request in the Interactions API against a supported model. Add the tool_search tool, mark the tools you want deferred with defer_loading: true, and keep the rest of your tool declarations as they are. If you rely on remote MCP servers, defer the mcp_server tool rather than individual tools.
When estimating cost, remember that deferred schemas are not free: once loaded, a schema is billed as input for the remainder of the conversation. Deferring tools you rarely use is the pattern the feature is built around, but the exact savings depend on your tool library and conversation length, so measure against your own workload rather than assuming a fixed reduction.
- Start with a supported model in the Interactions API
- Add tool_search and set defer_loading: true on tools to hold back
- Defer mcp_server tools rather than individual MCP tools
- Account for loaded schemas being billed as input for the rest of the conversation
Questions
Does Tool Retrieval work with remote MCP servers?
Yes. Set defer_loading to true on an mcp_server tool and every tool that server exposes is loaded on demand, so you can connect a large server without listing its tools one by one.
How is Tool Retrieval billed?
There is no separate charge. Input and output tokens are billed at standard rates for the model you call. 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.
Which Gemini models support Tool Retrieval?
In the Interactions API, Tool Retrieval works with Gemini 3.6 and later models, including all Gemini 4 models.
Original sources
Tool Info
Has this tool changed? Help us keep it up to date
Gemini API Tool Retrieval Reviews
Loading reviews…