Agent Tool Calling 最佳實務：你的 Agent 為什麼總選錯工具

Agent Tool Calling 最佳實務：你的 Agent 為什麼總選錯工具

Agent tool calling 最佳實務，是「能跑的 demo」與「在生產環境默默呼叫錯誤工具的 agent」之間唯一的防線。Anthropic 工程團隊實測，僅改寫一段工具描述，就將單次 tool result 從 206 token 壓到 72 token；Claude Code 更將每次工具回應硬性上限設為 25,000 token，因為膨脹問題確實存在。你的 agent 有四種失敗方式：選錯工具、寫錯參數、陷入無限迴圈、token 大量流失，而每一種都有本週就能上線的修法。

重點摘要：

• Agent tool calling 的失敗恰好分四類：選錯工具、參數錯誤、失控迴圈、token 流失。
• 工具描述是模型在選擇階段看到的唯一指令，因此能修正大多數選錯工具的問題。
• 扁平、符合任務形狀的 schema 加上輸入驗證，能消除多數參數錯誤。
• 精簡的工具回應與每次變更都跑評估迴圈，讓 token 成本與回歸問題可量化。

為什麼 agent tool calling 在生產環境會失敗？

Agent tool calling 有四種失敗模式：模型選了錯誤的工具、寫出錯誤的參數、陷入失控迴圈，或透過臃腫回應造成 token 流失。每種失敗命中呼叫迴圈的不同步驟，因此修復順序很重要。先處理選擇問題，因為選錯工具會污染後續所有步驟。

完整處方一覽：

按此順序逐一處理。實務 1 和 2 只需一個下午，就能消除你目前看到的大部分選錯工具與參數錯誤。工具描述不是文件，它是模型在選擇階段收到的唯一指令。

第一階段：設計模型真正能用的工具

Agent tool calling 中最便宜的可靠性提升，藏在工具定義裡，而不是 prompt 或模型選擇。模型從不讀你的 API 文件或 README。它只看到一個名稱、一段描述字串、一份 JSON schema，然後據此決定。把這三樣做對，選擇準確度就會在你動其他東西之前先提升。

實務 1：撰寫模型能據以行動的描述

把工具描述寫成給模型的指令，而不是 API 文件。一段能滿足人類開發者的描述（「users endpoint 的 REST 包裝」）對模型的決策毫無幫助。Anthropic 的工具撰寫工程指南與其工具定義最佳實務都推動同一個模式：說明何時使用該工具、回傳什麼、何時不該使用。

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

對比多數團隊實際上線的版本：

{
  "name": "get_user",
  "description": "Gets a user."
}

兩條規則就能完成大部分工作。第一，參數命名要讓含義毫無歧義：用 user_id，絕不用 user 或 id，因為 user 會誘使模型把名稱或 email 傳到該放 UUID 的位置。第二，明確宣告排除條件。「Do NOT use to search users」比任何正面描述都能防止更多選錯工具的呼叫，因為模型混淆重疊工具的頻率遠高於誤解單一、邊界清晰的工具。關於這些定義如何送達 OpenAI、Anthropic 和 Google API 的底層機制，參見我們的多供應商 function calling 指南。

實務 2：維持扁平、符合任務形狀的 schema

輸入 schema 保持扁平，只包含任務實際需要的欄位，不多也不少。帶有選填分支的巢狀物件是參數錯誤的溫床：模型必須推斷它從未見過範例的結構。OpenAI function calling 指南接受任意 JSON Schema，但寬容不等於可靠。

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

把它攤平到任務層級：

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

對任何有固定值集合的欄位，enum 優於自由文字。required 陣列優於全部選填。如果模型幾乎總是需要某個欄位，即使你的 API 將它標為選填，也在工具 schema 中設為 required。你不是在鏡像你的 API，你是在設計一個特定模型能正確填寫的介面。

第二階段：管理工具集，而不只是管理工具

當 agent 攜帶的工具超過一小撮，個別工具的品質就不夠了，因為選擇錯誤會隨模型讀取的清單長度而成長。

實務 3：將多步驟 API 序列包裝為原子化工具

