> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# Tool retrieval

{% callout type="note" %}
   Tool retrieval is in [preview](/docs/models#preview)
  and requires the `v1beta` [API version](/api-reference/api-versions). The API
  surface may change before general availability. 

{% /callout %}

Tool retrieval lets Gemini search for and load tool schemas during a
conversation, instead of receiving every tool definition upfront. You declare
your full tool library once and mark the tools you want to withhold from the
initial context. The model then pulls in the handful of schemas it actually
needs for the task at hand.

This matters when your tool library is large. A few dozen function declarations
can consume tens of thousands of tokens on every request, and model accuracy
drops as the number of candidate tools grows. Tool retrieval keeps the active
tool set small.

Tool retrieval is available on the
[Interactions API](/docs/interactions-overview). The
[`generateContent`](/docs/function-calling?generate-content=true) method does not
support it.

## Choosing a retrieval mode  {% id="choosing-a-mode" %}

The Gemini API supports two retrieval modes: **server-side retrieval** (the
default), where Gemini searches your declared tools and loads the matching
schemas itself, and **client-side retrieval**, where your application owns the
search and returns the matching schemas to the model. The following table
compares both modes with static tool loading, where every schema is sent on
every request:

{% table %}
  * Capability
  * Static tool loading
  * Server-side retrieval
  * Client-side retrieval

  ---

  * **How tools reach the model**
  * All schemas sent on every request
  * Gemini loads deferred schemas on demand
  * Your app returns schemas on demand

  ---

  * **Retrieval code you write**
  * None
  * None
  * Search, ranking, and filtering logic

  ---

  * **Tools must be declared upfront**
  * Yes
  * Yes
  * No

  ---

  * **Works with MCP servers**
  * Yes
  * Yes
  * Not applicable

  ---

  * **Extra round trips per search**
  * None
  * None
  * One per search: your app runs the search and sends a new request

  ---

  * **Best for**
  * Fewer than ~20 stable tools
  * Large but fixed tool libraries
  * Proprietary registries, namespaces, per-user tool sets
{% /table %}

If your application is latency-sensitive, use server-side retrieval. Each
client-side search adds a round trip between the model and your application,
while server-side searches run inside a single API call.

## Server-side tool retrieval  {% id="server-side" %}

To enable server-side retrieval, add `{"type": "tool_search"}` to your tools
array. Then set `defer_loading: true` on each `function` tool you want to
withhold, or on an `mcp_server` tool to defer every tool that server exposes.
The model sees the name and description of every deferred tool, but not its
parameter schema. When it needs one, it loads the full schema and continues.

{% tabs %}
  

  {% tab label="Python" %}
  ```python
  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 from one currency to another.",
          "defer_loading": True,
          "parameters": {
              "type": "object",
              "properties": {
                  "amount": {"type": "number"},
                  "to": {"type": "string"},
              },
              "required": ["amount", "to"],
          },
      },
      {
          "type": "mcp_server",
          "name": "weather_service",
          "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
          "defer_loading": True,
      },
  ]
  
  interaction = client.interactions.create(
      model="gemini-4-hydrogen",
      input="Check the temperature in London and convert 100 USD to EUR.",
      tools=tools,
  )
  
  for step in interaction.steps:
      print(step.type, getattr(step, "name", ""))
  ```

  {% /tab %}

  

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
  
  const tools = [
    { type: "tool_search" },
    {
      type: "function",
      name: "convert_currency",
      description: "Convert an amount from one currency to another.",
      defer_loading: true,
      parameters: {
        type: "object",
        properties: {
          amount: { type: "number" },
          to: { type: "string" },
        },
        required: ["amount", "to"],
      },
    },
    {
      type: "mcp_server",
      name: "weather_service",
      url: "https://gemini-api-demos.uc.r.appspot.com/mcp",
      defer_loading: true,
    },
  ];
  
  const interaction = await ai.interactions.create({
    model: "gemini-4-hydrogen",
    input: "Check the temperature in London and convert 100 USD to EUR.",
    tools: tools,
  });
  
  for (const step of interaction.steps) {
    console.log(step.type, step.name ?? "");
  }
  ```

  {% /tab %}

  

  {% tab label="REST" %}
  ```bash
  curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-4-hydrogen",
      "input": "Check the temperature in London and convert 100 USD to EUR.",
      "tools": [
        {"type": "tool_search"},
        {
          "type": "function",
          "name": "convert_currency",
          "description": "Convert an amount from one currency to another.",
          "defer_loading": true,
          "parameters": {
            "type": "object",
            "properties": {
              "amount": {"type": "number"},
              "to": {"type": "string"}
            },
            "required": ["amount", "to"]
          }
        },
        {
          "type": "mcp_server",
          "name": "weather_service",
          "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
          "defer_loading": true
        }
      ]
    }'
  ```

  {% /tab %}

  

{% /tabs %}

### How server-side retrieval works  {% id="how-server-side-works" %}

1.  You declare your tools, marking the deferred ones with `defer_loading:
    true`, and include `{"type": "tool_search"}`.
2.  The model receives the name and description of each deferred tool, but not
    its parameter schema.
3.  When the model needs a tool, it emits a `tool_search_call` step.
4.  The API resolves the schema and returns it as a `tool_search_result` step.
5.  The model emits the actual `function_call` with arguments.
6.  You execute the function and return a `function_result` as usual.

Steps 3 and 4 happen inside a single API call. You see both steps in the
response, but you don't act on them.

### Server-side response format  {% id="server-side-response" %}

```json
{
  "id": "int_server_111",
  "status": "requires_action",
  "steps": [
    {
      "type": "tool_search_call",
      "id": "tsc_abc123",
      "arguments": {
        "function_names": ["weather_service:get_weather", "convert_currency"]
      },
      "signature": "CpkBAY89a1..."
    },
    {
      "type": "tool_search_result",
      "call_id": "tsc_abc123",
      "signature": "CrQCAY89a1...",
      "result": [
        {
          "type": "function",
          "name": "weather_service:get_weather",
          "parameters": {
            "type": "object",
            "properties": {"location": {"type": "string"}},
            "required": ["location"]
          }
        },
        {
          "type": "function",
          "name": "convert_currency",
          "parameters": {
            "type": "object",
            "properties": {
              "amount": {"type": "number"},
              "to": {"type": "string"}
            },
            "required": ["amount", "to"]
          }
        }
      ]
    },
    {
      "type": "mcp_server_tool_call",
      "id": "mcp_call_111",
      "name": "get_weather",
      "server_name": "weather_service",
      "arguments": {"location": "London"}
    },
    {
      "type": "mcp_server_tool_result",
      "call_id": "mcp_call_111",
      "name": "get_weather",
      "server_name": "weather_service",
      "result": {"temp_celsius": 15}
    },
    {
      "type": "function_call",
      "id": "fc_xyz789",
      "name": "convert_currency",
      "arguments": {"amount": 100, "to": "EUR"}
    }
  ]
}
```

The API runs `get_weather` on the remote MCP server and returns the
`mcp_server_tool_call` and `mcp_server_tool_result` steps in the same response.
`convert_currency` is your own function, so the response ends with a
`function_call` step for you to execute. Look for `function_call` steps in
`steps` rather than relying on the interaction's `status`, which isn't always
`requires_action` when a `function_call` is returned.

The `signature` on `tool_search_call` and `tool_search_result` steps is an
opaque, encrypted value that carries the retrieval context. You don't need to
read it. If you manage conversation state yourself, you must send these steps
back unchanged, signature included. See
[Stateless conversations](/docs/tool-retrieval#stateless).

## Client-side tool retrieval  {% id="client-side" %}

Client-side retrieval hands the search back to your application. You declare a
`tool_search` tool with `execution: "client"`, a `name`, a `description`, and
your own parameter schema. The `description` is required, because the model
reads it to decide when to search. The model calls the tool like a normal
function, and you return the matching tool definitions in the
`function_result`.

Because the schemas travel in the result, the tools do not need to exist in your
original `tools` array. This lets you inject tools that become available partway
through a conversation, such as when a user connects a new integration.

{% tabs %}
  

  {% tab label="Python" %}
  ```python
  from google import genai
  
  client = genai.Client(http_options={"api_version": "v1beta"})
  
  tools = [
      {
          "type": "tool_search",
          "execution": "client",
          "name": "search_tool_registry",
          "description": "Search the internal tool registry for functions.",
          "parameters": {
              "type": "object",
              "properties": {
                  "query": {
                      "type": "string",
                      "description": "The tool name or capability to look for.",
                  },
                  "namespace": {
                      "type": "string",
                      "description": "Namespace filter, for example 'billing'.",
                  },
                  "limit": {
                      "type": "integer",
                      "description": "Maximum number of tools to return.",
                  },
              },
              "required": ["query"],
          },
      }
  ]
  
  # Turn 1: the model asks your application to search.
  interaction = client.interactions.create(
      model="gemini-4-hydrogen",
      input="Look up the billing history for user 123.",
      tools=tools,
  )
  
  for step in interaction.steps:
      if step.type == "function_call" and step.name == "search_tool_registry":
          # Run your own retrieval here: vector search, registry lookup, and
          # so on. Return complete function declarations.
          matches = [
              {
                  "type": "function",
                  "name": "get_billing_history",
                  "description": "Retrieve billing history for a given user.",
                  "parameters": {
                      "type": "object",
                      "properties": {"user_id": {"type": "integer"}},
                      "required": ["user_id"],
                  },
              }
          ]
  
          # Turn 2: return the schemas. The tools array is unchanged.
          followup = client.interactions.create(
              model="gemini-4-hydrogen",
              previous_interaction_id=interaction.id,
              tools=tools,
              input=[
                  {
                      "type": "function_result",
                      "name": step.name,
                      "call_id": step.id,
                      "result": matches,
                  }
              ],
          )
  
          # Turn 3: the model calls the tool it just discovered.
          for followup_step in followup.steps:
              if followup_step.type == "function_call":
                  print(followup_step.name, followup_step.arguments)
  ```

  {% /tab %}

  

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
  
  const tools = [
    {
      type: "tool_search",
      execution: "client",
      name: "search_tool_registry",
      description: "Search the internal tool registry for functions.",
      parameters: {
        type: "object",
        properties: {
          query: {
            type: "string",
            description: "The tool name or capability to look for.",
          },
          namespace: {
            type: "string",
            description: "Namespace filter, for example 'billing'.",
          },
          limit: {
            type: "integer",
            description: "Maximum number of tools to return.",
          },
        },
        required: ["query"],
      },
    },
  ];
  
  // Turn 1: the model asks your application to search.
  const interaction = await ai.interactions.create({
    model: "gemini-4-hydrogen",
    input: "Look up the billing history for user 123.",
    tools: tools,
  });
  
  for (const step of interaction.steps) {
    if (step.type === "function_call" && step.name === "search_tool_registry") {
      // Run your own retrieval here.
      const matches = [
        {
          type: "function",
          name: "get_billing_history",
          description: "Retrieve billing history for a given user.",
          parameters: {
            type: "object",
            properties: { user_id: { type: "integer" } },
            required: ["user_id"],
          },
        },
      ];
  
      // Turn 2: return the schemas. The tools array is unchanged.
      const followup = await ai.interactions.create({
        model: "gemini-4-hydrogen",
        previous_interaction_id: interaction.id,
        tools: tools,
        input: [
          {
            type: "function_result",
            name: step.name,
            call_id: step.id,
            result: matches,
          },
        ],
      });
  
      // Turn 3: the model calls the tool it just discovered.
      for (const followupStep of followup.steps) {
        if (followupStep.type === "function_call") {
          console.log(followupStep.name, followupStep.arguments);
        }
      }
    }
  }
  ```

  {% /tab %}

  

  {% tab label="REST" %}
  ```bash
  # Turn 1: declare a client-side tool search.
  curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-4-hydrogen",
      "input": "Look up the billing history for user 123.",
      "tools": [
        {
          "type": "tool_search",
          "execution": "client",
          "name": "search_tool_registry",
          "description": "Search the internal tool registry for functions.",
          "parameters": {
            "type": "object",
            "properties": {
              "query": {"type": "string"},
              "namespace": {"type": "string"},
              "limit": {"type": "integer"}
            },
            "required": ["query"]
          }
        }
      ]
    }'
  
  # The response contains a function_call step for "search_tool_registry".
  
  # Turn 2: return the matching schemas in the function result.
  curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
    -H "x-goog-api-key: $GEMINI_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
      "model": "gemini-4-hydrogen",
      "previous_interaction_id": "INTERACTION_ID",
      "tools": [
        {
          "type": "tool_search",
          "execution": "client",
          "name": "search_tool_registry",
          "description": "Search the internal tool registry for functions.",
          "parameters": {
            "type": "object",
            "properties": {
              "query": {"type": "string"},
              "namespace": {"type": "string"},
              "limit": {"type": "integer"}
            },
            "required": ["query"]
          }
        }
      ],
      "input": [
        {
          "type": "function_result",
          "name": "search_tool_registry",
          "call_id": "CALL_ID",
          "result": [
            {
              "type": "function",
              "name": "get_billing_history",
              "description": "Retrieve billing history for a given user.",
              "parameters": {
                "type": "object",
                "properties": {"user_id": {"type": "integer"}},
                "required": ["user_id"]
              }
            }
          ]
        }
      ]
    }'
  ```

  {% /tab %}

  

