建立 Claude 會選擇的工具

摘要逐字稿

當 Claude 選錯工具時，請先檢視工具的定義。這支影片以虛構的工程顧問公司 Meridian 為例。Meridian 重寫了其工具定義，並在重寫前後執行相同的 30 道測試問題。

本影片中的示範錄製於 2026 年 9 月，使用的是 Claude Sonnet 5（claude-sonnet-5）。結果在較新的模型上可能有所不同。

假設您的工具迴圈運作正常，然後發生了以下其中一種情況：

Claude 呼叫了錯誤的工具。
為了一個事實進行了三次工具呼叫。
傳入了 0142，但您的程式碼要的是 MEG-2026-0142。

Claude 永遠不會收到執行您工具的函式。它只會看到您傳送的定義，以及您回傳的結果。所以當 Claude 誤用工具時，請先檢查定義。

Meridian 有一個內部助理，供員工詢問關於專案、許可證和帳單的問題。重寫其工具定義後，在相同模型上，其在 30 道測試題中的分數從 14 分提升到 26 分。

Claude 看到的工具內容

工具定義是一段 JSON，用來告訴 Claude 某個工具的存在。 您會在每次請求的 tools 清單中傳送它。

以下是 Meridian 專案工具重寫後的定義，共有四個部分。

json

{
  "name": "lookup_project_status",
  "description": "Returns current facts about a single Meridian …",
  "input_schema": {
    "type": "object",
    "properties": {
      "project_id": {
        "type": "string",
        "description": "Full Meridian job number in the format MEG-YYYY-NNNN, e.g. MEG-2026-0142."
      },
      "fields": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["phase", "status", "lead", "hours", "deadline", "site", "client"]
        },
        "description": "Which fields to return. Omit to return everything."
      }
    },
    "required": ["project_id"]
  },
  "input_examples": [
    {"project_id": "MEG-2026-0142", "fields": ["phase", "status"]},
    {"project_id": "MEG-2025-0417", "fields": ["lead", "hours"]},
    {"project_id": "MEG-2024-0233"}
  ]
}

name 是 Claude 用來稱呼該工具的名稱。
description 是您撰寫、Claude 讀取的純文字。此處為節錄，完整內容會在下一節呈現。
input_schema 以 JSON Schema 列出工具的參數，每個參數都有名稱、類型及其各自的說明。required 指出哪些是必填項。
input_examples 為選填項目。它向 Claude 展示良好輸入範例的樣子，例如完整的工作編號。每個範例都必須符合 input_schema，否則 API 會回傳 400 錯誤。

Claude 透過閱讀使用者的請求以及每個工具的說明來決定是否進行工具呼叫。

撰寫詳盡的說明

在四個部分中，說明（description）的作用最大。

目標是至少三到四句話，如果工具較複雜則再多一些。涵蓋以下四點：

工具做什麼
何時使用，以及何時不使用
每個參數代表什麼意思
它不會回傳什麼

以下是 Meridian 的完整說明：

text

Returns current facts about a single Meridian project: phase,
schedule status, project lead, hours budgeted and consumed,
deadline, site city, and client. Use this only when the user asks
about a specific project by name or job number; if only a partial
number is given (e.g. 'the 0142 job'), normalize it to the full
MEG-YYYY-NNNN format before calling. Pass the fields parameter to
fetch just the fields the question needs instead of the whole
record. This tool does not return permit or invoicing information.
Use get_permit_status or get_billing_summary for those.

Meridian 的工具說明，依其涵蓋四項要素中的哪一項而以不同顏色標示每個段落。 — *Meridian 的說明涵蓋了一個好的說明應具備的全部四項要素。*

說明何時該使用該工具、何時不該使用，有助於 Claude 避免呼叫錯誤的工具。Meridian 的說明將此工具限定於關於單一專案的問題。對於許可證和帳單問題，則指名應使用的工具。

將重疊的工具合併為一個

當多個工具執行幾乎相同的工作時，再好的說明也幫不上太多忙。

Meridian 的第一組工具共有六個功能單薄的工具，每個都只有一行說明。其中四個各自回傳一項專案事實。這四個工具彼此重疊，導致 Claude 必須猜測某個問題需要哪一個。

解決方法是將這四個合併為一個工具 lookup_project_status，並加入一個 fields 參數來指定要回傳哪些事實。 另外兩個分別負責許可證和帳單，功能不同，因此保留不變。六個工具變成三個。

用評估來衡量變化

評估（eval）是一組固定的測試問題，附有已知的正確答案，針對 Claude 執行並評分。 它能顯示新的定義是否更好。

Meridian 的評估會檢查 Claude 是否呼叫了正確的工具。其中包含 30 道員工可能提出的問題，每道題都標註了正確的工具呼叫方式。Meridian 在 claude-sonnet-5 上執行了這 30 道問題兩次，分別使用兩組不同的工具。

工具組別	工具數量	分數
精簡型	6	14/30（47%）
整合型	3	26/30（87%）

只修正出問題的部分

要修正單一失敗案例，請找出定義中出問題的部分，只修改該部分，然後重新執行您的評估。

Claude 做錯了什麼	要修改的部分	該怎麼做
呼叫了錯誤的工具，或呼叫的工具數量超過問題所需	說明（description）	說明每個工具做什麼、何時該使用。合併彼此重疊的工具。
傳入了類型或格式錯誤的值	結構描述（schema）與範例	在該參數自身的 `description` 中說明格式。加入 `input_examples`。

工具使用疑難排解列出了更多症狀與修正方式。

重點整理

撰寫至少三到四句話的說明，並說明何時不該使用該工具。
將重疊的工具合併為一個帶有參數的工具。
用評估來衡量變化。
要修正單一失敗案例，只修改出問題的那個部分。

Claude 看到的工具內容

撰寫詳盡的說明

將重疊的工具合併為一個

用評估來衡量變化

只修正出問題的部分