ツールの定義



前提条件

• ツール使用の概要に精通していること
• Claude APIキーと動作するSDKまたはcURLのセットアップ



モデルの選択

複雑なツールや曖昧なクエリには最新の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）。これにより、ライブラリが成長してもツールの選択が明確になり、ツール検索を使用する場合に特に重要です。
• 高シグナルな情報のみを返すようにツールのレスポンスを設計する。 不透明な内部参照ではなく、意味的で安定した識別子（例：スラッグやUUID）を返し、Claudeが次のステップを推論するために必要なフィールドのみを含めます。肥大化したレスポンスはコンテキストを浪費し、Claudeが重要な情報を抽出するのを難しくします。

良い説明は、ツールが何をするか、いつ使用するか、どのようなデータを返すか、tickerパラメータが何を意味するかを明確に説明しています。不十分な説明は短すぎて、ツールの動作と使用法について多くの疑問をClaudeに残します。



ツール使用の例の提供

有効なツール入力の具体的な例を提供することで、Claudeがツールをより効果的に使用する方法を理解するのに役立ちます。これは、ネストされたオブジェクト、オプションのパラメータ、またはフォーマットに敏感な入力を持つ複雑なツールに特に有用です。



基本的な使用方法

ツール定義にオプションのinput_examplesフィールドを追加し、入力オブジェクトの例の配列を指定します。各例はツールのinput_schemaに従って有効である必要があります：

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フィールドでツールを指定することで実現できます。ハイライトされた行が、標準的なツール使用リクエストとの唯一の違いです：

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



次のステップ