ツールを定義する

前提条件

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

クライアントツールの指定

クライアントツールは、APIリクエストのトップレベルパラメータ tools で指定します。bashツールやテキストエディタツールなどのAnthropicスキーマのクライアントツールは、日付でバージョン管理された type によって宣言されます。各ツールが受け付けるフィールドについては、ツールリファレンスからリンクされている各ツールのページを参照してください。コンピュータ使用ツールとブラウザ使用ツールはクライアントツールセットです。これは name を持たない単一のエントリで、固定されたメンバーツールのセットを宣言します。ユーザー定義のツール定義には以下が含まれます。

cache_control、strict、defer_loading、allowed_callers など、単一のツール定義で利用可能なオプションプロパティの完全なセットについては、ツールリファレンスを参照してください。クライアントツールセットのエントリは、エントリに対して cache_control と allowed_callers を受け付け、メンバーごとに defer_loading を設定します。クライアントツールセットを参照してください。

{
  "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, either 'celsius' or 'fahrenheit'"
      }
    },
    "required": ["location"]
  }
}

ツール使用のシステムプロンプト

tools パラメータを指定してClaude APIを呼び出すと、APIはツール定義、ツール設定、およびユーザーが指定した「system prompt」（システムプロンプト）から特別なシステムプロンプトを構築します。構築されたプロンプトは、指定されたツールを使用するようモデルに指示し、ツールが適切に動作するために必要なコンテキストを提供するように設計されています。

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が重要な情報を抽出するのを難しくします。

{
  "name": "get_stock_price",
  "description": "Retrieves the current stock price for a given ticker symbol. The ticker symbol must be a valid symbol for a publicly traded company on a major US stock exchange like NYSE or NASDAQ. The tool will return the latest trade price in USD. It should be used when the user asks about the current or most recent price of a specific stock. It will not provide any other information about the stock or company.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string",
        "description": "The stock ticker symbol, e.g. AAPL for Apple Inc."
      }
    },
    "required": ["ticker"]
  }
}

{
  "name": "get_stock_price",
  "description": "Gets the stock price for a ticker.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticker": {
        "type": "string"
      }
    },
    "required": ["ticker"]
  }
}

良い説明は、ツールが何をするか、いつ使用するか、どのようなデータを返すか、そして ticker パラメータが何を意味するかを明確に説明しています。悪い説明は簡潔すぎて、ツールの動作や使い方についてClaudeに多くの疑問を残してしまいます。

ツール使用例の提供

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

基本的な使い方

ツール定義にオプションの input_examples フィールドを追加し、入力オブジェクトの例の配列を指定します。各例はツールの input_schema に従って有効でなければなりません。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    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": "any"} と tool_choice: {"type": "tool", "name": "..."} は失敗しますが、tool_choice: {"type": "auto"}（デフォルト）と tool_choice: {"type": "none"} は引き続き機能します。

サポートしているモデルでは、ハイライトされた行が標準的なツール使用リクエストとの唯一の違いです。

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

次のステップ