對應原題（Common ‧ Agents and Tool Use；Anthropic）
- How many tools is too many? How do you design tool schemas an LLM can actually use correctly?
— Asked at: Anthropic, Cognition- Design the tool surface for a coding agent: which tools exist, what their schemas look like, and how results come back. — Asked at: Anthropic
- What matters more for an agentic coding tool like Claude Code: the model or the harness? — Asked at: Anthropic
🎯 什麼情境該想到我
當你「agent 選錯工具、或工具回傳把上下文吃光」的時候。
★ 工具定義不是 API 文件，是 prompt。 它每一次呼叫都被送進模型，而且直接決定模型的決策品質。
⚙️ 怎麼用
★ 一、「幾個太多」——問錯問題了
沒有絕對數字，因為真正的瓶頸不是數量，是可區分性。
三個真實的失效機制：
| 機制 | 說明 |
|---|---|
| 1. Token 固定開銷 | 每個工具的 schema 每次呼叫都要重送。50 個工具可能就是 10k+ token 的固定成本——每一步都付一次（見 ReAct 與 Agent Loop 的 成長） |
| 2. ★ 選擇困難 | 工具越多、描述越相似，選錯率越高。這是主要殺手 |
| 3. 上下文稀釋 | 工具定義佔掉的位置，就是真正的任務內容佔不到的位置 |
★ 關鍵洞察：3 個描述重疊的工具，比 20 個界線清楚的工具更糟。
❌ 糟糕（3 個，但會選錯） search_docs 「搜尋文件」 find_documents 「尋找相關文件」 query_knowledge 「查詢知識庫」 → 模型無從判斷差別，只能亂猜 ✅ 良好（3 個，界線清楚） search_internal_wiki 「搜尋公司內部 wiki。用於政策、流程、團隊資訊。 不要用於程式碼或客戶資料。」 search_codebase 「搜尋本專案原始碼。用於找函式定義與用法。」 query_crm 「查詢客戶資料庫。需要客戶 ID 或 email。」
★ 所以要量的不是數量，是「工具選擇準確率」：
建一組 (查詢 → 正確工具) 的測試集 → 量準確率
每加一個工具就重跑一次 → 準確率掉了就是加太多了
這是一個可以直接寫進 CI 的數字。 面試講得出這個做法，比講「大概 20 個」有價值得多。
工具太多時的四種解法
| 解法 | 做法 |
|---|---|
| 參數化取代增生 | ★ 一個 search(source: enum[wiki, code, crm], query)，而不是 3 個 search_X |
| 動態工具載入 | 依對話階段或意圖，只暴露相關子集 |
| 工具檢索（tool RAG） | 對工具描述做語意檢索，只把 top-k 放進 context。工具數量上百時的標準做法 |
| 子 agent 封裝 | 把一整群工具包成一個「資料庫專家」工具，由子 agent 內部分派（見 多 Agent 編排與 Agent Drift） |
★ 二、Schema 設計的八條規則
| # | 規則 | ❌ | ✅ |
|---|---|---|---|
| 1 | 名稱：動詞開頭、具體 | docs | search_internal_docs |
| 2 | ★ 描述寫「何時用／何時不要用」 | 「搜尋文件」 | 「搜尋公司內部文件。用於政策與流程問題。不要用於程式碼搜尋（改用 search_codebase）或即時資料。」 |
| 3 | 參數越少越好，必填越少越好 | 8 個參數 | 1 必填 + 2 選填 |
| 4 | ★ 用 enum 取代自由文字 | status: string | status: enum["open","closed","pending"] —— 自由文字模型一定會亂填 |
| 5 | 參數名要自我說明 | d1, d2 | start_date_iso8601, end_date_iso8601 |
| 6 | 避免深層巢狀 | 四層巢狀物件 | 扁平化，必要時拆成兩個工具 |
| 7 | 在描述裡放範例 | — | 例：query="退款政策", source="wiki" |
| 8 | ★ 不要讓模型拼裝需要精確知識的字串 | run_sql(query: string) | query_orders(customer_id, date_range) —— 除非你能驗證並沙箱化 |
第 2 條是最高投報率的一條。 大多數工具描述寫的是「這個工具做什麼」（模型從名稱就猜得到），而模型真正需要的是「什麼時候該選我、什麼時候不該」。
第 8 條的例外：Text-to-SQL、程式碼執行這類工具本質上就是要模型拼字串。這時必須配：唯讀權限、schema 白名單、查詢逾時、結果筆數上限、以及執行前的驗證（見 可逆性、審計與人類把關）。
★ 三、回傳設計（最常被忽略的一半）
工具回什麼，和工具做什麼一樣重要——因為回傳值會直接進入模型的上下文。
| 原則 | 說明 |
|---|---|
| 資訊密度要高 | 丟 5000 行 raw JSON 給模型，等於燒掉上下文又沒幫上忙。只回需要的欄位 |
| ★ 截斷要明示並可續讀 | ...(已截斷，還有 1,240 行。用 offset=100 繼續讀) —— 靜默截斷會讓模型以為它看到了全部，這是危險的 bug |
| 錯誤要可行動 | ❌ Error: 400 ✅ 錯誤：date 格式須為 YYYY-MM-DD，收到 "上週"。 |
| 結構化但好讀 | 表格、清單優於巢狀 JSON。模型讀 Markdown 表格比讀深層 JSON 準 |
| ★ 附帶「下一步」的線索 | 「找到 3 個相符檔案。用 read_file 讀取內容。」——省下模型一次猜測 |
| 空結果要說清楚 | ❌ [] ✅ 在 wiki 中找不到「量子退火」的相關內容。試試更廣的關鍵字，或改用 search_codebase。 |
★ 四、Coding Agent 的工具面（Anthropic 那題）
一個經得起推敲的最小工具集：
| 工具 | 為什麼需要 |
|---|---|
read_file(path, offset?, limit?) | 讀。必須支援分段，否則大檔直接爆上下文 |
write_file(path, content) | 建新檔 |
edit_file(path, old_string, new_string) | ★ 精確取代，不是重寫整檔——省 token，且改動範圍可審查 |
bash(command, timeout) | 萬用逃生口：測試、建置、git、任意 CLI |
grep(pattern, path?) / glob(pattern) | 定位。沒有這兩個，模型只能亂猜檔名 |
設計理由：
- 正交 —— 每個工具做一件事，彼此不重疊，模型不用在相似選項間猶豫
- 可組合 —— glob → grep → read → edit → bash(test) 是完整的工作流
- 對應開發者的真實動作 —— 模型在預訓練時見過大量這樣的操作敘述
edit而不是write—— 精確取代讓 diff 小、可審、可回退（見 工具-外科手術式修改）
關鍵回傳設計：
read_file回傳帶行號（模型才能精確指出要改哪裡）edit_file的old_string必須唯一，不唯一就報錯——這強迫模型先讀再改，防止盲改bash回傳 stdout + stderr + exit code，三者都要
★ 五、模型 vs Harness（Anthropic 那題）
答案不是二選一，而是講清楚各自決定什麼：
| 決定什麼 | |
|---|---|
| 模型 | 能力天花板 —— 它能不能想出對的做法 |
| ★ Harness | 失敗的下限與可靠度 —— 想對了之後，會不會被執行環境搞砸 |
好的 harness 讓中等模型可用；爛的 harness 讓最強的模型也失控。
Harness 的核心價值是「可驗證的回饋迴圈」：
模型改了程式碼 → harness 自動跑 測試 / 型別檢查 / lint
→ 把失敗訊息餵回去
→ 模型自我修正
有這個迴圈，模型的錯誤會被收斂；沒有，錯誤會累積。
這也是為什麼 coding agent 比其他領域的 agent 成功得多——程式碼有編譯器和測試，是天然的 verifier（見 工具-讓LLM產出可驗證的產物、工具-把命令變成可驗證的目標）。
面試答法：「模型決定天花板，harness 決定地板和方差。在真實產品裡，方差比天花板更痛——所以我會先投資 harness：精確的編輯工具、可靠的回饋訊號、清楚的錯誤訊息、預算與護欄。」
⚠️ 注意 / 什麼時候不適用
- 工具描述會被注入。第三方 MCP server 的工具描述進了你的 prompt——它是不可信輸入（見 工具-MCP安全防護要點）。
- 加工具前先量準確率。「多一個總不會怎樣」是工具集腐化的開始。
- schema 改了要重測。模型對描述措辭很敏感，改一句話可能讓選擇準確率掉好幾個百分點。
- 別把所有東西都做成工具。能用固定流程直接執行的，不要讓模型決定。
- 回傳不要含大量樣板（HTTP header、完整 stack trace）。那是給人看的，不是給模型看的。
- 各家的 schema 支援度不同（JSON Schema 的哪些關鍵字有效、strict mode、巢狀深度）。換供應商要重測。
- 工具數量與選擇準確率的關係是非線性的。可能 15 個都很好，第 16 個（和第 7 個相似）一加就崩。
🧪 我實際套用的紀錄
- 2026-09-20：從面試題庫展開。待辦：為現有工具集建一組「查詢 → 正確工具」測試集，放進 CI。
🔗 相關
- Function Calling 與結構化輸出 —— schema 怎麼被執行
- ReAct 與 Agent Loop —— 工具回傳進入迴圈之後
- 多 Agent 編排與 Agent Drift —— 子 agent 封裝
- 可逆性、審計與人類把關 —— 有副作用的工具
- 工具-外科手術式修改 —— 為什麼 edit 優於 write
- 工具-讓LLM產出可驗證的產物 —— harness 的核心
- 工具-MCP安全防護要點 —— 工具描述的信任邊界