把任何固定的 API 呼叫序列收縮為一個原子化工具。Anthropic 的工程文章以 schedule_event 和 get_customer_context 為範例：一次呼叫完成整件事，優於三次呼叫讓 agent 每次都必須正確串接。鏈條中的每一環都是模型可能卡住、錯誤重試或陷入迴圈的另一個回合。

# What the agent does WITHOUT an atomic tool: 3 calls, 3 chances to fail
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# One atomic tool: the sequence lives in your code, not the model's head
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

經驗法則：如果模型每次都要在 A 之後呼叫 B，那 A 和 B 就是穿著兩套衣服的同一個工具。

實務 4：動態命名空間、裁剪與過濾工具

為每個工具名稱加上命名空間，並只讓每個 agent 看到目前任務需要的子集。通用名稱在你接上第二個整合的瞬間就會衝突。想像一個 agent 同時連接兩台 MCP server，兩者都暴露一個叫 search 的工具：兩個相同的動詞，無法區分。Anthropic 記錄了前綴命名空間帶來的可量化評估提升：

裁剪與命名同等重要。支援 agent 在回答密碼問題時不需要載入帳單工具。Planner-worker 模式（由 planner 將任務路由給只載入相關工具的 worker）是標準修法；LangGraph 的動態工具載入教學有完整實作說明。多少工具算太多？把每個 agent 5-10 個當作工作範圍，而非鐵律：準確度隨清單增長而下降，解法是過濾，不是換更大的模型。如果你正在選擇路由與過濾層本身，參見我們的最佳 function calling 函式庫評比。

第三階段：控制回傳內容與輸出內容

迴圈是雙向的，而多數團隊只工程化了出站那一半。你的工具回傳什麼，決定了 context window 有多少能存活到下一回合；你的驗證拒絕什麼，決定了模型是從錯誤中學習還是重蹈覆轍。

實務 5：回傳精簡、高訊號的結果

回傳模型能據以行動的最小結果，用人类可讀的識別碼取代原始 ID。Anthropic 的工程文章記錄了一個工具，其預設結果長達 206 token；一個精簡的 response_format 設定將同樣的結果壓到 72 token，大約是原來的三分之一。把這乘以每個任務的數十次呼叫，它就決定了你的 agent 能不能跑完。

// Before: 206 tokens (shape per Anthropic's documented example)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// After: 72 tokens
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

同一來源還有兩個細節：Anthropic 在工具定義上支援 response_format enum（detailed 對 concise），讓你宣告想要的形狀，而不是解析消防水管。Claude Code 將工具回應上限設為 25,000 token，這是硬性天花板，無論如何都會截斷膨脹結果。Anthropic 也報告（作為他們的發現），將 UUID 解析為語義名稱可量化地減少了檢索幻覺，這就是上面「之後」的 payload 寫 "Dana Kim" 而非 c9a1...f2 的原因。臃腫回應也是成本問題；完整圖解參見我們的降低 LLM API 成本指南。

實務 6：驗證每次呼叫，讓錯誤成為模型的教學

在伺服器端驗證每次工具呼叫，並回傳包含修正方法的錯誤訊息。Martin Fowler 的 function calling 文章直言：永遠不要信任模型的輸出。它會在該放 enum 的地方傳字串，憑空捏造不存在的 ID。

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

錯誤字串就是全部。比較：

# Unhelpful: the model retries the same bad call
{"error": "invalid input"}

# Helpful: the model knows exactly what to change
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

你的工具回傳的每條驗證錯誤，都是你為模型的下一次嘗試寫的 prompt。指出約束條件並指向修正工具的錯誤，能把重試迴圈變成一次就恢復。這也是你的第一道安全防線；我們的 LLM guardrails 指南有深入說明。

第四階段：先做到安全，再做到可量化

安全與量測是同一個階段，因為未設閘門的破壞性操作和未量測的回歸，都會以你事先看不到的事故形式浮現。先為無法撤銷的操作設閘門，再對一切埋設量測，讓下一次工具變更是有證據支撐的決策，而不是祈禱。

