AIコーディング2026年11月更新

Gemini API Tool Retrievalの使い方|defer_loadingの書き方・料金・400エラー・注意点

公開日: 2026/11/20
Gemini API Tool Retrievalの使い方|defer_loadingの書き方・料金・400エラー・注意点

この記事のポイント

Gemini APIのTool Retrievalは、大量のツールのうち必要なもののスキーマだけをその場で読み込むInteractions APIのプレビュー機能です。tool_searchとdefer_loadingの書き方、MCPの遅延、2ターン目以降の注意、トークンの損得、400エラーの直し方を日本語でまとめました。

Gemini APIのTool Retrievalは、エージェントに持たせた大量のツールのうち、必要になったツールのパラメータスキーマだけをその場で読み込む機能です。tools 配列に {"type": "tool_search"} を足し、後回しにしたいツールに defer_loading: true を付けるだけで使えます。ただし2026年11月時点ではInteractions APIのプレビューで、generateContent では使えません。

Googleが2026年11月19日(米国時間)に公開したTool Retrievalについて、公式ガイドをもとに次の内容を扱います。

  • 仕組みと、3つの読み込み方式(通常・サーバー側の検索・クライアント側の検索)の違い
  • Python・JavaScript・RESTの書き方と、MCPサーバーを丸ごと遅延させる方法
  • 2ターン目以降に必ず守る書き方と、よく出る400エラーの直し方
  • トークン料金で得になる場面・損になる場面の試算
  • ClaudeのTool search toolとの違いと、安全に使うための注意点

数十〜数百のツールやMCPサーバーをつなぐエージェントを作っている開発者、Gemini APIで社内向けエージェントを検討しているエンジニア向けの記事です。

導入前に押さえておきたい3点

  • Tool Retrievalは「ツールが多く、1回のリクエストで使うのは少数」の構成で入力トークンを減らせる。公式の目安はツールが20〜30個を超えたら検討
  • ツールが少ない・会話のコンテキストが長い・ほぼ毎回検索が走る構成では、かえって高くなることがある。自社のトラフィックで測ってから本番に入れる
  • 2ターン目以降もtools 配列を毎回まるごと送り直すのが最大の注意点。省くと400エラーや誤った関数呼び出しが起きる

AIエージェントそのものの全体像はAIエージェントとはで整理しています。

Gemini API Tool Retrievalとは

Google公式ブログのGemini API Tool Retrieval発表記事のメイン画像

出典: Google 公式ブログ

Tool Retrievalは、ツールのスキーマを毎回全部コンテキストに入れる代わりに、モデルが必要と判断したツールのスキーマだけをGoogleのサーバー側で読み込む仕組みです。公式ブログは目的を「入力トークンを減らし、エージェントの規模が大きくなってもツール選択の精度を保つこと」と説明しています。

通常の関数呼び出しでは、ツールの名前・説明・パラメータスキーマを毎リクエストすべて送ります。ツールが10個程度なら問題になりませんが、社内システムやSaaSの連携が数百に増えると、スキーマだけで数万トークンを占めます。Tool Retrievalを使うと、遅延させたツールについてモデルが見るのは名前と説明の1行だけです。

1回のAPI呼び出しの中で起きること

サーバー側の検索(既定の方式)では、次の流れになります。

  1. 開発者が tools に {"type": "tool_search"} と、defer_loading: true を付けたツールを入れて送る
  2. モデルには遅延ツールの名前と説明だけが見える
  3. モデルが tool_search_call を出し、APIがスキーマを探して tool_search_result を返す
  4. モデルが読み込んだスキーマを使って function_call を出す
  5. 開発者が関数を実行し、function_result を返す

2〜4は1回のAPI呼び出しの中で済みます。検索用のインデックスを作ったり、検索サーバーを立てたりする必要はありません。各ステップはレスポンスの interaction.steps に順番に入り、種類は tool_search_call / tool_search_result / mcp_server_tool_call / mcp_server_tool_result / function_call / function_result / thought です。

提供状況と対応モデル

2026年11月20日時点の提供状況は次のとおりです。

項目

内容

状態

プレビュー(正式提供の時期は未発表)

対象API

