← AUTOMATER NEWSROOM

Google Puts Tool Retrieval in the Gemini API: Defer Tool Schemas and Let the Server Load Them on Demand

Tool Retrieval is in preview in the Gemini Interactions API: add a tool_search tool, set defer_loading on the long tail, and the server loads parameter schemas on demand. What that changes for tokens, prefix caching, MCP catalogs and debugging — and where the saving does not show up.

A two-panel comparison: the top panel shows a request carrying full parameter schemas for every tool on every turn, while the bottom panel shows Tool Retrieval keeping only names and descriptions in the prompt, running a tool_search step, loading one schema on demand and emitting a function call in the same request.A two-panel comparison: the top panel shows a request carrying full parameter schemas for every tool on every turn, while the bottom panel shows Tool Retrieval keeping only names and descriptions in the prompt, running a tool_search step, loading one schema on demand and emitting a function call in the same request.
How Gemini API Tool Retrieval changes what a request carries. The deferred flow — tool_search_call, tool_search_result, then function_call inside one interaction — follows the sequence and step names in Google's Nov. 19, 2026 announcement. Diagram by Automater Newsroom.

Google put Tool Retrieval into preview in the Gemini Interactions API on Nov. 19, 2026. Turning it on takes two edits to a request: add a tool_search tool, and set defer_loading: true on the tools you want held back. The model still knows every tool exists. It just stops carrying every parameter schema.

For anyone running an agent against a large tool catalog, that is the difference between a context window full of JSON you mostly ignore and one that holds names and descriptions until a task actually needs more.

Google's announcement page for Tool Retrieval in the Gemini API, showing the headline, the Nov 19 2026 publication date and the opening summary about loading tool parameter schemas on demand.
Google's blog, Nov. 19, 2026: the Tool Retrieval announcement. The captured page shows the headline, the publication date and the lede explaining that tool parameter schemas load on demand instead of the full tool library being sent in every prompt, which Google says reduces input tokens and keeps tool selection accurate as an agent scales. · Original source

The problem Google is naming

Google’s announcement is blunt about the failure mode. When an agent connects to dozens or hundreds of tools, sending every full parameter schema on every request “adds up fast”: it inflates input token counts, adds latency, and lowers tool-selection accuracy as the candidate list grows.

Tool Retrieval splits what the model sees. A deferred tool keeps its name and description in context; its parameter schema stays out. When the model needs that tool it asks for it by name, the API loads the full schema, and the model emits the function call — all inside the same request.

Two details carry most of the practical weight:

  • No index to build or host. Gemini runs the search on its own servers. The only changes to your code are the new tool and a flag on the tools you defer.
  • No extra round trip in the default mode. Search, schema load and function call all happen inside one interaction.

That is a different division of labor from the coding-agent side of the market. Claude Code’s overview docs and Qwen Code’s both present MCP as the way the harness reaches external systems — Google Drive, Jira, Slack, your own tooling — which means the harness is what enumerates and declares those tools. Tool Retrieval moves the narrowing to the provider, inside the request.

Two cards comparing server-side tool_search, which runs on Gemini with no index to host and no extra round trip, against client-side execution, where your app runs the lookup, adds one round trip per search, and can expose tools that were never declared up front.Two cards comparing server-side tool_search, which runs on Gemini with no index to host and no extra round trip, against client-side execution, where your app runs the lookup, adds one round trip per search, and can expose tools that were never declared up front.
Choosing between Gemini-run and app-run tool search. Server-side mode defers a whole MCP server with one flag and keeps the cached prefix stable; client-side mode keeps your own registry, embedding index or permission filter in the loop at the cost of a round trip per search. Details from Google's Tool Retrieval announcement. Diagram by Automater Newsroom.

Turning it on

The announcement’s sample defers a long tail of functions while leaving the frequent ones loaded up front:

tools = [
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "issue_refund",
        "description": "Refund an order to the original payment method.",
        "defer_loading": True,
        "parameters": {"type": "object", "properties": {...}},
    },
    # ... 50+ other deferred functions (leave frequent tools undeferred)
]

interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    input="Order A-1042 arrived damaged. Please refund 40 dollars.",
    tools=tools,
)

Inside that single call the model searches for issue_refund, the API loads its schema, and the model emits the call. All three moves land in interaction.steps:

