發生什麼事
Google 在 11 月 19 日的官方部落格介紹 Gemini API 的 Tool Retrieval。它處理的是一個常見問題:代理(agent)接上的工具越多,每次請求都要把所有工具的完整參數定義送給模型,輸入 token 變多、延遲變高,Google 也說工具清單變長時,模型選對工具的準確度可能下降。
Tool Retrieval 的思路是把工具庫「待命」,只在任務需要時才載入那個工具的參數 schema。目前是預覽版,只在 Interactions API 提供。

怎麼運作
伺服器端模式:在請求裡加入 tool_search 工具,並對想延後載入的工具設定 defer_loading: true。模型一開始只看得到這些工具的名稱與描述;需要時它按名稱要求某個工具,API 把 schema 載入,模型接著送出函式呼叫,這些都在同一次請求內完成。tool_search_call、tool_search_result 與 function_call 會出現在 interaction.steps,方便除錯。不必自己建索引,搜尋由 Gemini 在伺服器端執行。常用工具可以不延後,只把長尾工具延後;延後的 schema 不放在 prompt 開頭,所以前綴快取在多輪對話中仍有效。
遠端 MCP:在 mcp_server 工具上設 defer_loading: true,該 server 提供的全部工具都會延後載入。
Client 端模式:把 tool_search 宣告為 "execution": "client" 並自訂搜尋參數,適合已有自己的工具註冊表、向量索引或權限過濾的團隊。每次搜尋會多一次來回,因為查找由你的應用程式執行;好處是工具不用事先宣告,可以在對話中途(例如使用者連接新整合時)才提供。
費用與支援範圍
沒有額外收費,輸入與輸出 token 按所用模型的標準價格計。啟用 tool_search 會多一小塊固定的輸入 token,而模型載入的每個 schema 在該對話後續都會計入輸入。Google 表示工具庫大、未載入的 schema 多於已載入的時候才會省,建議用自己的流量實測。支援 Gemini 3.6 以上,包含全部 Gemini 4 模型。
官方範例是一則退款請求:模型搜尋到被延後的 issue_refund 工具,API 載入 schema 後,模型填入訂單編號與金額送出呼叫。
對你的影響
- 如果你的代理只接十來個工具,效益有限;工具數量到幾十個以上、或接了多個 MCP server 時,才值得試。
- 它仍在預覽,且綁定 Interactions API;已經用其他 Gemini 介面的專案,要先確認能否搬過去。
- 先拿真實流量比較開啟前後的 token 用量與工具選擇正確率,再決定是否上線。