Interactions APIのみ(generateContent は対象外)

APIバージョン

v1beta が必須

対応モデル(公式ガイドの一覧)

gemini-4-hydrogen / gemini-4-argon / gemini-3.8-flash / gemini-3.6-flash

追加料金

なし(トークンは各モデルの通常単価)

SDK

Interactions APIはPython google-genai・JS @google/genai の2.3.0以上

対応モデルには食い違いがあります。公式ブログは「Gemini 3.6以降と、すべてのGemini 4モデル」と書いていますが、公式ガイドの一覧にはGemini 4 Carbon、Gemini 4 Neon、Gemini 3.7 Flashが載っていません。一覧にないモデルで defer_loading を使うと400エラーになるため、現時点ではガイドの4モデルを前提に作るのが安全です。

各モデルの特徴はGemini 4 Hydrogenとは、Gemini 4 Argonとは、Gemini 3.8 Flashとは、Gemini 3.6 Flashとはで解説しています。

Tool Retrievalでできること

Model Context Protocol(MCP)公式サイトのロゴ画像

出典: Model Context Protocol 公式サイト

Tool Retrievalでできることは、大きく分けて「関数を個別に遅延させる」「MCPサーバーを丸ごと遅延させる」「検索を自分のアプリで行う」の3つです。

  • 関数ツールの個別遅延: function ごとに defer_loading: true を付ける。よく使うツールは遅延させずに残せるので、混在させて使える
  • リモートMCPサーバーの一括遅延: mcp_server に defer_loading: true を付けると、そのサーバーの全ツールが必要になったときだけ読み込まれる。MCPサーバーを複数つなぐ構成で効果が大きい
  • クライアント側の検索: 検索を自分のアプリで実装し、見せるツールを権限やユーザーごとに変えられる。最初の tools に無いツールも返せる
  • プレフィックスキャッシュとの両立: 遅延スキーマはプロンプトの先頭に入らず、読み込んだ位置に追記されるため、先頭部分のキャッシュが崩れない
  • 会話の継続: previous_interaction_id で検索ステップを含む履歴をサーバーが保持する。store=false のステートレス運用でも使える

MCPの基本はMCPとはで解説しています。

3つの読み込み方式の違い

公式ガイドは、ツールの渡し方を3方式に分けて比べています。

比較項目

通常(全部読み込む)

サーバー側の検索(既定)

クライアント側の検索

スキーマの渡し方

毎リクエスト全部送る

遅延分をGeminiが読み込む

自分のアプリが返す

検索のコード

不要

不要

自前の検索・ランキング

ツールを最初に宣言

する

する

しない

MCP

使える

使える

対象外

往復の追加

なし

なし

検索1回ごとに1往復

向いている場面

約20個未満で固定のツール

大きく固定のツール群

自社のツール登録簿・ユーザーごとのツール

迷ったらサーバー側の検索から始め、「ユーザーごとに使えるツールを変えたい」「自前の埋め込み検索を使いたい」といった要件が出てきたらクライアント側を検討する、という順番で進めると無理がありません。

強みと弱み・制約

Tool Retrievalの強みは、検索の仕組みを自分で作らずに、ツールが増えたときのトークンを抑えられる点です。一方で、プレビューであることと、一度読み込んだツールを外せないことが大きな制約です。

強み

  • 設定が tool_search の追加と defer_loading だけで、インデックスもホスティングも不要
  • 遅延ツール1つあたりの一覧のコストは、初期テストで約26トークン(公式ガイド)。スキーマは読み込まれるまで課金されない
  • MCPサーバー単位でまとめて遅延できる
  • クライアント側の検索に切り替えれば、権限フィルタや会話途中のツール追加にも対応できる

弱み・制約

  • Interactions API限定・プレビュー。v1beta が必須で、正式提供までに仕様や項目名が変わる可能性がある
  • 読み込んだツールは会話中ずっとコンテキストに残り、外せない。以後のターンでも入力トークンとして課金される
  • サーバー側とクライアント側の検索は混在できない。defer_loading はサーバー側専用
  • 1ターンの中で検索が複数回走ることがある
  • 遅延ツールの上限数、検索のマッチ方法(名前以外に何を見るか)は非公表
  • 該当するツールが無いときは、構造化されたエラーではなくテキストで返る
  • Googleは削減率・レイテンシ・精度のベンチマークを公表していない
  • 遅延でプロンプトが短くなり、モデルの最小キャッシュサイズを下回ることがある

