定義工具



選擇模型

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

對於簡單的工具，請使用 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-8",
    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 欄位中指定工具來達成此目的。醒目標示的行是與標準工具使用請求的唯一差異：

import anthropic

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-4-8",
    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 通常會在呼叫工具之前說明它正在做什麼，或自然地回應使用者。

例如，給定提示「舊金山現在的天氣如何，那裡現在幾點？」，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 在解釋其動作時可能會使用各種措辭和方法。您的程式碼應將這些回應視為任何其他助理生成的文字，而不應依賴特定的格式慣例。



後續步驟