AI AGENTS · DEVELOPER TOOLS · GEMINI API
Google Gemini Tool Retrieval Explained: Build AI Agents with Hundreds of Tools
As AI agents connect to more services, sending every function definition with every request can become inefficient. Google’s new Tool Retrieval preview offers a different approach: keep tools discoverable, but load their detailed schemas only when they are needed.

AI agents become more useful when they can interact with business systems, databases, calendars, payment services, search tools and internal applications. But every connected function adds information the model may need before it can choose and call the right tool.
For an agent with dozens or hundreds of available functions, repeatedly including every detailed parameter schema in each request can increase prompt size and input-token usage. It can also make tool selection harder as the list of possible actions grows.
On 19 November 2026, Google announced Tool Retrieval for the Gemini API, available in preview in the Interactions API. The feature lets developers defer the full parameter schemas of selected tools and retrieve them when the agent needs them. Google’s official announcement describes the feature as a way to manage large tool libraries more efficiently.
What is Gemini Tool Retrieval?
Gemini Tool Retrieval is a feature in Google’s Gemini Interactions API that allows an agent to access a large collection of tools without loading every tool’s complete parameter schema into the initial model context.
A function schema describes what a tool does and the information it requires. For example, a function that creates a calendar event may need a title, start time, end time and attendee list. A function that issues a refund may require an order identifier and refund amount.
In a traditional function-calling setup, developers commonly send the full definitions of all available functions with a request. With Tool Retrieval, developers can mark less frequently used tools for deferred loading. The model can still see their names and descriptions, but the detailed parameter definitions are held back until the model requests a specific tool.
The feature is currently a preview, not a general-availability release. Google says it works with Gemini 3.6 and later models, including Gemini 4 models, through the Interactions API. Developers should check the current documentation for the supported model list and API requirements before implementation.
How does deferred tool loading work?
Google’s server-side approach uses a tool_search tool and the defer_loading setting on function definitions. When a tool is deferred, its name and description remain visible to the model, while its full parameter schema is retrieved only when the model asks for it.
The flow can be understood in four stages:
- Declare the tool library. The application provides the tools available to the agent. Frequently used tools can remain fully loaded, while less common tools are marked for deferred loading.
- The agent identifies a needed action. Based on the user’s request, the model decides which tool is relevant and asks to retrieve its definition.
- The API loads the schema. Gemini returns the detailed function schema so the model can prepare the correct function call.
- Your application executes the function. The application runs the requested operation and returns the result to the model, following the normal function-calling process.
Google says the search, schema retrieval and function-call steps are visible in the interaction steps, which can help developers inspect what the model considered while debugging an agent.
Server-side retrieval versus client-side retrieval
Google also describes a client-side option for developers who maintain their own tool registry, embedding index or permission filter. In that setup, the application handles the search and returns matching tool definitions to the model. This can be useful when tool discovery must follow application-specific rules, such as user permissions or tenant boundaries.
Tool Retrieval also supports deferred loading for remote MCP server tools in the Gemini API. That can help applications connect to larger MCP tool collections without placing every detailed tool definition in the initial context.
A practical example: an e-commerce support agent
Imagine an online store has an AI support agent connected to 80 functions. These might include checking an order, tracking a parcel, changing a delivery address, issuing a refund, creating a return, checking stock, applying a discount and escalating a case.
A customer writes: “My order arrived damaged. Can you refund the delivery charge?” The agent does not need the detailed schemas for every stock, marketing, reporting or account-management function. It needs to identify the refund-related action, retrieve the required parameters and follow the business rules for authorisation.
| Tool group | Possible loading strategy | Reason |
|---|---|---|
| Order lookup and tracking | Keep loaded if used frequently | Common actions in support conversations. |
| Refund and return functions | Defer if used less frequently | Retrieve the detailed schema when a refund or return is actually needed. |
| Inventory administration | Defer | Not relevant to most customer-support questions. |
| Analytics and reporting | Defer | Needed only for specific staff or reporting requests. |
| Account deletion or sensitive actions | Apply strict permission and approval controls | Retrieval does not itself authorise execution. |
This example illustrates the design pattern, not a ready-made production workflow. The application must still verify the customer, check refund eligibility, enforce spending limits and obtain any required human approval before executing a financial action.
Potential benefits for AI agent developers
1. Less schema information in the initial context
When a tool library is large, full parameter definitions can consume a meaningful share of the model’s input context. Deferring rarely used schemas can reduce the amount of tool-definition information sent up front. The actual saving depends on how many schemas are retrieved during a conversation and how large those schemas are.
2. More manageable tool libraries
Developers can expose a broad collection of capabilities without requiring every detailed definition to be loaded at the start. This may be useful for enterprise agents that interact with many departments or services.
3. A clearer tool-discovery process
Retrieval steps are represented in the interaction, making it easier to inspect which tools were searched for and which schemas were returned. This can help teams understand why an agent selected a particular function or failed to find one.
4. Support for remote MCP tools
For applications using Model Context Protocol servers, deferred loading can help manage a large set of remote tools. This is relevant to developers building agents that connect to multiple internal services or external integrations.
5. No separate Tool Retrieval fee
Google says Tool Retrieval has no separate charge. However, the normal input and output token rates still apply. Tool-search overhead and retrieved schemas are also part of the request’s token usage, so developers should measure total cost rather than assume every workload becomes cheaper.
Limitations and trade-offs developers should understand
Tool Retrieval is promising, but it is not automatically beneficial for every agent. Google’s announcement recommends measuring performance against real application traffic. Consider these practical limitations before enabling it.
- It is still in preview. Preview APIs can change. Avoid treating the current interface as a permanent production contract without reviewing Google’s current documentation and release notes.
- It is tied to the Interactions API. The announcement describes Tool Retrieval for that API. Do not assume the same feature is available through every Gemini API endpoint or integration.
- Retrieval has overhead. The search mechanism adds its own tokens and processing. If an agent has only a few small tools, sending the schemas directly may be simpler and more efficient.
- Retrieved schemas remain in context. Google notes that once a schema is retrieved, it stays available for the rest of the conversation; developers should account for this when designing long-running sessions.
- The tools list still needs to be supplied. Tool declarations are not a permanent server-side registry that removes the need to provide the tool configuration on later requests.
- Tool retrieval is not permission enforcement. Finding a function does not mean the user or agent is authorised to execute it. Your application must enforce identity, access control and business rules.
- It does not guarantee better decisions. Better context management may help, but the model can still select the wrong tool, misunderstand the request or produce invalid arguments.
When should developers use Gemini Tool Retrieval?
Tool Retrieval is most worth evaluating when an agent has a large tool library and uses only a small portion of it during a typical task. It may be less useful when the application has only a handful of functions or when most tools are needed on nearly every turn.
| Agent situation | Recommendation |
|---|---|
| Dozens or hundreds of available tools, only a few relevant per task | Good candidate for a controlled Tool Retrieval test. |
| Five small functions used in almost every request | Static tool definitions may be simpler. |
| Large internal MCP catalogue | Evaluate deferred loading and permission-aware discovery. |
| Long-running conversations with many different actions | Measure how retrieved schemas accumulate in context over time. |
| High-risk actions such as payments, account deletion or production changes | Use independent application-side authorisation and approval gates regardless of retrieval method. |
Implementation checklist for developers
Before enabling the feature in a real agent, use a small experiment and compare it with your existing function-calling implementation.
- Inventory your tools. Record each function’s name, description, schema size, usage frequency and risk level.
- Keep common tools available. Start by deferring only the long tail of functions that are rarely needed.
- Write precise descriptions. Tool names and descriptions help the model decide what to retrieve. Explain the action and when it should be used.
- Protect sensitive operations. Enforce access checks in the application, not in tool descriptions alone.
- Test retrieval quality. Build a representative set of user requests and check whether the right schema is retrieved.
- Measure token usage and latency. Compare the initial prompt, total request tokens, response time and cost across realistic conversations.
- Inspect interaction steps. Review tool-search calls and results to understand unexpected selections or missing tools.
- Test failure cases. Include ambiguous requests, unavailable tools, invalid arguments, denied permissions and long conversations.
- Review API changes. Since the feature is in preview, monitor the official Gemini API documentation and changelog before upgrading.
- Roll out gradually. Start with a low-risk workflow, retain a fallback and expand only when results justify it.
Frequently asked questions
What is Tool Retrieval in the Gemini API?
It is a preview feature that allows Gemini agents to load detailed function parameter schemas on demand instead of including every full tool schema in the initial request.
Does Tool Retrieval support hundreds of tools?
Google designed it to help developers manage large tool libraries, including collections with dozens or hundreds of functions. The practical benefit depends on how many tools an agent actually needs for each task.
Does Gemini Tool Retrieval cost extra?
Google says there is no separate Tool Retrieval fee. Normal model token charges still apply, including the tokens used for tool search and schemas that are retrieved.
Is Tool Retrieval available for every Gemini API model?
No. Google’s announcement says it works with Gemini 3.6 and later models, including Gemini 4 models, through the Interactions API. Check the current documentation for the exact supported models and API version.
Can Tool Retrieval work with MCP servers?
Yes. Google says deferred loading can also be used with remote MCP server tools connected through the Gemini API.
Does deferred loading make an AI agent more secure?
Not by itself. It changes when tool schemas are loaded, not whether a user is authorised to perform an action. Applications still need authentication, permission checks, input validation, audit logs and approval controls.
Should every AI agent use Tool Retrieval?
No. It is most relevant to agents with large tool libraries where only a subset of functions is needed per task. Small, frequently used tool sets may work better with ordinary function definitions.
Official source and further reading
Editorial note: Tool Retrieval was announced as a preview feature on 19 November 2026. Availability, supported models and API behaviour may change. Confirm current technical details in Google’s official documentation before using it in production.
Smarter tool access can help agents scale
As AI agents connect to more software and services, managing tool context becomes an important part of application design. Gemini Tool Retrieval gives developers another way to handle large function libraries—but careful measurement, clear tool descriptions and strong application-side permissions remain essential.