料金とトークンの考え方

Tool Retrieval自体に追加料金はありません。かかるのは入力・キャッシュ・出力トークンの通常料金だけです。ただし、サーバー側で検索が1回走るたびに、そのリクエストのプロンプト分をもう1回処理するのとほぼ同じトークンがかかる点に注意が必要です。

課金されるトークンの内訳

内訳

内容

遅延ツールの一覧

1ツールにつき1行(名前+short_description または説明の1文目)。約26トークン/ツール

検索の指示文

サーバー側の tool_search を有効にすると固定のブロックが入力に加わる(サイズは非公表)

検索1回ごとの追加処理

全コンテキスト+読み込んだスキーマでモデルがもう1回走る。total_tool_use_tokens に計上

読み込んだスキーマ

以後の会話の毎ターン、入力として課金される

使用量は total_input_tokens / total_tool_use_tokens / total_cached_tokens / total_output_tokens / total_thought_tokens で確認できます。導入前後で total_input_tokens と total_tool_use_tokens の合計を比べると、得か損かが判断できます。

得になる例・損になる例(試算)

公式の考え方に沿って、編集部で単純化した試算をしました。検索の指示文の固定トークンは非公表のため含めていません。キャッシュも考えない前提です。

ケース1: 200ツール(各スキーマ400トークン)、会話のコンテキスト3,000トークン、使うのは2つ

  • 通常: 3,000+200×400=約83,000トークン
  • Tool Retrieval: 1回目の処理 3,000+200×26=8,200、検索後の追加処理 8,200+2×400=9,000 → 合計約17,200トークン

gemini-4-hydrogen(入力 $1.50/100万トークン)で計算すると、1リクエストあたり約$0.125が約$0.026になり、1,000回で約$125が約$26に下がります。

ケース2: 10ツール(各400トークン)、会話のコンテキスト30,000トークン

  • 通常: 30,000+10×400=約34,000トークン
  • Tool Retrieval: 1回目 30,000+260=30,260、検索後の追加処理 30,260+400=30,660 → 合計約60,900トークン

ツールが少なくコンテキストが長いと、検索の追加処理が重くなり、通常より約1.8倍高くなります。公式ガイドも「ツールが少ない・コンテキストが大きい・ほぼ毎回検索する場合は高くなりうる」と明記しており、公式ブログは自社のトラフィックで測るよう勧めています。

対応モデルの単価と値上げ予定

公式料金ページ(Standardの有料枠、100万トークンあたり、2026年11月20日時点)の単価です。2つのモデル系統で値上げが予定されているので、見積もりは改定後の単価でも計算しておくと安心です。

モデル

入力

出力

キャッシュ入力

無料枠

gemini-4-hydrogen

$1.50

$7.50

$0.075

あり

gemini-4-argon

$2.00(2026-12-01から$4.00)

$10.00(12/1から$20.00)

$0.10(12/1から$0.20)

なし

gemini-3.8-flash

$0.75(2027-01-01から$1.50)

$3.75(1/1から$7.50)

$0.075(1/1から$0.15)+保存料

あり

gemini-3.6-flash

$0.75(2027-01-01から$1.50)

$3.75(1/1から$7.50)

$0.075(1/1から$0.15)+保存料

あり

Gemini 4系は暗黙キャッシュのみで、明示キャッシュには対応していません。Flash系の明示キャッシュには保存料($0.50/100万トークン/時、2027年から$1.00)がかかります。

Gemini API Tool Retrievalの使い方

Google Gen AI Python SDK(googleapis/python-genai)のGitHubリポジトリ画像

出典: googleapis/python-genai(GitHub)

使い方は「SDKを用意する → tool_search と defer_loading を書く → steps を確認する → 2ターン目以降は tools を送り直す」の順です。Pythonを中心に、JavaScriptとRESTの書き方も示します。

手順1: SDKとAPIキーを用意する

