Google added Tool retrieval (Preview) to the Gemini Interactions API, according to its API changelog entry dated November 19, 2026. Instead of sending every function schema with every request, you mark tools with defer_loading: true, add a {"type": "tool_search"} tool, and Gemini loads a schema only when the model needs it. To start, use the v1beta API version with a supported model and the Interactions API.
What Tool retrieval is
Agents with large tool libraries pay for them in tokens. Every request carries the name, description and parameter schema of each tool, and Google's guide says tool selection accuracy drops as the candidate list grows. Tool retrieval changes what the model sees at the start of a request. For each deferred tool it sees the name and description, but not the parameter schema. When the model decides it needs a tool, the schema is retrieved and the model emits the function call, all in one request in the default mode.
Google's changelog describes the change this way: the Interactions API can now search your tool library and load function schemas on demand, so large tool sets no longer have to be sent in full on every request. Google's announcement on its blog frames the benefits as fewer input tokens, better tool selection and lower latency. Those benefits are Google's claims; the blog itself advises measuring against your own traffic.
There are three ways to handle tools after this release, and the guide compares them:
| Static loading | Server-side retrieval | Client-side retrieval | |
|---|---|---|---|
| Who searches | Nobody (all schemas sent) | Gemini | Your app |
| Extra round trips | None | None | One per search |
| Best for (per the guide) | Fewer than 20 stable tools | Large known libraries and MCP servers | Dynamic registries, namespaces, per-user tools |
Server-side retrieval is the default. The guide recommends it for latency-sensitive apps because the search runs within a single API call.
Who it is for and availability
Tool retrieval is for developers building agents on the Gemini API who have many tools, or who connect remote MCP servers that expose many tools. It is not a consumer feature and has no app setting.
| Item | What Google documents |
|---|---|
| Status | Preview; the API surface may change before general availability |
| API surface | Interactions API only; generateContent does not support it |
| API version | v1beta |
| Supported models | gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash |
| Price | No separate charge; standard model token rates apply |
| Regions and plans | The pages we opened do not list region or plan limits for this feature |
The changelog states support as "Gemini 3.6 and later models, including all Gemini 4 models." The guide's model list is the more specific one, so check it before you pick a model.
For context on price, the Gemini API pricing page lists gemini-3.6-flash at $0.75 per 1M input tokens and $3.75 per 1M output tokens on the Standard paid tier through December 31, 2026, rising to $1.50 and $7.50 from January 1, 2027, as of November 21, 2026. The page labels that model the "previous generation Flash model." Because Tool retrieval adds no fee of its own, its cost is whatever your chosen model charges.
Requirements
- A Gemini API key and the Interactions API (not
generateContent). - The
v1betaAPI version. The guide shows the client setup asgenai.Client(http_options={"api_version": "v1beta"})in Python andnew GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } })in JavaScript. - A supported model from the list above.
- For stateless use (
store=False), an SDK version that supports the new step types (tool_search_callandtool_search_result). - Function tools with full
parametersdefined. The guide says that without them the model cannot call the tool after retrieval.
How to set up Tool retrieval, step by step
Server-side retrieval (default)
- Create a client that uses
v1beta, as shown above. - Add
{"type": "tool_search"}to thetoolsarray. Do not setname,descriptionorparameterson a server-sidetool_search; the guide says those are only for client-side execution. - On each function you want to hold back, set
defer_loading: true. The guide's Python example declares a function with"type": "function", aname(convert_currency), adescriptionand"defer_loading": True, plus its parameters. - Call the Interactions API. The guide's Python call is:
interaction = client.interactions.create(
model="gemini-4-hydrogen",
input="Convert 100 USD to EUR.",
tools=tools,
)- Read
interaction.steps. Google says you will see atool_search_calland atool_search_result, which the API resolves internally, followed by afunction_call. Your application runs only thefunction_call, then returns afunction_resultas usual. - Check
interaction.stepsfor afunction_callon every response. The guide says not to rely onstatusalone, because it is not alwaysrequires_actionwhen a function call is returned.
Optional: add short_description to a deferred function. The guide describes it as a compact summary shown during retrieval instead of the full description, valid only on deferred functions. It suggests naming the service at the start of the text.
Deferring a remote MCP server
Set defer_loading: true on an mcp_server tool next to a server-side tool_search. The guide says this defers every tool the server exposes. When the model calls one, the API runs it on the remote server and returns mcp_server_tool_call and mcp_server_tool_result steps. Connection setup is covered in the Remote MCP section of Google's function-calling documentation.
Client-side retrieval
Use this when you want your own registry, embeddings or permission filters, or want to add tools mid-conversation. The API reference for ToolSearch says execution takes server (default) or client, and that name, description and parameters are set only for client-side execution.
- Declare a
tool_searchtool with"execution": "client", plus aname(the guide's example issearch_tool_registry), adescriptionand the searchparameters. - Turn 1: the model calls your search function.
- Your code runs its own lookup and returns complete function declarations in
function_result.result. Return objects, not JSON strings. - Turn 2: send the
function_resultwithprevious_interaction_id. The returned tools do not need to be in the initialtoolsarray. - Turn 3: the model calls the discovered tool.
This mode costs one round trip per search.
Multi-turn and stateless use
The guide gives these rules:
- Resend the full
toolsarray on every request, including follow-upfunction_resultturns, because the API does not persist tool declarations. - With
store=False, append every model-generated step to your history unchanged, keeptool_search_callandtool_search_resultin order before thefunction_call, and preserve thesignaturefields ontool_search_call,tool_search_result,thoughtandfunction_callsteps.
How to turn it off
Remove defer_loading from the tools and drop the tool_search entry. The tools are then sent in full again (static loading). The guide describes no separate switch.
Limitations
From Google's guide:
- Interactions API on
v1betaonly. - Server-side and client-side retrieval cannot be combined in one request, and you can include one
tool_searchentry per request. defer_loadingworks only with server-side retrieval.- The model may issue several searches in one turn.
- Loaded tools stay in context for the rest of the conversation and cannot be unloaded.
- A search that matches nothing returns a text response, not a structured error.
Best practices the guide lists: leave core, frequently used tools loaded and defer the long tail; do not defer tools named in system instructions or tool outputs, since the model may call them without searching; prefix related tool names by service (for example billing_ and crm_); and for client-side retrieval, list the searchable namespaces in the description.
Common errors the guide names:
| Problem | Fix per the guide |
|---|---|
defer_loading without tool_search | Include tool_search on every request, or remove defer_loading |
Missing tool_search_call in stateless requests | Replay all search steps unchanged |
Missing signature | Append response steps to history without modifying them |
| Unsupported model | Use a model from the supported list |
Privacy and admin notes
The pages we opened say nothing specific about data use or retention for Tool retrieval; it runs inside the Interactions API, so the Gemini API terms for that API apply. Check Google's terms for your tier before sending sensitive data.
Two billing points matter for budgets. Per the guide, deferred tools add only their name and short description to input tokens, and parameter schemas are not billed until loaded. But each loaded schema is appended to the conversation and billed as input for the rest of it, and each server-side search triggers an extra internal model call reported in total_tool_use_tokens at the input rate. Google's blog adds that tool_search itself adds a small fixed block of input tokens. The guide says retrieval saves money with large libraries and few tools used per request, and that small libraries, or long contexts that search every turn, may be cheaper with static loading.
Caching: retrieved schemas are appended rather than changing the prompt prefix, so implicit caching still applies. The guide warns that deferring tools can shrink a prompt below the model's minimum cacheable size.
For related reading on how Google's newest model is billed, see How to Use Gemini 4 Neon.
See also
- Sarvam AI Token Factory: Models, Pricing and the Sovereign AI Debate
- How to use GPT-6.2 Astra and Sol in the API: pricing and limits
- Claude Tool Use in Python: Build a Simple Agent Loop Step by Step
What we checked
- Opened the Gemini API changelog (redirected to aistudio.google.com/docs/changelog) on 2026-11-21: the November 19, 2026 "Tool retrieval (Preview)" entry confirms
defer_loading: true, the{"type": "tool_search"}tool,execution: "client", MCP support and "Gemini 3.6 and later models, including all Gemini 4 models." - Opened the Tool retrieval guide (aistudio.google.com/docs/tool-retrieval) on 2026-11-21: source of the
v1betarequirement, the supported model list, the modes table, the pricing notes, limitations and error list. The guide did not display the full tools array in the page text we read, so we describe its fields instead of reproducing it. - Cross-checked the
ToolSearchschema in the Interactions API reference:executionvaluesserver(default) andclient,defer_loadingon function and MCP server tools, andshort_descriptionfor deferred functions all match the guide. - Opened Google's blog post on Tool retrieval: matches the guide on server and client modes,
interaction.stepscontents and caching; the savings are Google's claims and we did not measure them. - Opened the Gemini API pricing page:
gemini-3.6-flashStandard paid-tier prices quoted above. It showed no separate Tool retrieval price (we read about the first 100,000 of 117,956 characters). - Not tested with a live API key; no request was run and no output was observed. Steps follow Google's documentation as of 2026-11-21, and the feature is in preview, so details may change.
Last tested: 2026-11-21
Comments
Questions and tips are welcome. Comments are checked by the EpiFive team before they appear; please do not share passwords, phone numbers or other private details.