{% /tabs %}

### How client-side retrieval works  {% id="how-client-side-works" %}

1.  You declare a `tool_search` tool with `execution: "client"`, a `name`, a
    `description`, and a `parameters` schema.
2.  The model emits a standard `function_call` step for that tool.
3.  Your application runs its own retrieval logic.
4.  You return the matching tool definitions in `function_result.result`.
5.  The model emits `function_call` steps for the tools it just received.
6.  You execute those functions and return their results as usual.

## Configuration reference  {% id="configuration" %}

### `tool_search` {% id="tool-search" %}

Declares the retrieval mechanism. Exactly one `tool_search` tool is allowed per
request.

Server-side:

```json
{"type": "tool_search"}
```

Client-side:

```json
{
  "type": "tool_search",
  "execution": "client",
  "name": "search_tool_registry",
  "description": "Search the internal tool registry for functions.",
  "parameters": { ... }
}
```

{% table %}
  * Field
  * Required
  * Description

  ---

  * `type`
  * Yes
  * Must be `"tool_search"`.

  ---

  * `execution`
  * No
  * `"server"` (default) or `"client"`.

  ---

  * `name`
  * For client-side
  * The function name the model calls. Omitting it on a client-side
    `tool_search` returns a `400` error. Don't set it on a server-side
    `tool_search`.

  ---

  * `description`
  * For client-side
  * Tells the model when to search. Omitting it on a client-side
    `tool_search` returns a `400` error. Don't set it on a server-side
    `tool_search`.

  ---

  * `parameters`
  * For client-side
  * JSON Schema for the search arguments. Don't set it on a server-side
    `tool_search`.
{% /table %}