Interactions APIを使うには、Pythonなら google-genai、JavaScriptなら @google/genai の2.3.0以上が必要です。Tool Retrievalに必要な最小の版は公式に明記されていないため、最新版を入れておくのが確実です。APIキーはGoogle AI Studioで発行し、環境変数 GEMINI_API_KEY に設定します。

pip install -U google-genai
# JavaScript の場合
npm install @google/genai@latest

ステートレス(store=false)で使う場合は、tool_search_call / tool_search_result を認識できる版が必要です。古い版はこれらのフィールドを落としてしまい、2回目のリクエストで400エラーになります。

手順2: 最小のコードを書く(関数+MCPサーバーを遅延)

v1beta を指定してクライアントを作り、tools に tool_search と遅延ツールを入れます。公式サンプルをもとに、日本語のコメントを付けた例です。

from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

tools = [
    # 1リクエストに tool_search はちょうど1つ
    {"type": "tool_search"},
    {
        "type": "function",
        "name": "billing_convert_currency",
        "description": "Convert an amount from one currency to another.",
        "short_description": "billing: 通貨換算",  # 任意。検索時に description の代わりに使う
        "defer_loading": True,
        # 遅延させても完全なスキーマが必須
        "parameters": {
            "type": "object",
            "properties": {
                "amount": {"type": "number"},
                "to": {"type": "string"},
            },
            "required": ["amount", "to"],
        },
    },
    {
        # MCPサーバーを丸ごと遅延(サーバー名は snake_case)
        "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="100ドルを円に換算して、東京の明日の天気も教えて",
    tools=tools,
)

for step in interaction.steps:
    print(step.type, getattr(step, "name", ""))

うまく動けば、steps に tool_search_call → tool_search_result → function_call(関数の場合)または mcp_server_tool_call → mcp_server_tool_result(MCPの場合)が並びます。遅延させたMCPツールはリモートのMCPサーバーで実行され、結果も同じレスポンスに入ります。

遅延させる関数でも parameters を省いてはいけません。省くと検索で空のスキーマが返り、モデルがその関数を呼べなくなります。

手順3: JavaScript・RESTで書く場合

JavaScriptでも構造は同じで、ai.interactions.create() に同じ tools を渡します。

import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ httpOptions: { apiVersion: "v1beta" } });

const interaction = await ai.interactions.create({
  model: "gemini-4-hydrogen",
  input: "東京の明日の天気を教えて",
  tools: [
    { type: "tool_search" },
    {
      type: "mcp_server",
      name: "weather_service",
      url: "https://gemini-api-demos.uc.r.appspot.com/mcp",
      defer_loading: true,
    },
  ],
});

for (const step of interaction.steps) console.log(step.type, step.name ?? "");

RESTでは POST https://generativelanguage.googleapis.com/v1beta/interactions に、ヘッダー x-goog-api-key を付けて同じ本文を送ります。

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": "東京の明日の天気を教えて",
    "tools": [
      {"type": "tool_search"},
      {"type": "mcp_server", "name": "weather_service",
       "url": "https://gemini-api-demos.uc.r.appspot.com/mcp", "defer_loading": true}
    ]
  }'

手順4: 関数を実行して結果を返す(2ターン目)

function_call が出たら、アプリ側で関数を実行し、function_result を返します。ここでtools 配列をまるごと送り直すのが最重要ポイントです。Interactions APIではツール宣言がリクエスト間で保存されないため、previous_interaction_id を付けても tools・system_instruction・generation_config は毎ターン指定します。

# 毎回 steps を走査する(status == "requires_action" だけに頼らない)
calls = [s for s in interaction.steps if s.type == "function_call"]

results = []
for call in calls:
    output = run_my_function(call.name, call.arguments)  # 自分の関数を実行
    results.append({
        "type": "function_result",
        "name": call.name,
        "call_id": call.id,  # function_call ステップのIDを渡す
        "result": output,
    })

next_interaction = client.interactions.create(
    model="gemini-4-hydrogen",
    previous_interaction_id=interaction.id,
    input=results,
    tools=tools,  # 2ターン目以降も tools 全体を送る
)