實務 7：破壞性操作設人工審核閘門

將讀取工具與寫入工具分開，並對任何破壞性操作加上人工確認閘門。MCP 規範的工具註解正是為此而設：destructiveHint 標記執行破壞性更新的工具，openWorldHint 標記觸及外部系統的工具，讓客戶端能在執行前提示確認。用它。

這個失敗模式不是假設性的。Laurent Kubaski 在他的 2025 年 7 月 tool-calling 文章中記錄了一個案例（原始報告已連結）：使用者要求 Excel 中的 Copilot 操作第 4 列，agent 卻操作了第 8 列。錯誤的列與寫入操作之間沒有任何確認閘門。修法是 AWS 為 Bedrock Agents 記錄的模式：agent 準備操作、回傳以待核准、只在人工確認後才執行。Cursor 對檔案編輯也是這麼做的。在只需讀取的任務中將憑證範圍設為唯讀，並將確認閘門視為注入攻擊面的一部分，這個主題在我們的prompt injection 防禦指南中有完整討論。

實務 8：每次工具變更都跑評估迴圈

在每次工具變更前後跑一個小型評估套件，並按固定順序閱讀指標。Paragon 的優化指南提出了一個值得採用的四指標框架：

Anthropic 的工具評估 cookbook建立在真實的 Slack 和 Asana MCP 評估之上，展示了好的和壞的評估任務長什麼樣：

# Weak: vague, many valid paths, impossible to score
"Use the Asana tools to organize some work."

# Strong: one correct tool, checkable arguments, binary outcome
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

我們的解讀（明確標示為我們的觀點）：已發表的數字告訴你工作的順序。先檢查工具正確性，因為 Anthropic 自己的量測顯示描述和命名變更會直接影響它（206 到 72 token 的改寫、UUID 轉名稱的幻覺發現），把任務效率留到最後，因為它主要反映前三個指標已經抓到的失敗。入門套件設計 15-30 個任務，每個工具兩到三個，每個任務有一個預期呼叫和一個二元通過條件。這個規模足以抓到描述改寫帶來的回歸，而不需要花一週標註，我們將 cookbook 的 Slack 和 Asana 設定解讀為證據：這麼小的套件就是預設起點，而非捷徑。更深的機制在我們的生產環境 AI agent 評估指南中，如果你的評估結果顯示工具本身沒問題但編排有問題，那就是重新审视框架選擇的時機，參見最佳 AI agent 框架。

Agent tool calling 與 MCP 的差異

MCP 是傳輸與註冊標準，不是可靠性層，因此無論你的工具透過 MCP 送達還是內聯定義，同樣八項實務都適用。原生 tool calling 是模型供應商合約：模型如何發出 tool_call 並讀取 tool_result。MCP 標準化工具如何送達模型；它對模型是否選對工具毫無作為。

一個暴露名為 search、描述為 "searches things" 的工具的 MCP server，其失敗方式與以同樣方式定義的內聯函式完全相同。先修定義，再擔心傳輸。我們的 Model Context Protocol 指南從頭到尾涵蓋了協定面。

Techsy 如何套用這八項實務

在每個客戶 agent 建置中，我們在其他東西上線之前先強制執行其中三項：描述寫成指令（實務 1）、每個寫入工具設驗證閘門（實務 6）、評估套件在部署前跑而非事故後跑（實務 8）。這三項涵蓋了選錯工具、參數錯誤，以及重新引入兩者的回歸，而我們偵錯過的每個生產環境 agent 事故都從這裡開始。其餘五項隨 agent 成長而加入。如果你的 agent 已過 demo 階段卻仍在選錯工具，預約免費諮詢，我們會告訴你八項中該先修哪一項。

關於作者

Mert Batur 是 Techsy.io 的共同創辦人，團隊為 B2B 客戶交付 AI agent、自動化系統與語音/SDR 管線。他撰寫 Techsy 團隊在生產環境實際使用的 LLM 工具堆疊。在 LinkedIn 上聯繫。

常見問題

什麼是 agent tool calling？

