Codex 擴充能力與工具系統 Part 04｜Tool Calling 與 Tool Search 分工

工具只有幾個時，Tool Calling 幾乎不用特別解釋。模型拿到工具 schema，選一個，填 arguments；應用程式執行後把結果送回去，模型再繼續往下做。

資源壓力往往先出現在 tool call 之前。

一個 agent 接上 GitHub、Google Drive、資料庫、內部 API、瀏覽器和幾個 MCP server 之後，可用工具很容易從「看一眼就知道有哪些」變成一大份 catalogue。如果每次 request 都先附上所有完整 tool definitions，模型還沒碰到程式碼或問題本身，context 已經先花掉一部分在工具說明上。

工具變多之後，多出來的問題是 discovery：這一輪到底需要看哪些工具？Tool Search 就插在這裡。等相關 definition 進到 context，後面的 Tool Calling 還是照常發生。工具數量本身不是一條可靠的切換線，重點是整套 schemas 對 context 和 latency 造成了多少實際負擔。

Tool call 之前，schema 已經先佔了 context

OpenAI 的 Function Calling 流程很直接：把可呼叫工具提供給模型，模型回傳 tool call，應用程式執行，再把 tool output 送回模型。模型接著產生回答，或繼續呼叫下一個工具。

這種做法在小型、固定的工具集裡沒有什麼問題。假設 agent 只有讀檔、寫檔、shell、Git，再加幾個專案內 API，直接把 definitions 放進 model input，路徑短，也沒有額外的 discovery step：

User request
    ↓
Model receives tool schemas
    ↓
Tool call: name + arguments
    ↓
Tool execution
    ↓
Tool result
    ↓
Model continues

成本會隨工具面變大而累積。Tool definition 不只有 function name，還有 description、parameter schema、required fields、enum、nested objects 等內容。採用 upfront exposure 時，這些文字會跟程式碼、文件、conversation history、檢索結果一起吃同一個 context budget。

如果一個 task 最後只會用到整套工具中的兩三個，其餘 definitions 在這一輪就只是預付成本。

Tool Search 延後的是完整 definition

GPT-5.4 的 Tool Search 把工具 discovery 從 upfront prompt 拆出去。模型先拿到較輕量的可用工具資訊與搜尋能力；需要某種能力時再查找，matching tool definition 才在那個時間點加入 conversation。

runtime 因此多了一步：

User request
    ↓
Lightweight tool information + Tool Search
    ↓
Search for relevant tools
    ↓
Load matching tool definition
    ↓
Tool call: name + arguments
    ↓
Tool execution
    ↓
Tool result
    ↓
Model continues

Search 和 Calling 不在同一個 stage。前者先找出需要載入的 definition，後者才決定要 call 哪個工具、帶哪些 arguments。

	Tool Search	Tool Calling
當下要決定什麼	哪些 tool definitions 需要進場	已可用的工具中要 call 哪一個
主要工作	discovery / retrieval	selection / invocation
目標工具的完整 schema	可能還沒載入	已經可供模型使用
產物	matching tool definition	tool name + arguments
接下來	把工具 definition 帶進後續推理	執行工具並回傳 output

多一個 discovery stage，也就多一個 failure surface。原本可能在 tool selection 或 arguments 上出錯，現在還可能先找不到需要的工具。Codex 的 searched-tool flow 會把 tool name、description 和 input fields 帶進搜尋結果。PR 沒有公開 search ranking 規則，這裡不往下猜。對實際 debug 來說，差別已經很明確：模型可能還沒開始組 arguments，就先卡在 discovery。

36 個 MCP servers 下，token 少了 47%

OpenAI 在 GPT-5.4 發布時，用 Scale MCP Atlas 的 250 個 tasks 做過一組對照。測試同時啟用 36 個 MCP servers，一邊把所有 MCP functions 直接放進 model context，另一邊把這些 servers 放到 Tool Search 後面。

Tool Search 版本的 total token usage 降低 47%，accuracy 相同。

這是特定 benchmark 與配置下的結果，不能直接外推到別的 agent。在這組 workload 裡，schema 本身已經大到足以形成可量到的 context 成本。OpenAI 同一份資料也提到 prompt cache preservation，因為 request 不必反覆攜帶一大段可能持續變動的完整 schemas。

