AI engineering

How to Set Up Gemini API Tool Retrieval: Models, Pricing, Limits

Google put Tool retrieval in preview in the Gemini Interactions API on November 19, 2026. See the models, the steps, how it is billed and its limits.

By EpiFive Editorial TeamReviewed/updated 9 min readHow we check our guides
On this page

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 loadingServer-side retrievalClient-side retrieval
Who searchesNobody (all schemas sent)GeminiYour app
Extra round tripsNoneNoneOne per search
Best for (per the guide)Fewer than 20 stable toolsLarge known libraries and MCP serversDynamic 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.

ItemWhat Google documents
StatusPreview; the API surface may change before general availability
API surfaceInteractions API only; generateContent does not support it
API versionv1beta
Supported modelsgemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flash
PriceNo separate charge; standard model token rates apply
Regions and plansThe 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 v1beta API version. The guide shows the client setup as genai.Client(http_options={"api_version": "v1beta"}) in Python and new 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_call and tool_search_result).
  • Function tools with full parameters defined. 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)

  1. Create a client that uses v1beta, as shown above.
  2. Add {"type": "tool_search"} to the tools array. Do not set name, description or parameters on a server-side tool_search; the guide says those are only for client-side execution.
  3. On each function you want to hold back, set defer_loading: true. The guide's Python example declares a function with "type": "function", a name (convert_currency), a description and "defer_loading": True, plus its parameters.
  4. 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,
)
  1. Read interaction.steps. Google says you will see a tool_search_call and a tool_search_result, which the API resolves internally, followed by a function_call. Your application runs only the function_call, then returns a function_result as usual.
  2. Check interaction.steps for a function_call on every response. The guide says not to rely on status alone, because it is not always requires_action when 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.

  1. Declare a tool_search tool with "execution": "client", plus a name (the guide's example is search_tool_registry), a description and the search parameters.
  2. Turn 1: the model calls your search function.
  3. Your code runs its own lookup and returns complete function declarations in function_result.result. Return objects, not JSON strings.
  4. Turn 2: send the function_result with previous_interaction_id. The returned tools do not need to be in the initial tools array.
  5. 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 tools array on every request, including follow-up function_result turns, because the API does not persist tool declarations.
  • With store=False, append every model-generated step to your history unchanged, keep tool_search_call and tool_search_result in order before the function_call, and preserve the signature fields on tool_search_call, tool_search_result, thought and function_call steps.

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 v1beta only.
  • Server-side and client-side retrieval cannot be combined in one request, and you can include one tool_search entry per request.
  • defer_loading works 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:

ProblemFix per the guide
defer_loading without tool_searchInclude tool_search on every request, or remove defer_loading
Missing tool_search_call in stateless requestsReplay all search steps unchanged
Missing signatureAppend response steps to history without modifying them
Unsupported modelUse 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

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 v1beta requirement, 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 ToolSearch schema in the Interactions API reference: execution values server (default) and client, defer_loading on function and MCP server tools, and short_description for deferred functions all match the guide.
  • Opened Google's blog post on Tool retrieval: matches the guide on server and client modes, interaction.steps contents and caching; the savings are Google's claims and we did not measure them.
  • Opened the Gemini API pricing page: gemini-3.6-flash Standard 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

Sources

Questions people ask

What is Tool retrieval in the Gemini API?

It is a preview feature of the Interactions API that lets Gemini search your tool library and load a function's parameter schema only when the model needs it, instead of sending every schema on every request. You turn it on by adding a tool_search tool and setting defer_loading to true on the tools you want to hold back.

Which models support Tool retrieval?

Google's changelog says it works with Gemini 3.6 and later models, including all Gemini 4 models, in the Interactions API. The Tool retrieval guide lists gemini-4-carbon, gemini-4-neon, gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash and gemini-3.6-flash.

Does Tool retrieval cost extra?

Google's guide says there is no separate charge. Tokens bill at the model's standard input, cached and output rates. Each server-side search triggers an extra internal model call that is reported in total_tool_use_tokens and billed at the input rate.

Can I use it with generateContent?

No. The guide says it is available only in the Interactions API on v1beta, and generateContent does not support it.

Can I unload a tool after the model loads it?

No. The guide lists as a limitation that loaded tools stay in context for the rest of the conversation and cannot be unloaded.

Gemini APIInteractions APITool retrievalFunction callingMCP