ツール使用の実装方法

モデルの選択

複雑なツールと曖昧なクエリには、最新のClaude Sonnet (4.5)またはClaude Opus (4.1)モデルの使用をお勧めします。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。

シンプルなツールにはClaude Haikuモデルを使用できますが、欠落しているパラメータを推測する可能性があることに注意してください。

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

クライアントツール（Anthropic定義とユーザー定義の両方）は、APIリクエストのtoolsトップレベルパラメータで指定されます。各ツール定義には以下が含まれます：

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

toolsパラメータを使用してClaude 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フィールド（ベータ版）を使用してスキーマ検証済みの例を提供できます。詳細については、ツール使用例の提供を参照してください。

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

ツール使用例の提供

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

基本的な使用方法

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

例はツールスキーマと一緒にプロンプトに含まれており、Claudeに適切に形成されたツール呼び出しの具体的なパターンを示しています。これにより、Claudeはオプションパラメータをいつ含めるか、どのフォーマットを使用するか、複雑な入力をどのように構造化するかを理解するのに役立ちます。

要件と制限事項

• スキーマ検証 - 各例は、ツールのinput_schemaに従って有効である必要があります。無効な例は400エラーを返します
• サーバー側ツールではサポートされていません - ユーザー定義ツールのみが入力例を持つことができます
• トークンコスト - 例はプロンプトトークンに追加されます：シンプルな例の場合は約20～50トークン、複雑なネストされたオブジェクトの場合は約100～200トークン

ツールランナー（ベータ版）

ツールランナーは、Claudeでツールを実行するためのすぐに使用できるソリューションを提供します。ツール呼び出し、ツール結果、会話管理を手動で処理する代わりに、ツールランナーは自動的に以下を実行します：

• Claudeがツールを呼び出すときにツールを実行する
• リクエスト/レスポンスサイクルを処理する
• 会話状態を管理する
• タイプセーフティと検証を提供する

ほとんどのツール使用実装にはツールランナーの使用をお勧めします。

Claudeの出力の制御

ツール使用の強制

場合によっては、Claudeがツールを使用せずに答えを提供できると考えていても、特定のツールを使用してユーザーの質問に答えるようにClaudeに強制したい場合があります。これは、tool_choiceフィールドでツールを指定することで実行できます：

tool_choice = {"type": "tool", "name": "get_weather"}

tool_choiceパラメータを使用する場合、4つの可能なオプションがあります：

• autoはClaudeが提供されたツールを呼び出すかどうかを決定することを許可します。これはtoolsが提供されるときのデフォルト値です。
• anyはClaudeに提供されたツールの1つを使用する必要があることを伝えますが、特定のツールを強制しません。
• toolにより、特定のツールを常に使用するようにClaudeを強制できます。
• noneはClaudeがツールを使用することを防ぎます。これはtoolsが提供されないときのデフォルト値です。

このダイアグラムは、各オプションがどのように機能するかを示しています：

tool_choiceがanyまたはtoolの場合、ツールを強制的に使用するためにアシスタントメッセージをプリフィルすることに注意してください。これは、明示的に要求された場合でも、モデルがtool_useコンテンツブロックの前に自然言語応答または説明を発行しないことを意味します。

テストでは、これはパフォーマンスを低下させないことが示されています。モデルが特定のツールを使用するよう要求しながら、自然言語コンテキストまたは説明を提供したい場合は、tool_choiceに{"type": "auto"}（デフォルト）を使用し、userメッセージで明示的な指示を追加できます。例えば：What's the weather like in London? Use the get_weather tool in your response.

JSON出力

ツールは必ずしもクライアント関数である必要はありません。提供されたスキーマに従うJSON出力をモデルに返させたい場合はいつでもツールを使用できます。例えば、特定のスキーマを持つrecord_summaryツールを使用する場合があります。完全に機能する例については、Claudeでのツール使用を参照してください。

ツールを使用したモデルレスポンス

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

並列ツール使用

デフォルトでは、Claudeはユーザーのクエリに答えるために複数のツールを使用する場合があります。この動作は以下の方法で無効にできます：

• tool_choiceタイプがautoの場合にdisable_parallel_tool_use=trueを設定すると、Claudeは最大1つのツールを使用します
• tool_choiceタイプがanyまたはtoolの場合にdisable_parallel_tool_use=trueを設定すると、Claudeは正確に1つのツールを使用します

並列ツール使用を最大化する

Claude 4モデルはデフォルトで優れた並列ツール使用機能を備えていますが、ターゲットプロンプティングを使用してすべてのモデルで並列ツール実行の可能性を高めることができます：

ツール使用とツール結果コンテンツブロックの処理

Claudeの応答は、クライアントツールを使用するか、サーバーツールを使用するかによって異なります。

クライアントツールからの結果の処理

応答はtool_useのstop_reasonと、以下を含む1つ以上のtool_useコンテンツブロックを持ちます：

• id: この特定のツール使用ブロックの一意の識別子。これは後でツール結果と照合するために使用されます。
• name: 使用されているツールの名前。
• input: ツールのinput_schemaに準拠して、ツールに渡される入力を含むオブジェクト。

クライアントツールのツール使用応答を受け取ったときは、以下を実行する必要があります：

1. tool_useブロックからname、id、inputを抽出します。
2. ツール名に対応するコードベース内の実際のツールを実行し、ツールinputを渡します。
3. roleがuserの新しいメッセージを送信して会話を続行し、tool_resultタイプを含むcontentブロックと以下の情報を含めます：
   • tool_use_id: これが結果である、ツール使用リクエストのid。
   • content: ツールの結果。文字列（例："content": "15 degrees"）、ネストされたコンテンツブロックのリスト（例："content": [{"type": "text", "text": "15 degrees"}]）、またはドキュメントブロックのリスト（例：）。これらのコンテンツブロックは、、またはタイプを使用できます。

{"role": "user", "content": [
  {"type": "text", "text": "Here are the results:"},  // ❌ tool_resultの前のテキスト
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

ツール結果を受け取った後、Claudeはその情報を使用して元のユーザープロンプトへの応答を生成し続けます。

サーバーツールからの結果の処理

Claudeはツールを内部で実行し、追加のユーザー操作を必要とせずに結果を応答に直接組み込みます。

max_tokens停止理由の処理

Claudeの応答がmax_tokens制限に達したため切断された場合、切断された応答に不完全なツール使用ブロックが含まれている場合は、より高いmax_tokens値でリクエストを再試行して、完全なツール使用を取得する必要があります。

pause_turn停止理由の処理

Webサーチなどのサーバーツールを使用する場合、APIはpause_turn停止理由を返す場合があり、APIが長時間実行されるターンを一時停止したことを示します。

pause_turn停止理由を処理する方法は以下の通りです：

pause_turnを処理する場合：

• 会話を続行: 一時停止された応答を後続のリクエストでそのまま渡して、Claudeがターンを続行できるようにします
• 必要に応じて変更: 会話を中断またはリダイレクトしたい場合は、継続する前にコンテンツを変更することもできます
• ツール状態を保持: 継続リクエストに同じツールを含めて、機能を維持します

エラーのトラブルシューティング

Claudeでツールを使用する場合、いくつかの異なるタイプのエラーが発生する可能性があります：

これは正しいです：

「tool_use idsが見つかりましたが、その直後にtool_resultブロックがありません」というエラーが表示される場合は、ツール結果が正しくフォーマットされていることを確認してください。