ツール使用の実装方法

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

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

ツール定義のベストプラクティス

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パラメータを使用する場合、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はツールを呼び出す前に、自分が何をしているかについてコメントしたり、ユーザーに自然に応答したりすることがよくあります。

例えば、「サンフランシスコの現在の天気はどうですか、そこの時刻は何ですか？」というプロンプトが与えられた場合、Claudeは以下のように応答する可能性があります：

この自然な応答スタイルは、ユーザーが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"}]）、またはドキュメントブロックのリスト（例："content": ["type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "15 degrees"}]）。これらのコンテンツブロックはtext、image、またはdocumentタイプを使用できます。
   • is_error（オプション）：ツール実行がエラーで終了した場合はtrueに設定します。

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

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

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

max_tokens停止理由の処理

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

pause_turn停止理由の処理

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

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

pause_turnを処理する場合：

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

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

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