[
  {"type": "tool_search_call", "id": "tsc_7f2a",
   "arguments": {"function_names": ["issue_refund"]}},
  {"type": "tool_search_result", "call_id": "tsc_7f2a",
   "result": [{"type": "function", "name": "issue_refund", "parameters": {...}}]},
  {"type": "function_call", "id": "fc_91c3", "name": "issue_refund",
   "arguments": {"order_id": "A-1042", "amount": 40}}
]

Read that array as a debugging surface, not just plumbing. Google frames it explicitly as a way to inspect which tools the model considered when you are fixing a tool name or description. In a harness-side setup you infer that from behavior; here it is in the response.

Five things to do with it

  1. Defer the long tail, keep the hot path loaded. Google’s own sample comment says to leave frequent tools undeferred. Deferring a tool the model needs every turn buys nothing and adds a search step.
  2. Point one flag at a whole MCP server. Setting defer_loading: true on an mcp_server tool defers every tool that server exposes, so a large remote server no longer has to be listed tool by tool.
  3. Re-check your prefix cache breakpoints. Deferred schemas stay out of the start of the prompt and loaded ones arrive later in the conversation, which Google says keeps the cached prefix identical from turn to turn. If you positioned cache breakpoints around a big tool block, that block is no longer there.
  4. Use client-side execution when you own the lookup. Declaring tool_search with "execution": "client" and your own search parameters keeps a registry, an embedding index or a per-user permission filter in your code. It costs one round trip per search — and because tools no longer need to be declared up front, you can expose a new tool mid-conversation when a user connects an integration.
  5. Log the steps from day one. tool_search_call says what the model asked for; tool_search_result says what came back. Those two entries are the shortest route to a description rewrite.

What it costs

There is no separate charge: input and output tokens bill at the standard rate for the model you call. Two things change the arithmetic.

Turning on tool_search adds a small, fixed block of input tokens, and Google does not publish its size. And every schema the model loads is billed as input for the rest of the conversation, exactly like a tool declared up front.

That second point is the one to plan around. A loaded schema is not a one-off charge; it recurs every turn from the moment it loads. Deferring is a bet that a tool will not be needed, and losing the bet costs what declaring it would have cost — plus the search block.

A four-turn diagram comparing input token shape: declaring every tool up front re-sends all schemas each turn, while deferred tools send only names until turn two loads issue_refund, whose schema then remains in context and is billed as input on turns three and four.A four-turn diagram comparing input token shape: declaring every tool up front re-sends all schemas each turn, while deferred tools send only names until turn two loads issue_refund, whose schema then remains in context and is billed as input on turns three and four.
The billing shape Google describes for Tool Retrieval. Names-only turns replace full schemas, but each schema the model loads is billed as input for the rest of the conversation, so a load is a recurring cost rather than a one-off. Widths are illustrative, not measured; Google publishes no size for the fixed tool_search block. Diagram by Automater Newsroom.

Google’s own conclusion is conditional: you save tokens when the schemas you never load outweigh the ones you do, which it calls “the usual case for large libraries,” followed immediately by “measure it against your own traffic.” Take that as the instruction it is.

Constraints before you plan around it

Item Status in the announcement
Availability Preview, in the Interactions API
Models Gemini 3.6 and later, including all Gemini 4 models
Pricing No separate charge, standard token rates
Accuracy claim Asserted, no benchmark published in the post
tool_search block size Not published

The samples call client.interactions.create with model="gemini-4-hydrogen", and the post links out to a full setup guide in Google’s AI Studio docs rather than carrying reference detail itself.

Why it matters past Google’s API

Tool sprawl is the tax every operator of a large MCP catalog already pays, and the usual answers are all yours to build: hand-curate a subset, split work across subagents with narrower rosters, or put a gateway in front of the catalog. Harness engineering treats a bloated tool list as a design failure for exactly this reason — every exposed tool costs window space and decision noise, not only tokens. Server-side retrieval is the provider taking that problem off your side of the boundary.

If you build on the Gemini API, the change is small enough to test this week: mark the long tail deferred, read the steps on a real task, and compare a week of bills before you believe the saving. If you build on MCP elsewhere, the sharper question is who narrows the tool list next — your harness, your gateway, or the model provider.

Sources: Google, Introducing Tool Retrieval in the Gemini API · Claude Code overview docs · Qwen Code overview docs. Related reading: prompt caching and context engineering.

Sources

  1. Gemini API tool retrieval for efficient agent scaling
  2. Overview - Claude Code Docs
  3. Qwen Code overview | Qwen Code Docs