Skip to content
Back to blog
AI Tools

Gemini Interactions API Tool Search Preview: Save Tokens

Gemini Interactions API tool search entered preview on Nov 19, 2026. See the defer_loading setup, token math for 200 vs 10 tools, 400 errors, and Claude and OpenAI.

6 min readAI Tools
Gemini API tool searchGemini API tool retrievaldefer_loadingGemini Interactions APIAI agentsMCP
Gemini Interactions API Tool Search Preview: Save Tokens

Gemini Interactions API tool search preview: only apps with many tools save tokens

Tool retrieval in the Gemini API does not send every tool definition with each request. The model searches for tools and loads them when it needs them. In its Nov 19, 2026 changelog, Google said it was added to the Gemini Interactions API as a preview. An app with dozens of tools that uses only a few per request can cut input tokens a lot. An app with about 10 tools and long conversations may see tokens go up instead, so run the numbers before you turn it on.

On Nov 19, 2026, tool search, which loads tool definitions only when needed, arrived in preview in the Gemini Interactions API.

There is no extra charge. It follows the model's standard input and output pricing. In Google's documentation example, an app with 200 tools drops from about 164,000 to 23,650 input tokens, but an app with 10 tools and a long conversation rises from 68,000 to 92,830.

It does not work with generateContent. It is only for the v1beta Interactions API. According to the docs, the supported models are gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash and gemini-3.6-flash.

Illustration of paper tool cards and a magnifying glass for the Gemini Interactions API tool search preview

Static loading, server search or client search: which should you pick

Google's tool retrieval docs describe three ways to give tools to the model in the Gemini Interactions API. Until now, static loading was the default. It sends every tool definition with every request.

Three ways to deliver tools (based on Google's official docs)
ItemStatic loadingServer searchClient search
How tools reach the modelAll sent with every requestGemini loads deferred tools when neededYour app returns tools when needed
Search code you writeNoneNoneSearch, ranking and filter logic
Extra round trips per searchNoneNone (handled inside one API call)One
Best forA stable set of fewer than about 20 toolsA large but fixed tool listYour own tool registry, per-user tool sets

Figure 1 is the original comparison table from the docs. Server search is the default, so it is the simplest to set up. Client search fits setups where a user adds a new integration and tools get added mid-conversation. The docs say static loading suits a stable set of fewer than about 20 tools, so if you are below that size, you can keep your current approach. Source: Google Gemini API docs capture (Nov 20, 2026).

Comparison table of static loading, server search and client search in the Gemini Interactions API tool search docs

Gemini Interactions API tool search setup steps and how to verify

For server search, add one {"type": "tool_search"} entry to the tools array and add defer_loading: true to each function you want to defer. The docs explain that adding it to an mcp_server entry defers all tools from that server. The model sees only the name and description of deferred tools. When it needs one, it emits a search step and the API returns the full schema.

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})
tools = [
    {"type": "tool_search"},
    {"type": "function", "name": "convert_currency",
     "description": "Convert an amount between currencies.",
     "defer_loading": True,
     "parameters": {"type": "object",
       "properties": {"amount": {"type": "number"}, "to": {"type": "string"}},
       "required": ["amount", "to"]}},
]
interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Convert 100 USD to EUR.",
    tools=tools,
)
for step in interaction.steps:
    print(step.type, getattr(step, "name", ""))

The code above is a shortened version of Google's docs example. When it works, steps first shows a search step and a search result step, then a function_call. The search step is handled inside a single API call, so your code does not need to respond to it. You only run the function_call and return it as a function_result. The docs advise you not to rely on the status value and to check whether a function_call step exists.

Flow of Gemini Interactions API tool search passing only tool names, loading the needed schema and calling the function

Figure 2 shows the order in which a request runs. Google's docs advise you to measure with your own traffic before you turn it on broadly. Send a static loading request and a tool search request separately to the same model, then compare total_tool_use_tokens and input tokens in the responses to see if it pays off. This comparison method is Mcpy's suggestion, adapted from the docs example.

Why you must resend the tools array every request, and the 400 errors

Tool declarations are not saved between requests. According to the tool retrieval docs, even with previous_interaction_id you must resend the tool_search entry, the deferred tools and the non-deferred tools every time. If you skip them, the model may keep trying to call earlier tools. If you manage state yourself with store=false, you must send the search call and result steps back in order, including the signature. You can read the background on the changed storage default in our post on the Gemini API request storage default.