tools を省くと、前のツールを呼び続ける、宣言していない関数を呼ぶ、内部の retriever: 付きの呼び出しが表に出る、といった不具合が起きると公式ガイドは説明しています。サーバー側の tool_search だけを省いた場合は400エラーです。

公式ガイドは、ステータスが requires_action 以外でも function_call が入ることがあるとしています。分岐はステータスではなく steps の中身で判断してください。

手順5: ステートレスで使う場合

store=false で使う場合、previous_interaction_id は使えないため、履歴を全部送り返します。このとき tool_search_call と tool_search_result のステップを、signature を含めてそのまま返すことが必要です。signature は中身を読んだり書き換えたりしてはいけない値で、欠けると "missing thought_signature" のエラーになります。

手順6: クライアント側の検索に切り替える

自前の登録簿や権限フィルタを使いたい場合は、tool_search に "execution": "client" を付けます。サーバー側と違い、name・description・parameters を自分で定義します。description はモデルが「いつ検索するか」を判断する手がかりになるので、検索対象の一覧と検索のタイミングを具体的に書きます。

tools = [
    {
        "type": "tool_search",
        "execution": "client",
        "name": "search_company_tools",
        "description": "社内の業務ツール(請求・顧客管理・在庫)を探す。"
                       "目的のツールが手元に無いときに呼ぶ。",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "namespace": {"type": "string"},
                "limit": {"type": "integer"},
            },
            "required": ["query"],
        },
    },
    # クライアント側では defer_loading を使わない
]

モデルは検索を通常の function_call として呼びます。アプリは検索を実行し、previous_interaction_id・同じ tools 配列・function_result を返します。function_result の result には完全な関数宣言の配列をオブジェクトのまま入れ(JSON文字列にしない)、検索呼び出しの name と call_id を含めます。該当が無いときは短いテキストで返し、モデルに言い直させます。

最初の tools に無いツールも返せるため、「会話の途中でユーザーが新しいSaaSを接続した」といったケースにも対応できます。その代わり、検索1回ごとにAPIとの往復が1回増えます。

公式が勧める設計のコツ

  • よく使うツールは遅延させず、使用頻度の低い多数のツールを遅延させる
  • システム指示や他ツールの出力に名前が出るツールは遅延させない
  • システム指示で「どんなときに検索するか」をモデルに伝える
  • 関数名にサービス名の接頭辞(例: billing_get_customer)を付け、short_description の先頭にもサービス名を置いて、似たツールを区別しやすくする

よく出る400エラーと直し方

公式ガイドが挙げている400エラーを、原因と直し方の早見表にまとめました。

原因

直し方

defer_loading があるのに tool_search が無い

{"type": "tool_search"} を足すか、defer_loading を外す

クライアント側の tool_search だけなのに defer_loading を使った

defer_loading を外すか、サーバー側に切り替える

2回目以降のリクエストでサーバー側の tool_search を省いた

毎回 tools 全体を送る

サーバー側とクライアント側を両方宣言した/同じ種類を2つ入れた

tool_search は1つだけにする

クライアント側で name か description が無い

両方を追加する

サーバー側に name・description・parameters を付けた

外すか、"execution": "client" にする

short_description を付けたのに defer_loading が無い

defer_loading: true を付ける

非対応モデルで defer_loading を使った

ガイド記載の4モデルに変える

ステートレス履歴に遅延ツールの function_result があるのに、検索ステップが無い

tool_search_call / tool_search_result をそのまま返す

検索ステップの signature が欠けている("missing thought_signature")

元の signature を戻す

システム指示や他ツールの出力に名前が出ている遅延ツールを、検索なしで呼んだ

そのツールは遅延させない。このエラーの後は会話を続けられない

最後のエラーは、エラー後にその会話を続けられなくなる点がやっかいです。PPC Landによると、エラー文は "Server side tool call context must be circulated" です。システム指示に「〇〇ツールを使って」と書いているなら、そのツールは最初から読み込んでおきます。

安全に使うための注意点

