定義工具



先決條件

• 熟悉工具使用概觀
• Claude API 金鑰以及可運作的 SDK 或 cURL 設定



選擇模型

對於複雜的工具和模糊的查詢，請使用最新的 Claude Opus 模型 Claude Opus 5；它能更好地處理多個工具，並在需要時尋求澄清。

對於簡單直接的工具，請使用 Claude Haiku 模型，但請注意它們可能會推斷缺少的參數。



指定客戶端工具

客戶端工具（包括 Anthropic 結構描述和使用者定義的工具）在 API 請求的 tools 頂層參數中指定。每個工具定義包括：

有關任何工具定義上可用的完整選用屬性集，包括 cache_control、strict、defer_loading 和 allowed_callers，請參閱工具參考。



工具使用系統提示

當您使用 tools 參數呼叫 Claude API 時，API 會根據工具定義、工具配置和任何使用者指定的系統提示建構一個特殊的系統提示。建構的提示旨在指示模型使用指定的工具，並提供工具正常運作所需的上下文：

In this environment you have access to a set of tools you can use to answer the user's question.
{{ FORMATTING INSTRUCTIONS }}
String and scalar parameters should be specified as is, while lists and objects should use JSON format. Note that spaces for string values are not stripped. The output is not expected to be valid XML and is parsed with regular expressions.
Here are the functions available in JSONSchema format:
{{ TOOL DEFINITIONS IN JSON SCHEMA }}
{{ USER SYSTEM PROMPT }}
{{ TOOL CONFIGURATION }}



工具定義的最佳實踐

為了在使用工具時讓 Claude 發揮最佳效能，請遵循以下準則：

• 提供極其詳細的描述。 這是影響工具效能最重要的因素。您的描述應該解釋工具的每個細節，包括：
  • 工具的功能
  • 何時應該使用它（以及何時不應該使用）
  • 每個參數的含義以及它如何影響工具的行為
  • 任何重要的注意事項或限制，例如如果工具名稱不清楚，工具不會回傳哪些資訊。您能提供給 Claude 關於工具的上下文越多，它在決定何時以及如何使用這些工具時就會表現得越好。每個工具描述至少要有 3–4 個句子，如果工具較複雜則需要更多。
• 優先考慮描述，但對於複雜的工具可考慮使用 input_examples。 清晰的描述最為重要，但對於具有複雜輸入、巢狀物件或格式敏感參數的工具，您可以使用 input_examples 欄位提供經過結構描述驗證的範例。詳情請參閱提供工具使用範例。
• 將相關操作整合到較少的工具中。 與其為每個動作建立單獨的工具（create_pr、review_pr、merge_pr），不如將它們組合成一個帶有 action 參數的單一工具。更少但功能更強大的工具可以減少選擇的模糊性，並使 Claude 更容易瀏覽您的工具介面。
• 在工具名稱中使用有意義的命名空間。 當您的工具跨越多個服務或資源時，請在名稱前加上服務前綴（例如 github_list_prs、slack_send_message）。這使得工具選擇在您的工具庫增長時不會產生歧義，在使用工具搜尋時尤其重要。
• 設計工具回應以僅回傳高訊號資訊。 回傳語義化、穩定的識別碼（例如 slug 或 UUID），而不是不透明的內部參照，並且只包含 Claude 推理下一步所需的欄位。臃腫的回應會浪費上下文，並使 Claude 更難提取重要資訊。

良好的描述清楚地解釋了工具的功能、何時使用它、它回傳什麼資料，以及 ticker 參數的含義。不良的描述過於簡短，讓 Claude 對工具的行為和用法留下許多疑問。



提供工具使用範例

您可以提供有效工具輸入的具體範例，幫助 Claude 理解如何更有效地使用您的工具。這對於具有巢狀物件、選用參數或格式敏感輸入的複雜工具特別有用。



基本用法

在您的工具定義中新增一個選用的 input_examples 欄位，其中包含一組範例輸入物件的陣列。每個範例都必須符合工具的 input_schema：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "The unit of temperature",
                    },
                },
                "required": ["location"],
            },
            "input_examples": [
                {"location": "San Francisco, CA", "unit": "fahrenheit"},
                {"location": "Tokyo, Japan", "unit": "celsius"},
                {
                    "location": "New York, NY"  # 'unit' is optional
                },
            ],
        }
    ],
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

範例會與您的工具結構描述一起包含在提示中，向 Claude 展示格式正確的工具呼叫的具體模式。這有助於 Claude 理解何時包含選用參數、使用什麼格式，以及如何建構複雜的輸入。



要求與限制

• 結構描述驗證 - 每個範例都必須符合工具的 input_schema。無效的範例會回傳 400 錯誤
• 不支援伺服器端工具 - 輸入範例適用於使用者定義和 Anthropic 結構描述的客戶端工具，但不適用於伺服器工具，例如網頁搜尋或程式碼執行
• Token 成本 - 範例會增加提示 token 數：簡單範例約 20–50 個 token，複雜的巢狀物件約 100–200 個 token



控制 Claude 的輸出



強制工具使用

在某些情況下，您可能希望 Claude 使用特定工具來回答使用者的問題，即使 Claude 原本會直接回答而不呼叫工具。您可以透過在請求的 tool_choice 欄位中指定工具來做到這一點。突出顯示的行是與標準工具使用請求的唯一區別：

client = anthropic.Anthropic()

tools = [
    {
        "name": "get_weather",
        "description": "Get the current weather in a given location",
        "input_schema": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "The city and state, e.g. San Francisco, CA",
                }
            },
            "required": ["location"],
        },
    }
]

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "tool", "name": "get_weather"},
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
)

print(response)

使用 tool_choice 參數時，有四個可能的選項：

• auto 允許 Claude 決定是否呼叫任何提供的工具。當提供 tools 時，這是預設值。
• any 告訴 Claude 必須使用提供的工具之一，但不強制使用特定工具。
• tool 強制 Claude 始終使用特定工具。
• none 防止 Claude 使用任何工具。當未提供 tools 時，這是預設值。

此圖表說明了每個選項的運作方式：

請注意，當您將 tool_choice 設為 any 或 tool 時，API 會預先填入助理訊息以強制使用工具。這意味著模型不會在 tool_use 內容區塊之前發出自然語言回應或解釋，即使明確要求這樣做也是如此。

測試顯示這不應該降低效能。如果您希望模型在仍然要求使用特定工具的同時提供自然語言上下文或解釋，您可以將 tool_choice 設為 {"type": "auto"}（預設值），並在 user 訊息中新增明確的指示。例如：What's the weather like in London? Use the get_weather tool in your response.



使用工具時的模型回應

使用工具時，Claude 通常會在呼叫工具之前評論它正在做什麼，或自然地回應使用者。

例如，給定提示「What's the weather like in San Francisco right now, and what time is it there?」，Claude 可能會回應：

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll help you check the current weather and time in San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA" }
    }
  ]
}

這種自然的回應風格有助於使用者理解 Claude 正在做什麼，並創造更具對話性的互動。您可以透過系統提示以及在提示中提供 <examples> 來引導這些回應的風格和內容。

需要注意的是，Claude 在解釋其行動時可能會使用各種措辭和方式。您的程式碼應該像對待任何其他助理生成的文字一樣對待這些回應，而不要依賴特定的格式慣例。



後續步驟