### `defer_loading` {% id="defer-loading" %}

Set `defer_loading: true` on a `function` or `mcp_server` tool to keep its full
schema out of the initial context. The tool's name and description stay visible
so the model knows the capability exists.

`defer_loading` applies to server-side retrieval. Setting it on any tool without
also including a server-side `{"type": "tool_search"}` returns a `400` error, so
don't combine it with `execution: "client"`.

### `short_description` {% id="short-description" %}

An optional field on function declarations that also set `defer_loading: true`.
When set, the model uses it instead of the full `description` as the compact
summary during retrieval. Use it to keep long, parameter-heavy descriptions out
of the initial context:

```json
{
  "type": "function",
  "name": "convert_currency",
  "description": "Convert an amount between currencies using live mid-market rates, with optional rounding and historical date lookup.",
  "short_description": "Convert an amount between currencies.",
  "defer_loading": true,
  "parameters": { ... }
}
```

Setting `short_description` on a function without `defer_loading: true` returns
a `400` error.

## MCP servers  {% id="mcp" %}

Remote MCP servers support `defer_loading`. When set, every tool the server
exposes is deferred and loaded on demand:

```json
{
  "type": "mcp_server",
  "name": "weather_service",
  "url": "https://gemini-api-demos.uc.r.appspot.com/mcp",
  "defer_loading": true
}
```