Agent tool calling 是 LLM 決定呼叫外部函式的機制：它發出一個結構化的 tool_call，等待你的程式碼回傳一個它能據以推理的 tool_result。這就是把聊天模型變成能查詢資料庫、呼叫 API、採取行動的 agent 的關鍵：模型選擇工具和參數，你的執行器負責執行。

Agent tool calling 迴圈如何運作？

迴圈有五個步驟：使用者請求送達模型、模型選擇工具並撰寫 tool_call、你的執行器執行它、tool_result 回傳給模型、模型回答或發出另一次呼叫。這個循環重複直到任務完成。本指南中的四種失敗模式各存在於此迴圈的特定步驟。

為什麼我的 agent 會選錯工具？

通常是因為兩個工具重疊，而它們的描述沒有說明誰是誰。模型僅根據名稱和描述做選擇，所以 "gets a user" 和 "finds users" 讀起來可以互換。修法：加上排除行（「do NOT use to search」）、命名空間名稱、減少 context 中的工具數量。Kubaski 的四模型測試顯示，即使是強模型也會在模糊的清單上路由錯誤。

如何強制 tool calling agent 結構化其輸出？

約束 schema，而非 prompt。對有固定值的欄位用 enum，對任務需要的任何東西用 required 陣列，用扁平物件取代巢狀物件。對最終回答（而非工具呼叫），OpenAI 的 structured outputs 和 Anthropic 的 tool-choice 模式等供應商功能可強制特定形狀。我們的結構化輸出指南涵蓋了兩條路徑並附程式碼。

Agent tool calling 與 MCP 的差異是什麼？

原生 tool calling 是你的程式碼與單一模型供應商之間的合約：tool_call 和 tool_result 的訊息格式。MCP 是一個協定層，標準化工具如何被發現並送達任何相容的客戶端。MCP 改變的是管線，而非可靠性。描述不良的工具無論走哪條路徑都會以同樣方式失敗，我們的 Model Context Protocol 指南有詳細說明。

LLM agent 的工具數量多少算太多？

把每個 agent 5-10 個工具當作工作範圍，而非鐵律。選擇準確度隨可見清單增長而下降，尤其當名稱或描述重疊時。解法不是更大的模型，而是過濾：只載入目前任務需要的子集，使用 planner-worker 分割。為所有東西加上命名空間，讓兩個整合永遠不會同時暴露一個裸的 search。

Tool calling 的最佳模型是什麼？

沒有單一答案，而這個領域已發表的基準測試老化很快。OpenAI、Anthropic 和 Google 的前沿模型都能通過基本工具使用任務，而搭配良好設計工具的較小模型，往往能以極低的 token 成本達到幾乎相同的任務完成率。建立實務 8 的 15-30 個任務評估套件，用你自己的工具測試候選模型。

如何降低 tool calling 的 token 成本？

削減回傳內容。回傳精簡、高訊號的結果，而非原始 API payload：Anthropic 記錄了一個 response_format 變更帶來 206 到 72 token 的削減。將 UUID 解析為名稱、丟掉模型從不使用的欄位，並記住每個工具結果在後續每個回合都會重新進入 context window。透過原子化工具減少呼叫次數，能從帳單中移除整個結果。

如何評估 tool calling 品質？

按順序評分四個指標：工具正確性（選對工具？）、輸入準確性（參數有效？）、任務完成率（目標達成？）、任務效率（token 與呼叫次數？）。撰寫 15-30 個任務，每個預期一個特定呼叫、可檢查的參數和一個二元通過條件。在每次工具變更前後都跑套件，讓描述改寫永遠不會在未量測的情況下上線。

結論

先診斷，再優化。你的 agent 選錯工具只有四種原因，而上述八項實務中的三項（描述、扁平 schema、過濾）能修正驅動多數生產環境事故的選擇失敗。從這裡開始，因為它們只需一個下午，而且它們是這個問題之所以可修的原因。保持驗證錯誤的資訊量、為任何破壞性操作設人工閘門、每次變更都跑評估迴圈，讓你在換模型之前先量測。選錯工具不是模型問題，而是工具設計問題，而設計掌握在你手中。