定义工具

选择模型

对于复杂的工具和模糊的查询，使用最新的 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）。这使得工具选择在您的库增长时变得明确，在使用工具搜索时尤其重要。
• 设计工具响应以仅返回高信号信息。 返回语义、稳定的标识符（例如，slugs 或 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 在解释其操作时可能会使用各种措辞和方法。您的代码应该像对待任何其他助手生成的文本一样对待这些响应，并且不应该依赖特定的格式约定。

后续步骤