This is useful when you connect several MCP servers at once, since a single
server can expose dozens of tools. See [Remote MCP](/docs/function-calling#mcp)
for connection details.

## Multi-turn conversations  {% id="multi-turn" %}

When you chain turns with `previous_interaction_id`, the API stores the step
history for you, including the `tool_search_call` and `tool_search_result`
steps. You don't need to send those steps again. You do need to send your tools
again, as described in the next section.

### Send the full `tools` array on every request  {% id="resend-tools" %}

The API doesn't carry tool declarations over from one request to the next, even
when you pass `previous_interaction_id`. Send the same complete `tools` array on
every request in a conversation:

*   The `tool_search` entry.
*   Every deferred tool, including deferred `mcp_server` tools.
*   Every tool that isn't deferred.

This applies to chained requests that use `previous_interaction_id`, to the
request that returns a `function_result`, and to
[stateless conversations](/docs/tool-retrieval#stateless) that replay the full history.

If a later request leaves tools out, the model only knows about the tools it
already called in earlier turns. It tends to keep using those tools, and it can
try to call functions that the request no longer declares. With server-side
retrieval, internal retrieval calls with names that start with `retriever:` can
also show up in the response steps.

The following example sends a function result back in turn 2 and resends the
same `tools` list from turn 1:

{% tabs %}
  

  {% tab label="Python" %}
  ```python
  # Turn 1 used tools=tools and returned a function_call step.
  fc_step = next(s for s in interaction.steps if s.type == "function_call")
  
  followup = client.interactions.create(
      model="gemini-4-hydrogen",
      previous_interaction_id=interaction.id,
      tools=tools,
      input=[
          {
              "type": "function_result",
              "name": fc_step.name,
              "call_id": fc_step.id,
              "result": [{"type": "text", "text": '{"amount": 92.4, "currency": "EUR"}'}],
          }
      ],
  )
  
  print(followup.output_text)
  ```

  {% /tab %}

  

  {% tab label="JavaScript" %}
  ```javascript
  // Turn 1 used tools: tools and returned a function_call step.
  const fcStep = interaction.steps.find((s) => s.type === "function_call");
  
  const followup = await ai.interactions.create({
    model: "gemini-4-hydrogen",
    previous_interaction_id: interaction.id,
    tools: tools,
    input: [
      {
        type: "function_result",
        name: fcStep.name,
        call_id: fcStep.id,
        result: [{ type: "text", text: '{"amount": 92.4, "currency": "EUR"}' }],
      },
    ],
  });
  
  console.log(followup.output_text);
  ```

  {% /tab %}

  

{% /tabs %}

### Stateless conversations  {% id="stateless" %}

If you manage conversation state yourself (`store=false`) and pass the full step
history in `input` on every request (see
[Stateless function calling](/docs/function-calling#stateless-function-calling)),
you must send every `tool_search_call` and `tool_search_result` step back
exactly as you received it, along with the full `tools` array. This applies to
server-side retrieval, that is, any request that uses `defer_loading`.
Client-side retrieval uses ordinary `function_call` and `function_result` steps,
which follow the standard stateless rules.

Circulating the steps verbatim means:

*   Send both steps. The API rejects a request when a `tool_search_call` step is
    missing, but it doesn't check for the matching `tool_search_result` step.
    That step holds the loaded schemas, so without it the model loses access to
    tools it already loaded.
*   Keep the `signature` field. It carries the retrieval context the API needs
    to reconstruct the conversation.
*   Don't edit, rebuild, or reformat the steps. Append the response steps to
    your history as you received them.
*   Keep the steps in their original position, before the `function_call` step
    that uses the retrieved tool.
*   Send back the other steps from the response too, including `thought` steps
    and their signatures, as for any
    [stateless function call](/docs/function-calling#stateless-function-calling).
    If you build your history with an SDK, use a version that recognizes the
    `tool_search_call` and `tool_search_result` step types. Older versions
    parse them as unknown steps and drop their fields, which causes the errors
    below.

If these steps are missing, the API rejects the request with a `400` error:

```none
Server side tool call context must be circulated when using deferred loading
functions. Please return the tool_call and tool_response parts in previous turns
back to the server. Missing circulated context for functions: convert_currency
```

The error appears on the request that sends the `function_result` for a
deferred tool, not on the request where retrieval happened. The first call
succeeds, and the second call fails. The end of the message lists the functions
whose retrieval context is missing.

If the steps are present but their `signature` field was removed, the API
returns a different `400` error:

```none
Tool call part is missing thought_signature.
```

For a `tool_search_result` step, the message starts with `Tool response part`
instead. In both cases, `thought_signature` refers to the `signature` field.
Send the `tool_search_call` and `tool_search_result` steps back with their
`signature` values unchanged.

The following example replays a conversation statelessly with a deferred tool:

{% tabs %}
  

  {% tab label="Python" %}
  ```python
  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 from one currency to another.",
          "defer_loading": True,
          "parameters": {
              "type": "object",
              "properties": {
                  "amount": {"type": "number"},
                  "to": {"type": "string"},
              },
              "required": ["amount", "to"],
          },
      },
  ]
  
  history = [
      {
          "type": "user_input",
          "content": [{"type": "text", "text": "Convert 100 USD to EUR."}],
      }
  ]
  
  interaction = client.interactions.create(
      model="gemini-4-hydrogen",
      store=False,
      input=history,
      tools=tools,
  )
  
  # Append every step unchanged, including tool_search_call and
  # tool_search_result steps and their signatures.
  for step in interaction.steps:
      history.append(step.model_dump())
  
  fc_step = next(s for s in interaction.steps if s.type == "function_call")
  history.append({
      "type": "function_result",
      "name": fc_step.name,
      "call_id": fc_step.id,
      "result": [{"type": "text", "text": '{"amount": 92.4, "currency": "EUR"}'}],
  })
  
  final_interaction = client.interactions.create(
      model="gemini-4-hydrogen",
      store=False,
      input=history,
      tools=tools,
  )
  
  print(final_interaction.output_text)
  ```

  {% /tab %}

  

  {% tab label="JavaScript" %}
  ```javascript
  import { GoogleGenAI } from "@google/genai";
  
  const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });
  
  const tools = [
    { type: "tool_search" },
    {
      type: "function",
      name: "convert_currency",
      description: "Convert an amount from one currency to another.",
      defer_loading: true,
      parameters: {
        type: "object",
        properties: {
          amount: { type: "number" },
          to: { type: "string" },
        },
        required: ["amount", "to"],
      },
    },
  ];
  
  const history = [
    {
      type: "user_input",
      content: [{ type: "text", text: "Convert 100 USD to EUR." }],
    },
  ];
  
  const interaction = await ai.interactions.create({
    model: "gemini-4-hydrogen",
    store: false,
    input: history,
    tools: tools,
  });
  
  // Append every step unchanged, including tool_search_call and
  // tool_search_result steps and their signatures.
  history.push(...interaction.steps);
  
  const fcStep = interaction.steps.find((s) => s.type === "function_call");
  history.push({
    type: "function_result",
    name: fcStep.name,
    call_id: fcStep.id,
    result: [{ type: "text", text: '{"amount": 92.4, "currency": "EUR"}' }],
  });
  
  const finalInteraction = await ai.interactions.create({
    model: "gemini-4-hydrogen",
    store: false,
    input: history,
    tools: tools,
  });
  
  console.log(finalInteraction.output_text);
  ```

  {% /tab %}

  

{% /tabs %}

## Errors  {% id="errors" %}

{% table %}
  * Message
  * Cause
  * Resolution

  ---

  * `tool_search tool must be specified when using defer_loading.`
  * A `function` or `mcp_server` tool sets `defer_loading: true`, but the
    request has no `tool_search` tool.
  * Add `{"type": "tool_search"}` to the tools array, or remove
    `defer_loading`.

  ---

  * `When defer_loading is set on a FunctionDeclaration, a Tool with
tool_search must also be provided in the request.`
  * A function sets `defer_loading: true`, but the request has no server-side
    `tool_search`. This happens when the only `tool_search` is client-side
    (`execution: "client"`), or when a follow-up request leaves out the
    `tool_search` entry.
  * Remove `defer_loading` when you use client-side retrieval. With server-side
    retrieval, send the full `tools` array, including `{"type": "tool_search"}`,
    on every request.

  ---

  * `Cannot specify both client-side and server-side tool_search tools.`
  * The tools array contains both a server-side and a client-side
    `tool_search`.
  * Declare exactly one.

  ---

  * `Only a single ToolSearch definition is expected.`
  * The tools array contains more than one `tool_search` of the same kind.
  * Declare exactly one.

  ---

  * `ToolSearch name must be specified when execution mode is CLIENT_SIDE.`
  * A client-side `tool_search` is missing `name`.
  * Add a `name`.

  ---

  * `ToolSearch description must be specified when execution mode is
CLIENT_SIDE.`
  * A client-side `tool_search` is missing `description`.
  * Add a `description`.

  ---

  * `ToolSearch name must not be specified when execution mode is
SERVER_SIDE.`
  * A server-side `tool_search` sets `name`. The same error is returned for
    `description` and `parameters`.
  * Remove the field, or set `execution: "client"`.

  ---

  * `short_description can only be set if defer_loading is true`
  * A function sets `short_description` without `defer_loading: true`.
  * Set `defer_loading: true`, or remove `short_description`.

  ---

  * `deferred loading is not supported for this model`
  * The model doesn't support tool retrieval.
  * Use one of the [supported models](/docs/tool-retrieval#supported-models).

  ---

  * `Server side tool call context must be circulated when using deferred
loading functions.`
  * In a stateless request, the history includes a `function_result` for a
    deferred tool but not the `tool_search_call` and `tool_search_result` steps
    that loaded it. This error appears on the second call, not the first.
  * Send back every `tool_search_call` and `tool_search_result` step unchanged,
    including `signature`. See [Stateless conversations](/docs/tool-retrieval#stateless).

  ---

  * `Tool call part is missing thought_signature.` or `Tool response part is
missing thought_signature.`
  * In a stateless request, a `tool_search_call` (call part) or
    `tool_search_result` (response part) step was sent back without its
    `signature` field.
  * Send the retrieval steps back exactly as you received them, including
    `signature`. See [Stateless conversations](/docs/tool-retrieval#stateless).

  ---

  * `Function call is missing a thought_signature in functionCall parts.`
  * In a stateless request, a `function_call` step, or the `thought` step before
    it, was sent back without its `signature`.
  * Send every step back unchanged, including `thought` steps and their
    signatures. See [Stateless conversations](/docs/tool-retrieval#stateless).

  ---

  * `Server side tool call context must be circulated ... Missing circulated
context for functions: FUNCTION_NAME`, even though you sent every step back
  * The model called a deferred function that no `tool_search` in the
    conversation loaded, usually because the function's name appears in your
    system instructions or in another tool's output. The error appears on the
    request that sends the `function_result`, and the conversation can't
    continue.
  * Don't defer tools that you mention by name. See
    [Best practices](/docs/tool-retrieval#best-practices).
{% /table %}

For the full list of API error codes, see [API errors](/docs/api-errors).

## Best practices  {% id="best-practices" %}

*   **Keep your most-used tools loaded.** Leave `defer_loading` unset on the
    handful of tools your agent uses on most turns, and defer the long tail of
    specialized tools.
*   **Keep tools that you mention by name loaded.** If a tool name appears in
    your system instructions or in another tool's output, don't defer that tool.
    Otherwise the model can call it without searching for it first, and the
    next request fails with the
    `Server side tool call context must be circulated` error.
*   **Send the full schema for every deferred tool.** Include the complete
    `parameters` schema on deferred function declarations. Unloaded schemas
    aren't billed, and a tool sent with only a `name` and `short_description`
    comes back from a search with an empty schema that the model can't call.
*   **Tell the model when to search.** Add an instruction such as "If none of
    your loaded tools can complete the task, use tool search to find one" to
    your system instructions.
*   **Disambiguate similar tools.** When several services expose similar
    operations, prefix function names with the service (for example,
    `billing_get_customer` and `crm_get_customer`) and name the service at the
    start of `short_description`.
*   **Describe your catalog in a client-side `tool_search`.** List the
    namespaces or categories you can search, and when to search, in its
    `description`. A vague description makes the model less likely to search.
*   **Return function declarations as objects.** In client-side retrieval, put
    complete declarations in the `function_result.result` array. Don't send them
    as a JSON string. Include the `name` and `call_id` of the search
    `function_call` in every `function_result`.
*   **Handle searches that find nothing.** If your client-side search finds no
    match, return a short text result that says so and lists what the model can
    search for, so it can adjust its query.
*   **Check the steps, not the status.** A response can contain a
    `function_call` step for you to execute even when its `status` isn't
    `requires_action`. Look for `function_call` steps in `steps` on every
    response.

## Token usage and billing  {% id="pricing" %}

Tool retrieval has no separate charge. Every token is billed at the standard
input, cached, and output rates for the model you call. See
[Pricing](/docs/pricing).

Deferred tools count toward your input tokens only as one-line entries in the
deferred tool list. Their parameter schemas aren't billed until the model loads
them. Each server-side search adds its own cost, so measure the net effect on
your own traffic. See [What you're billed for](/docs/tool-retrieval#billing).

### Usage fields  {% id="usage-fields" %}

Each interaction reports token counts in its `usage` object, and these fields
are what you're billed for. With tool retrieval, check these fields:

{% table %}
  * Field
  * What it includes

  ---

  * `total_input_tokens`
  * The prompt of the first model call in the request: your input, the
    conversation history, system instructions, the schemas of tools that aren't
    deferred, the tool search instructions, and the list of deferred tools.

  ---

  * `total_tool_use_tokens`
  * The prompts of the additional model calls the API makes within the same
    request after a server-side tool runs, including each server-side tool
    search. Each of these calls sends the full context again, plus the newly
    loaded schemas. Billed at the input rate.

  ---

  * `total_cached_tokens`
  * The part of the prompt served from the
    [implicit cache](/docs/caching). Billed at the cached rate instead of the
    input rate.

  ---

  * `total_output_tokens`, `total_thought_tokens`
  * Generated tokens, the same as for any request.
{% /table %}

### What you're billed for  {% id="billing" %}

*   **The deferred tool list.** Each deferred tool adds one line to the input:
    its name and its `short_description`, or the first sentence of its
    `description` if `short_description` isn't set. Parameter schemas aren't
    included. In early testing, this came to about 26 tokens per deferred tool.
*   **Tool search instructions.** Enabling server-side `tool_search` adds a
    small, fixed block of input tokens to every request.
*   **Each search.** When the model calls a server-side `tool_search`, the API
    runs another model call in the same request with the full context and the
    loaded schemas. That call's entire prompt is reported in
    `total_tool_use_tokens`. As a result, a search costs roughly as much input
    as the request's prompt again, minus any cached tokens. Each additional
    search in the same request adds another pass. With client-side retrieval,
    each search is a separate request, which is billed like any other request.
*   **Loaded schemas.** Each schema the model loads stays in context and is
    billed as input on every later call and turn, the same as a tool you
    declared upfront.

### Caching  {% id="caching" %}

Tool retrieval works with [implicit caching](/docs/caching). Retrieved schemas
are added to the conversation where the model loads them, not to the start of
the prompt, so your system instructions, tool list, and earlier turns stay an
unchanged prefix from one request to the next. Once that prefix is above the
model's minimum cacheable size, later requests in the conversation can be served
from the cache, including the extra model call that each server-side search
makes. Cached tokens are reported in `total_cached_tokens`.

Keep in mind that deferring tools also makes the prompt smaller. If a prompt was
only above the minimum cacheable size because of its full tool schemas, it can
fall below it once those tools are deferred. See
[Context caching](/docs/caching) for the minimum size for each model.

### When tool retrieval saves tokens  {% id="when-it-saves" %}

Tool retrieval saves tokens when the schemas you no longer send on every request
outweigh the cost of the searches. That's usually the case when:

*   Your tool library is large, and a typical request uses only a few tools.
*   Most requests don't need a search, or need just one.

It can cost more when:

*   Your tool library is small, so there's little to save.
*   Your conversation context is large and almost every request searches,
    because each search sends that context again.

The following example is illustrative. It uses round numbers, not measurements,
and leaves out output tokens and caching. A request sends 2,000 tokens of
conversation, the model loads 2 tools (400 tokens each), and the conversation
takes two requests: one that ends in a `function_call` and one that returns the
`function_result`.

{% table %}
  * Scenario
  * Static loading (input tokens)
  * Tool retrieval (input + tool-use tokens)

  ---

  * 200 tools, 400 tokens each
  * 2 × (2,000 + 80,000) = **164,000**
  * Request 1: 2,000 + 5,200 deferred list + 150 instructions = 7,350, plus a
    search pass of 7,350 + 800 = 8,150. Request 2: 8,150. Total: **about 23,650**

  ---

  * 10 tools, 400 tokens each, 30,000-token context
  * 2 × (30,000 + 4,000) = **68,000**
  * Request 1: 30,000 + 260 + 150 = 30,410, plus a search pass of 31,210.
    Request 2: 31,210. Total: **about 92,830**
{% /table %}

Measure against your own traffic before rolling tool retrieval out broadly.

## Limitations  {% id="limitations" %}

*   Tool retrieval is supported on the Interactions API only. The
    `generateContent` method does not support it.
*   Server-side and client-side retrieval are mutually exclusive within a
    request.
*   `defer_loading` applies to server-side retrieval only.
*   The model may issue several search calls in one turn when it needs multiple
    tools.
*   Retrieved tools stay in context for the rest of the conversation. There is
    no way to unload a tool once the model has loaded it.
*   Tool declarations aren't stored between requests. Send the full `tools`
    array on every request. See
    [Send the full `tools` array on every request](/docs/tool-retrieval#resend-tools).
*   A query that matches no deferred tool produces a text response rather than
    a structured retrieval error. Don't rely on a `tool_search_result` step to
    detect a retrieval miss.

## Supported models  {% id="supported-models" %}

Tool retrieval is supported on the following models:

*   [`gemini-4-hydrogen`](/docs/models/gemini-4-hydrogen)
*   [`gemini-4-argon`](/docs/models/gemini-4-argon)
*   [`gemini-3.8-flash`](/docs/models/gemini-3.8-flash)
*   [`gemini-3.6-flash`](/docs/models/gemini-3.6-flash)

Requests that set `defer_loading` on an unsupported model return a `400` error.

## What's next  {% id="whats-next" %}

*   Learn the basics in the [Function calling](/docs/function-calling) guide.
*   Combine tool retrieval with built-in tools using
    [Multi-tool use](/docs/function-calling#native-tools).
*   Browse the full set of [Tools](/docs/tools).
*   Reduce cost further with [Context caching](/docs/caching).

