# Gemini tool retrieval can make large agent toolboxes practical

Google's preview keeps most parameter schemas outside the initial prompt and loads them when needed. The approach can cut token use for large tool libraries, but searches add model work and retrieved tools remain in context.[1][2]

Google released Tool Retrieval in preview on November 19, 2026 for the Gemini Interactions API. Agents can see compact names and descriptions for deferred tools, search for a relevant tool, load its full schema and issue the function call in one server-side request.[1][2]

The change addresses a real scaling problem: dozens of parameter-heavy schemas consume context and can make tool selection less accurate. It does not guarantee lower cost. Server-side search adds another model pass over the context, and loaded schemas remain in the conversation.[2]

Google suggests static loading for fewer than roughly 20 stable tools; larger libraries should compare it with server-side retrieval.[2] Teams that need per-user permissions or changing registries should test client-side retrieval, where the application controls which schemas become visible.[2]

## What Google released

[Google announced Tool Retrieval on November 19](https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/) [1]. The preview works through the Gemini Interactions API and requires the v1beta API version; generateContent does not support it.[2]

For server-side retrieval, developers add one tool_search entry and mark long-tail functions or remote MCP servers with defer_loading: true. Gemini initially receives each deferred tool's name and a compact description, while the parameter schema stays outside the prompt.[1][2]

When a task needs a deferred function, the model emits a tool_search_call, the API returns a tool_search_result with the schema, and the model emits the ordinary function_call. The search and schema load happen inside the same API request, and the response steps remain visible for inspection.[1][2]

## Retrieval changes the tool-selection problem

A static tool list asks the model to choose among every full declaration on every request.[2] Tool Retrieval separates discovery from execution: the first decision uses short capability descriptions, while argument construction happens only after the chosen schema arrives.[2]

That separation can reduce repeated schema tokens and remove irrelevant parameters from the active context.[1][2] It also makes names and descriptions more consequential. Two vague or overlapping descriptions can send the search toward the wrong function before the model ever sees either schema.

Treat the deferred list as a searchable interface. Give each tool a distinct action, describe when it should be selected, and keep the most frequent or safety-critical tools loaded when removing a search step is more valuable than saving their schema tokens.

## Server-side and client-side retrieval solve different problems

Google recommends server-side retrieval for a large but fixed library. It requires no separate index, works with deferred remote MCP servers and completes search inside the original request. This is the simpler path when every user may access the same declared tools.[1][2]

Client-side retrieval adds an application round trip, but tools do not need to be declared upfront.[2] Your registry can return only tools available to the current tenant, account or workflow.[2] That makes it the stronger design when a permission filter, namespace boundary or newly connected integration controls what the model may discover.[2]

Retrieval is not authorization. A server-side search can narrow schemas, but the application still needs to authenticate the caller, authorize the requested action, validate arguments and require approval for consequential effects. A compact tool description must never become the permission check.

## The cost claim needs workload testing

[Google's documentation explains the billing path](https://ai.google.dev/gemini-api/docs/tool-retrieval) [2]. In early testing, the compact deferred list used about 26 tokens per deferred tool. Each server-side search then adds another model call over the full context plus the schemas it loads.

Large, sparse libraries are the favorable case.[2] Google's illustrative example compares 200 schemas of 400 tokens each across two requests: static loading totals 164,000 input tokens, while retrieval totals about 23,650 before output tokens and caching. Those are round-number examples, not measured savings for a production workload.[2]

Small libraries with long conversations can cost more.[2] In Google's second illustration, ten tools beside a 30,000-token context total 68,000 tokens with static loading and about 92,830 with retrieval because search repeats the large context.[2]

Measure total_input_tokens, total_tool_use_tokens, total_cached_tokens, output tokens, latency and accepted-task rate together. A lower initial prompt can still lose if most turns search, if several searches occur in one turn, or if retrieval chooses the wrong tool and triggers retries.[2]

## A safe rollout plan

- Inventory every tool by schema size, call frequency, tenant scope, side effects and approval requirement. Keep a known static baseline.[2]
- Start with the long tail. Leave common tools loaded and defer large, infrequent schemas whose names and descriptions have distinct intent.[1][2]
- Choose server-side retrieval only when the declared library is appropriate for every caller. Use client-side retrieval when identity, tenant, role or connected-account state changes tool visibility.[2]
- Build an eval set with direct requests, ambiguous requests, no-match requests, competing tools, multi-tool tasks and attempts to access unauthorized capabilities.[2]
- Score search choice, function choice, argument validity, completed-task success, refusal behavior, total billed tokens, latency and number of searches per turn.[2]
- Inspect tool_search_call and tool_search_result steps in traces. Alert on repeated searches, unexpected MCP tools, retrieval misses and function calls outside the user's allowed action set.[1][2]
- Roll out by traffic slice with a static-loading fallback. Do not remove application authorization, argument validation, idempotency or human approval gates.
- Re-run the evaluation when a tool name, description, schema, registry ranking rule, model or SDK version changes.[2]

## Limits teams should design around

- Tool Retrieval is preview software on v1beta. Its API surface can change before general availability.[2]
- The feature is available on the Interactions API only. Existing generateContent integrations need a migration rather than a flag change.[2]
- The complete tools array must be sent on every request, even when previous_interaction_id carries conversation history.[2]
- For stateless conversations, tool_search_call and tool_search_result steps must be replayed unchanged with their signatures. Older SDKs can drop unknown fields and cause a later 400 response.[2]
- There is no way to unload a tool after its schema enters the conversation. Later model calls continue to carry and bill for it.[2]
- A retrieval miss produces a text response rather than a structured no-match error, so applications need outcome checks instead of assuming a result step always appears.[2]
- Server-side and client-side retrieval cannot be combined in one request, and a turn may perform several searches.[2]
- Google's supported-model list currently names Gemini 4 Hydrogen, Gemini 4 Argon, Gemini 3.8 Flash and Gemini 3.6 Flash. Check the live list before selecting a model.[2][3]

## Frequently asked questions

- Does Tool Retrieval execute my local functions? No.[2] It finds and loads schemas. Your application still executes ordinary function calls and returns results.[1][2]
- Does it work with MCP? Server-side retrieval can defer a remote MCP server, causing its tools to load on demand. The application must still apply appropriate trust and permission controls.[1][2]
- Is Tool Retrieval free? Google bills deferred-list tokens, searches, loaded schemas and generated output at the selected model's token rates.[1][2]
- When should tools remain static? Keep static loading for a small stable library, or for frequently used tools where a retrieval pass adds more cost and latency than the schema consumes.[2]
- Which mode supports per-user tools? Client-side retrieval lets the application search its own registry and apply per-user filters before returning schemas.[1][2]
- What should teams test first? Begin with tool-selection accuracy, authorization boundaries, retrieval misses and total task cost on real conversation lengths.

## Sources

- [[1] Google: Introducing Tool Retrieval in the Gemini API](https://blog.google/innovation-and-ai/technology/developers-tools/gemini-api-tool-retrieval/)
- [[2] Google AI Studio: Tool retrieval documentation](https://ai.google.dev/gemini-api/docs/tool-retrieval)
- [[3] Google AI Studio: Gemini API release notes](https://ai.google.dev/gemini-api/docs/changelog)
