定義工具

選擇模型

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

對於直接的工具，請使用 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 有效：

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 架構的客戶端工具，但不適用於伺服器工具，如網路搜尋或程式碼執行
• 令牌成本 - 範例增加提示令牌：簡單範例約 20-50 個令牌，複雜嵌套物件約 100-200 個令牌

控制 Claude 的輸出

強制工具使用

在某些情況下，您可能希望 Claude 使用特定工具來回答使用者的問題，即使 Claude 在沒有呼叫工具的情況下會直接回答。您可以通過在 tool_choice 欄位中指定工具來執行此操作，如下所示：

tool_choice = {"type": "tool", "name": "get_weather"}

使用 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 通常會在呼叫工具之前評論它正在做什麼或自然地回應使用者。

例如，給定提示「San Francisco 現在的天氣如何，那裡現在幾點？」，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 在解釋其操作時可能使用各種措辭和方法。您的程式碼應該像對待任何其他助手生成的文字一樣對待這些回應，並且不應依賴特定的格式化慣例。

後續步驟