Tool Retrievalの公式ページとブログには、セキュリティ専用の注意書きはありません。ただし公式仕様から、業務で使う前に押さえておきたい点がいくつかあります。特に重要なのは、遅延させたMCPツールはリモートのMCPサーバーで実行され、結果が同じレスポンスで返ってくることです。開発者のコードで実行前に止める場所がないため、MCPサーバーの選び方と権限の絞り方がそのまま安全性を決めます。

  • 信頼できるMCPサーバーだけをつなぐ。mcp_server の allowed_tools で呼べるツールを絞る
  • headers に入れる認証トークンは権限を最小にする。書き込みや削除ができるトークンを安易に渡さない
  • リモートMCPはStreamable HTTPのみ(SSE非対応)。サーバー名は - を使わず snake_case にする
  • データの保存期間を確認する。Interactions APIは既定で store=true で、保存期間は有料枠55日・無料枠1日(有料枠は7/14/28/55日に短縮できる)。機密データを扱うなら短くするか store=false を検討する。store=false では previous_interaction_id が使えない
  • ユーザーごとに使えるツールを変えたいならクライアント側の検索にする。自前の権限フィルタを検索の段階に挟める
  • プレビューであることを前提に運用する。仕様変更に備え、本番では通常の関数呼び出しへ戻せる作りにしておく

Claude CodeでのMCP設定の考え方はClaude CodeのMCPサーバー設定ガイドでも扱っています。

ClaudeのTool search toolとの違い

Claude Platform DocsのTool search toolページの画像

出典: Claude Platform Docs

同じ目的の機能として、Anthropicの Claude API には「Tool search tool」があります。defer_loading: true で遅延させる考え方は共通ですが、Claude側は安定版で、検索方式や上限が公開されている点が大きく違います。

比較項目

Gemini API Tool Retrieval

Claude API Tool search tool

状態

プレビュー(v1beta)

安定版

対象API

Interactions APIのみ

Messages API(Bedrockなど他クラウド経由でも使える)

有効化

{"type": "tool_search"}

tool_search_tool_regex_20251119 または tool_search_tool_bm25_20251119

遅延の指定

defer_loading: true

defer_loading: true

検索方式

非公表(サーバー側)/クライアント側も使える

正規表現またはBM25/自前の検索も使える

MCPの一括遅延

mcp_server に指定

mcp_toolset の default_config

遅延ツールの上限

非公表

1リクエスト10,000個

該当なしのとき

テキストで返る

空の配列で返る

追加料金

なし(検索の処理は total_tool_use_tokens)

なし(読み込んだ定義は入力トークン)

Anthropicは公式ドキュメントで、ツール定義のトークンを85%超減らせると説明しています。Googleは削減率を公表していないため、数字だけで単純に比べることはできません。すでにGeminiの対応モデルでエージェントを作っているならTool Retrieval、正式版の安定性や上限の明示を重視するならClaudeのTool search tool、という選び方になります。

導入するかどうかの判断基準

入れるべきかどうかは、ツールの数・会話の長さ・1リクエストで使うツールの数の3点でほぼ決まります。

状況

判断

ツールが20個未満で固定

通常の関数呼び出しのままでよい

ツールが20〜30個を超え、1回で使うのは数個

サーバー側の検索を試す価値が高い

MCPサーバーを複数つないでいる

使う頻度の低いサーバーから遅延させる

会話のコンテキストが数万トークンと長い

検索の追加処理が重くなる。導入前後のトークンを必ず測る

ほぼ毎回、検索が走る

割高になりやすい。よく使うツールを遅延から外す

ユーザーや部署ごとに使えるツールが違う

クライアント側の検索を選ぶ

本番で仕様変更を避けたい

プレビューのため、正式提供まで待つか戻せる作りにする

公式の関数呼び出しページも、通常の関数呼び出しでは同時に有効なツールは10〜20個までが目安で、20〜30個を超えたらTool Retrievalを検討するよう書いています。

社内の業務システムやSaaSを何十もつないだエージェントを全社で使う場合は、1回あたりのトークンに加え、利用人数と回数で月額がどこまで増えるかを先に見積もっておくと判断がぶれません。個人の試用とは違う、全社展開や業務システムへの組み込みにかかる費用の考え方は社内AIチャットボットの費用で整理しています。

こんな人におすすめ・おすすめしない人