Codex 後來拿掉了「工具數量決定 flow」這件事

Codex 早期曾把 tool count 直接寫進這條 flow。

早期實作裡，MCP tools 只有在 feature flag 開啟，或工具數量至少達到 100 時，才會放到 tool_search 後面。這會造成一個不太漂亮的結果：同一套工具能力，runtime flow 會跟 rollout configuration 和 tool count 綁在一起。

2026 年 6 月合併的 Codex PR #29486 把這個數量相依行為拿掉。只要 model / provider 支援 Tool Search 與 namespaced tools，實際生效的 MCP tools 就延後到搜尋後再載入；search 用不了時，仍走原本的 direct exposure，保留相容性。

PR 裡連測試為什麼要改都寫得很具體。舊測試常假設模型第一個 request 就看到 MCP tool 並立即 call；新的實際 flow 是先收到 tool_search、搜尋、取得 matching MCP tool，下一個 request 才呼叫它。

Tool Search
    ↓
Matching MCP tool becomes available
    ↓
Tool Calling

到了 Codex CLI 0.143.0，release note 也正式寫明 MCP tools 預設使用 Tool Search。舊的「100 tools」條件因此只是一段實作歷史，不是現在要自己設定的切換值。

一個工具其實有四種不同狀態

大型工具系統裡，人們常用一句「這個工具可不可以用」代稱幾個完全不同的狀態。

把 runtime 拆開後，可以用四個狀態看：

1. Availability
   工具已連接或註冊，出現在系統可管理的工具面中

2. Discovery
   這個 task 找到相關工具，definition 準備進入 context

3. Invocation
   模型選定工具並產生 arguments

4. Execution
   工具實際執行，結果再回到模型

這是用來讀懂流程的 explanatory model，不是 OpenAI 對 Codex 的官方四層 taxonomy。MCP server 已經連上，只能先說明它存在於系統的工具面；還要經過實際配置、filtering 與後續流程，才知道這一輪模型是否真的看得到並能呼叫它。某個工具被搜尋到，也不代表它已經執行。

權限更不能跟 discovery 混在一起。OpenAI 對 Codex 的安全說明把 sandbox 定義為 technical execution boundary，approval policy 則決定什麼情況需要額外授權。Tool Search 改變的是工具何時進入模型可見範圍，不會因為「找到了」就自行擴大 sandbox、authentication 或原本的 permission boundary。

小型 tool set 仍然適合 direct exposure

如果工具很少、schema 短、集合穩定，而且 latency 很敏感，direct exposure 仍然是合理設計。它少一個 discovery round，也少一個 search miss 的可能性。

判斷時先看 workload 長什麼樣。如果同時掛了很多 MCP servers、schemas 越來越長，但典型 task 每次只碰其中一小部分，upfront exposure 的固定成本就會愈來愈難忽略。catalogue 還在持續增長時，這筆成本也會跟著長。工具面很小而且穩定時，則沒有必要為了架構漂亮硬塞一層 search。

如果是在設計自己的 agent，不用先找一個工具數量門檻。先看 schemas 到底佔了多少 prompt，再看一個典型 task 實際只會碰到整套工具中的多少。latency 很敏感時，還要把多一次 discovery round 的代價一起算進去。

對 Codex 使用者，支援的 MCP setup 已經走預設 searched-tool flow，不用自己照這套條件切模式。debug 時先看它到底是「工具沒接上」、「沒搜到」、「call 錯了」，還是「執行被邊界擋住」。這四種故障表面上都像「工具沒工作」，修法完全不同。

References

1. OpenAI, Function calling, documentation. https://developers.openai.com/api/docs/guides/function-calling
2. OpenAI, Function calling and other API updates, 2023-06-13. https://openai.com/index/function-calling-and-other-api-updates/
3. OpenAI, Introducing GPT-5.4, 2026-03-05. https://openai.com/index/introducing-gpt-5-4/
4. openai/codex GitHub PR #29486, [codex] Use tool search for MCP tools by default, merged 2026-06-22. https://github.com/openai/codex/pull/29486
5. openai/codex GitHub release, Codex 0.143.0, 2026-07-08. https://github.com/openai/codex/releases/tag/rust-v0.143.0
6. OpenAI, Running Codex safely at OpenAI, 2026-05-08. https://openai.com/index/running-codex-safely/