Common 400 errors in tool search (based on Google's official docs)
Error messageHow to fix it
tool_search tool must be specified when using defer_loading.Add the tool_search entry or remove defer_loading
Cannot specify both client-side and server-side tool_search tools.Declare only one type
deferred loading is not supported for this modelSwitch to a supported model
short_description can only be set if defer_loading is trueTurn on defer_loading or remove short_description
Server side tool call context must be circulated when using deferred loading functions.In a stateless flow, resend the missing search steps as they were
Tool call part is missing thought_signature.Restore the signature that was dropped from the search step

Which apps save tokens and which apps use more

In the billing section of the tool retrieval docs, Google says it applies the model's standard input, cache and output rates with no separate charge. However, each deferred tool adds one line with its name and short description to the input, about 26 tokens per tool in early testing. Each time a server search happens, one more model call runs inside the same request. It includes the full conversation plus the loaded schemas, and that whole prompt is counted as total_tool_use_tokens. Loaded schemas stay until the conversation ends and count as input in later calls. There is no way to unload a tool once it is loaded.

Input token comparison in Google's docs example (tokens, 2-turn request)
ScenarioStatic loadingTool search
200 tools, 400 tokens per tool164,00023,650
10 tools, 30,000-token conversation68,00092,830

Here is the math behind Figure 3. In the 200-tool example, the first request is 7,350: a 2,000-token conversation, a 5,200-token deferred list (200 x 26) and 150 tokens of instructions. The search call adds 8,150, and the second request is 8,150, for about 23,650. In the 10-tool example, the conversation is 30,000 tokens, so the search call sends that conversation once more. That makes about 92,830, more than the 68,000 of static loading. Both examples are illustrative calculations built from numbers Google rounded, not measurements, and they leave out output tokens and caching. Source: Google Gemini API docs capture (Nov 20, 2026).

Google docs calculation table comparing input tokens for Gemini Interactions API tool search and static loading

Summing up Google's explanation of when it saves, it pays off for apps where tool definitions take a big share and most requests search zero or one time. It is the opposite for apps with few tools or long conversations where almost every request searches. Deferring tools can also make the prompt smaller than the model's minimum cache size.

Tool search input token breakdown in the 200-tool example (tokens, Google docs calculation)
ComponentTokens
Conversation in the first request2,000
Deferred tool list (200 tools)5,200
Tool search instructions150
Search call (conversation + list + loaded schemas)8,150
Second request8,150

Reading it vertically, the deferred list and the search call make up most of the input. The 2 loaded schemas (800 tokens) are a small share, and as you add tools the list grows by only about 26 tokens per tool.

Limits to know before you use it and design tips

According to the limits list in the tool retrieval docs, tool search works only in the v1beta Interactions API and is not supported in generateContent. You cannot mix server search and client search in one request, and defer_loading is for server search only. If no search result matches, the answer comes back as text instead of a structured error, so do not judge a failed search from the search result step alone. The docs also say the API shape may change before general release.

Model support is worded a little differently in the supported models section of the docs and in the changelog. The changelog says Gemini 3.6 and later models, including all of Gemini 4. The tool retrieval docs list four models: gemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash and gemini-3.6-flash. Using defer_loading on an unsupported model returns a 400 error, so check that your model is on the list first. Hydrogen pricing and the free tier are in our Gemini 4 Hydrogen general availability post, and the 3.8 Flash replacement schedule is in our summary of Gemini API model changes.

The design advice in the docs is to defer only the long tail and not the tools you use often. Do not defer tools you call directly by name, and include the full parameter schema even for deferred functions. If you send only a name and short description, search returns an empty schema and the model cannot call it. Prefix similar function names with the service name, and write in the system instruction when to search.

Claude and GPT have this feature too

Anthropic offers a same-named tool search tool as stable. It supports two search methods, regex and BM25, and up to 10,000 deferred tools per request. OpenAI also has tool_search and defer_loading, and its docs say the Responses API supports only gpt-5.4 and later models. The same idea exists at all three companies, but the implementations differ.

Tool search compared across three companies (based on each company's official docs, Nov 20, 2026)
ItemGemini APIClaude APIOpenAI API
Search tool nametool_searchtool_search_tool_regex_20251119, tool_search_tool_bm25_20251119tool_search
Usable APIInteractions API only (v1beta, preview)Messages API and others (stable)Responses API
Supported modelsgemini-4-hydrogen, gemini-4-argon, gemini-3.8-flash, gemini-3.6-flashCurrent models from Claude Opus 4.5 onward (Opus 4.1 and earlier excluded)gpt-5.4 and later models
How to deferdefer_loading on functions and mcp_server entriesdefer_loading in tool definitions, mcp_toolset setting for MCPdefer_loading on functions and MCP server tools, namespaces supported
Separate chargeNone, standard model pricingNo separate server tool charge, loaded definitions count as input tokensNo pricing mentioned in the docs

The criteria for deciding whether you need tool search are similar. The Claude docs recommend it when you have 10 or more tools or definitions exceed 10,000 tokens, which differs from the Gemini docs' threshold of about 20 tools. But each doc's threshold comes from different models and calculations, so do not compare the numbers directly. It is better to measure your own app's definition token count and decide from that.

Frequently asked questions

Does tool search cost extra?

Google's docs say there is no separate charge and the model's input, cache and output rates apply as is. However, each search triggers one more model call, so input tokens can go up.

Can I defer MCP server tools too?

If you add defer_loading to a remote mcp_server entry, all tools the server exposes are deferred. The docs say this is useful when several servers have many tools.

Can I use it in an app built with generateContent?

No. Tool search is only for the Interactions API, so to use it in an existing app you must first move to the Interactions API.

Found this useful? Share it

Latest posts

Related projects

Get new posts by email

Insights on marketing, analytics, and dev, delivered to your inbox.