Tool Retrievalが役に立つのは、ツールが増えすぎてプロンプトが膨らんでいる開発者です。ツールが少ない構成では、効果を手間とコストが上回ります。

こんな人におすすめ

  • 数十〜数百の関数やMCPツールを持つエージェントを、Gemini APIで作っている
  • 複数のMCPサーバーをつなぎ、スキーマだけで入力トークンの大半を占めている
  • ツールが増えるにつれ、モデルが違うツールを選ぶようになってきた
  • すでにInteractions APIへ移行済み、または移行を予定している
  • ユーザーごとに使えるツールを切り替えたい(クライアント側の検索)

おすすめしない人

  • ツールが10〜20個程度で、今のトークン量に困っていない
  • 会話が長く、ほぼ毎回ツールを使う構成になっている
  • generateContent から移行する予定がない
  • プレビュー機能を本番に入れられない社内ルールがある
  • 対応が未確認のモデル(Gemini 4 Carbon・Neon、Gemini 3.7 Flash)で使いたい

よくある質問

generateContentのままでTool Retrievalは使えますか?

使えません。2026年11月時点ではInteractions API専用です。Interactions APIは2026年6月に一般提供となり、新規プロジェクトで推奨されるインターフェースになっています。generateContent も引き続きサポートされているので、Tool Retrievalが必要な処理からInteractions APIに移すやり方もとれます。

遅延ツールはいくつまで登録できますか?

上限は公表されていません。検索のマッチ方法も非公開です。数百を超える規模で使う場合は、選択の精度とトークン量を自社のデータで検証してから本番に入れるのが安全です。

一度読み込んだツールを会話の途中で外せますか?

外せません。読み込まれたスキーマは会話が終わるまでコンテキストに残り、毎ターン入力トークンとして課金されます。長い会話で多くのツールを読み込む使い方だと、後半ほどトークンが増えます。会話を区切って新しいInteractionを始める設計も検討してください。

検索で該当するツールが無かったことはどう判定しますか?

構造化されたエラーではなくテキストで返るため、tool_search_result の有無で「見つからない」を判定しないでください。モデルが回答を言い直したり、ユーザーに確認を求めたりする流れになるので、最終的な steps と出力テキストで処理を分けます。

Vertex AIでも使えますか?

公式ブログと公式ガイドは、Gemini API(Google AI Studio)のInteractions APIでのプレビューとして案内しています。Vertex AIでの提供については、2026年11月20日時点で公式の記載を確認できていません。

まとめ

Gemini APIのTool Retrievalは、{"type": "tool_search"} と defer_loading: true を足すだけで、大量のツールのスキーマを必要なときだけ読み込める機能です。ツールが20〜30個を超え、1回で使うのが数個なら、入力トークンを大きく減らせます。

一方で、2026年11月時点ではInteractions API限定のプレビューで、対応モデルは公式ガイドの4つです。読み込んだツールは外せず、ツールが少ない・コンテキストが長い構成ではかえって高くなります。導入する際は、次の3点を必ず守ってください。

  • 2ターン目以降も tools 配列をまるごと送り直す
  • 遅延ツールにも完全な parameters を書き、名前を出すツールは遅延させない
  • 導入前後で total_input_tokens と total_tool_use_tokens を比べ、得か損かを測る

遅延させたMCPツールはリモートで自動的に実行されるため、つなぐサーバーと allowed_tools・認証トークンの権限は、通常のMCP利用以上に絞っておきましょう。

参考: Google公式ブログ「Introducing Tool Retrieval in the Gemini API」 / Tool Retrieval 公式ガイド / Interactions API 概要 / 関数呼び出し・MCP / Gemini API 料金 / Claude Tool search tool

このツールを自社のシステムや業務にどう組み込むか、ご提案します

この記事の著者

AI革命

AI革命

編集部

AI革命株式会社の編集部です。最新のAI技術動向から実践的な導入事例まで、企業のデジタル変革に役立つ情報をお届けしています。豊富な経験と専門知識を活かし、読者の皆様にとって価値のあるコンテンツを制作しています。

AI・システム開発は、開始価格を公開しています

既存システムの改修 100万円〜・PoC 300万円〜(税別)。相談内容を送っていただくと、2営業日以内に担当者からご返信します