ツールの定義



モデルの選択

複雑なツールや曖昧なクエリには、最新の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に提供できるコンテキストが多いほど、Claudeはいつどのようにツールを使用するかをより適切に判断できます。ツールの説明ごとに少なくとも3〜4文を目指し、ツールが複雑な場合はそれ以上記述してください。
• 説明を優先しつつ、複雑なツールにはinput_examplesの使用を検討する。 明確な説明が最も重要ですが、複雑な入力、ネストされたオブジェクト、または形式に敏感なパラメータを持つツールの場合は、input_examplesフィールドを使用してスキーマ検証済みの例を提供できます。詳細については、ツール使用の例の提供を参照してください。
• 関連する操作をより少ないツールに統合する。 すべてのアクションに対して個別のツール（create_pr、review_pr、merge_pr）を作成するのではなく、actionパラメータを持つ単一のツールにグループ化します。より少なく、より高機能なツールは選択の曖昧さを減らし、Claudeがツール群を扱いやすくします。
• ツール名に意味のある名前空間を使用する。 ツールが複数のサービスやリソースにまたがる場合は、名前にサービスのプレフィックスを付けます（例：github_list_prs、slack_send_message）。これにより、ツールライブラリが拡大してもツール選択が明確になり、ツール検索を使用する場合に特に重要です。
• 重要な情報のみを返すようにツールレスポンスを設計する。 不透明な内部参照ではなく、意味のある安定した識別子（スラッグや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スキーマのクライアントツールで機能しますが、ウェブ検索やコード実行などのサーバーツールでは機能しません
• トークンコスト - 例はプロンプトトークンに追加されます。シンプルな例で約20〜50トークン、複雑なネストされたオブジェクトで約100〜200トークンです



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パラメータを使用する場合、4つのオプションがあります。

• 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は、自分のアクションを説明する際にさまざまな表現やアプローチを使用する可能性があることに注意してください。コードでは、これらの応答を他のアシスタント生成テキストと同様に扱い、特定のフォーマット規則に依存しないようにしてください。



次のステップ