Gemini API Tool Retrieval Launches in Preview | Zeniteq
Loading
Zeniteq is now available on mobile for iPhone, iPad and Apple Watch.Download nowLearn more
Gemini API Tool Retrieval Launches in Preview
Google’s new Interactions API preview loads tool schemas on demand, with savings that depend on catalog size, conversation length and search frequency.
Google’s new Tool Retrieval feature for the Gemini Interactions API allows developers to offload large function schemas from the model’s active context until needed. By setting defer_loading to true, agents only load parameter definitions when a specific tool is selected, reducing input token consumption for large catalogs. This optimization is particularly effective for extensive function libraries, though it introduces search overhead. Developers must weigh these costs carefully, as the extra model passes required for retrieval can increase expenses in scenarios with smaller catalogs or large existing contexts, making it a strategic choice rather than a universal cost-saver.
Google launched Tool Retrieval in preview for the Gemini Interactions API on November 19, 2026, giving developers a way to keep large tool parameter schemas out of the model’s context until they are needed. Developers opt in by adding a tool_search tool and setting defer_loading: true on selected tools, according to Google’s announcement.
The feature targets agents connected to dozens or hundreds of functions. Each function normally comes with a schema describing its arguments, data types and required fields. Sending all those definitions into the model’s context consumes input tokens even when a task needs only one function.
Google says deferred loading can reduce input-token costs and latency while keeping tool selection accurate as catalogs grow. The qualification is that retrieval introduces work of its own. A smaller initial prompt does not automatically mean a cheaper complete interaction.
What Stays in Context, and What Gets Deferred
Tool Retrieval separates a function’s discoverability from its detailed calling instructions.
The model initially sees each deferred tool’s name and description. Its parameter schema stays outside the context until the model requests that tool by name. The API then loads the schema, allowing the model to construct a function call with the required arguments.
For a refund function, those layers might be:
Initially visible: A function named issue_refund, with a description explaining that it refunds an order.
Loaded when selected: A schema requiring an order_id string and an amount number.
Generated afterward: A function call containing the particular order identifier and refund amount.
Google’s launch post says the search, schema loading and function-call generation can happen within the same API request.
That makes names and descriptions especially important. My reading is that deferred loading moves more of the initial selection burden onto those short descriptions: a detailed parameter schema cannot help the model choose a tool before that schema has been retrieved. Clear distinctions between similarly named functions become a practical requirement.
Frequently used tools can remain fully loaded. Developers can defer specialized functions while keeping common actions immediately available.
The server-side opt-in requires two changes: include a tool_search entry and mark the tools whose schemas should be deferred.
This illustrative Python fragment assumes refund_tool already contains a complete function declaration, including its name, description and parameter schema:
Pass that list as the tools argument to client.interactions.create, using a supported Gemini model. The fragment shows the configuration change; it is not a complete application and has not been executed here.
In Google’s example, the resulting interaction.steps includes three useful records:
tool_search_call, identifying the requested function.
tool_search_result, containing the retrieved declaration and parameters.
function_call, containing the function name and generated arguments.
Those records give developers a way to distinguish retrieval problems from argument-generation problems. If the wrong tool is selected, its name and description are worth inspecting. If the correct tool is selected but receives unsuitable arguments, the schema and subsequent function-call generation need attention.
Retrieving a function is separate from executing it. For custom functions, application code still performs the operation and sends back a function_result. A generated refund call does not itself move money. Authorization, argument validation and business rules remain application responsibilities.
Remote MCP Servers Can Be Deferred Too
Google also supports deferred loading for tools exposed through remote Model Context Protocol, or MCP, servers. Set defer_loading: true on an mcp_server tool, and the tools that server exposes become available on demand without declaring each one individually.
That is a useful fit for broad integrations. A remote server may expose many operations, while a particular conversation needs only a small subset. Deferring the server’s tools limits the parameter schemas brought into context for that task.
The announcement also describes compatibility with prefix caching. Retrieved schemas are inserted later in the conversation, leaving the earlier prompt prefix unchanged. This preserves a stable prefix across turns, although it does not remove the input-token charges associated with loaded schemas.
Server-Side and Client-Side Retrieval Differ
The default server-side path lets Gemini handle retrieval. Developers do not need to build or host a search index for that mode.
Client-side retrieval gives the application control over searching, ranking and filtering tools. Unite.AI’s coverage of the setup documentation describes it as an option for applications with their own registries, embedding indexes or permission filters.
Detail
Server-side retrieval
Client-side retrieval
Who handles retrieval?
Gemini handles selection and schema loading
Application code searches and returns tools
Catalog handling
Deferred tools are declared in the request
Tools can be introduced during the conversation
Extra work
A billed model pass for each search
An application round trip for each search
Useful fit
A known catalog with minimal retrieval infrastructure
Custom ranking, user-specific filtering or newly connected integrations
The distinction matters for applications where tool access changes by user or session. I’d favor client-side retrieval when discovery needs application-specific filtering that cannot be expressed adequately through a fixed catalog. That control comes with more orchestration and another round trip.
Unite.AI reports that requests allow exactly one tool_search definition and cannot combine server-side and client-side retrieval. These are alternative retrieval paths within a request, not two stages to stack together.
No Separate Fee Does Not Mean No Retrieval Cost
Tool Retrieval carries no separate feature charge, but normal model input and output charges still apply. Loaded schemas are billable input.
The more consequential detail is the extra model work. PPC Land’s analysis of Google’s documentation reports that every server-side search adds a model pass using the full context and newly loaded schemas. That prompt is reported as tool-use tokens and charged at the input rate.
The cost components therefore include:
A small, fixed block of search instructions.
Compact entries identifying deferred tools.
Full schemas for tools that are retrieved.
Additional input processing for server-side search passes.
Ordinary model output.
PPC Land reports that Google’s early testing put the compact entry at about 26 tokens per deferred tool. That figure is a vendor-reported observation, not a fixed size developers should assume for every description.
Google’s announcement supplies no measured benchmark for savings or selection accuracy. The numerical examples below come from documentation summarized by secondary reporting, not independent product tests.
Large Catalogs and Small Catalogs Can Produce Opposite Results
200 tools at 400 tokens each, with two tools retrieved
164,000 input tokens
About 23,650 input and tool-use tokens
10 tools at 400 tokens each, with a 30,000-token context
68,000 input tokens
About 92,830 input and tool-use tokens
The first example shows why deferred loading is attractive: leaving most of a large catalog unused avoids substantial schema overhead.
The second exposes the trade-off. With fewer schemas to avoid and a large existing context, processing that context again for search can cost more than loading the tools upfront.
These examples support a narrower conclusion than “retrieval saves tokens”: retrieval helps when avoided schema processing outweighs the additional search work. Catalog size, schema length, search frequency and conversation length all affect that balance.
I’d begin by deferring infrequently used, schema-heavy functions. Deferring every function by default risks paying search overhead for actions the agent uses on nearly every task.
Deferred Context Is Not a Smaller API Payload
Developers also need to distinguish the request sent to the API from the content initially loaded into model context.
According to Unite.AI’s account of the documentation, the complete tools array must still be resent on every request, including requests chained through previous_interaction_id. Tool declarations are not stored between requests.
The practical implication is that server-side deferred loading is a model-context optimization, not a way to stop transmitting the catalog. Applications still need to construct and send their declarations.
Retrieved schemas also cannot be unloaded during a conversation. A long-running agent that gradually touches much of its catalog will retain more schema content over time. Early-turn savings therefore should not be treated as representative of an entire session.
For evaluation, I’d compare complete task costs and latency, recording search frequency and the number of distinct schemas loaded. Measuring only the first prompt would miss the feature’s main trade-off.
Model Support and Preview Boundaries
Google says Tool Retrieval supports Gemini 3.6 and later models, including Gemini 4 models. Unite.AI reports that the setup guide explicitly lists Gemini 4 Argon, Gemini 3.8 Flash and Gemini 3.6 Flash, and that setting defer_loading on an unsupported model returns a 400 error.
This release is an Interactions API preview, not a generally available Tool Retrieval release. Unite.AI also reports that the older generateContent method does not support it and that the preview API surface may change.
For existing agents, that means checking the API interface and exact model support before treating this as a configuration-only update. For large catalogs already using Interactions, the new flags offer a relatively direct way to test deferred schemas against a fully loaded baseline.
Frequently Asked Questions
3 questions
1
Is Gemini Tool Retrieval Generally Available?
No. Google launched it in preview through the Interactions API on November 19, 2026.
2
Does Retrieval Execute Custom Functions?
No. It loads the schema and lets the model generate a function call. Application code still executes the function and returns its result.
3
Will It Always Reduce Token Costs?
No. Server-side searches add billed model work. Google’s illustrative examples show that a small tool catalog combined with a large context can cost more with retrieval.