​
モデルの選択

一般的に、複雑なツールや曖昧なクエリには Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5 または Claude Opus 3 を使用してください。これらは複数のツールをより適切に処理し、必要に応じて明確化を求めます。

単純なツールには Claude Haiku 3.5 または Claude Haiku 3 を使用しますが、不足しているパラメータを推測する可能性があることに注意してください。

Claude Sonnet 3.7 でツール使用と拡張思考を使用する場合は、詳細についてはこちらのガイドを参照してください。

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

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

パラメータ説明
nameツールの名前。正規表現 ^[a-zA-Z0-9_-]{1,64}$ に一致する必要があります。
descriptionツールの機能、使用タイミング、動作に関する詳細なプレーンテキストの説明。
input_schemaツールに必要なパラメータを定義するJSON Schemaオブジェクト。

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

toolsパラメータを指定してAnthropic 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文、複雑なツールの場合はそれ以上を目指してください。
  • 例よりも説明を優先する。 ツールの説明や付随するプロンプトにツールの使用例を含めることはできますが、これはツールの目的とパラメータに関する明確で包括的な説明を持つことよりも重要ではありません。説明を十分に詳細にした後にのみ例を追加してください。

良い説明では、ツールの機能、使用タイミング、返すデータ、およびtickerパラメータの意味が明確に説明されています。不十分な説明は簡潔すぎて、ツールの動作や使用法に関する多くの疑問をClaudeに残しています。

​
Claudeの出力の制御

​
ツール使用の強制

場合によっては、Claudeがツールを使わずに回答できると判断した場合でも、ユーザーの質問に答えるために特定のツールを使用させたいことがあります。これは、tool_choiceフィールドでツールを指定することで実現できます：

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

tool_choiceパラメータを使用する場合、4つの選択肢があります：

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

この図は各オプションの動作を示しています：

tool_choiceがanyまたはtoolの場合、ツールを使用するようにアシスタントメッセージを事前に入力することに注意してください。これは、明示的に求められた場合でも、モデルがtool_useコンテンツブロックの前に思考の連鎖textコンテンツブロックを出力しないことを意味します。

私たちのテストでは、これによってパフォーマンスが低下することはないはずです。特定のツールを使用するよう要求しながらも思考の連鎖（特にOpusの場合）を維持したい場合は、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 Opus 3モデルはtool_choiceがautoに設定されている場合にこれを行います（これはデフォルト値です。ツール使用の強制を参照）、SonnetとHaikuはプロンプトによってこれを行うよう促すことができます。

例えば、「What’s the weather like in San Francisco right now, and what time is it there?」というプロンプトに対して、Claudeは次のように応答するかもしれません：

JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "<thinking>この質問に答えるために、以下を行います：1. get_weatherツールを使用してサンフランシスコの現在の天気を取得します。2. get_timeツールを使用してAmerica/Los_Angelesタイムゾーン（サンフランシスコ、CAを含む）の現在の時刻を取得します。</thinking>"
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": {"location": "San Francisco, CA"}
    }
  ]
}

この思考の連鎖はClaudeの推論プロセスに洞察を与え、予期しない動作のデバッグに役立ちます。

Claude Sonnet 3モデルでは、思考の連鎖はデフォルトでは一般的ではありませんが、ユーザーメッセージやシステムプロンプトに"Before answering, explain your reasoning step-by-step in tags."のような内容を追加することで、Claudeに推論を示すよう促すことができます。

<thinking>タグはClaudeが思考の連鎖を示すために使用する一般的な規約ですが、正確な形式（このXMLタグの名前など）は時間とともに変化する可能性があることに注意することが重要です。コードは思考の連鎖を他のアシスタント生成テキストと同様に扱い、<thinking>タグの存在や特定の書式に依存すべきではありません。

​
並列ツール使用

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

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

Claude Sonnet 3.7での並列ツール使用

Claude Sonnet 3.7は、disable_parallel_tool_useを設定していない場合でも、レスポンスで並列ツール呼び出しを行う可能性が低いかもしれません。この問題を回避するために、トークン効率の良いツール使用を有効にすることをお勧めします。これにより、Claudeが並列ツールを使用するよう促すのに役立ちます。このベータ機能はレイテンシを削減し、出力トークンを平均14%節約します。

トークン効率の良いツール使用ベータにオプトインしたくない場合は、「バッチツール」を導入することもできます。これは他のツールへの呼び出しを同時にラップするメタツールとして機能します。このツールが存在する場合、モデルはそれを使用して複数のツールを同時に並列で呼び出すことがわかっています。

この回避策の使用方法については、クックブックのこの例を参照してください。

​
tool_useとtool_resultコンテンツブロックの処理

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

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

応答にはstop_reasonがtool_useとなり、以下を含む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"}]）として指定できます。これらのコンテンツブロックはtextまたはimageタイプを使用できます。
    • is_error（オプション）：ツールの実行がエラーになった場合はtrueに設定します。

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

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

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

他のAPIとの違い

ツール使用を分離したり、toolやfunctionのような特別な役割を使用する他のAPIとは異なり、AnthropicのAPIはツールをuserとassistantのメッセージ構造に直接統合します。

メッセージにはtext、image、tool_use、tool_resultブロックの配列が含まれます。userメッセージにはクライアントコンテンツとtool_resultが含まれ、assistantメッセージにはAI生成コンテンツとtool_useが含まれます。

​
pause_turn停止理由の処理

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

pause_turn停止理由の処理方法は次のとおりです：

import anthropic

client = anthropic.Anthropic()

# ウェブ検索を含む初期リクエスト
response = client.messages.create(
    model="claude-3-7-sonnet-latest",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "2025年の量子コンピューティングのブレークスルーに関する包括的な情報を検索してください"
        }
    ],
    tools=[{
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 10
    }]
)

# レスポンスにpause_turn停止理由があるかチェック
if response.stop_reason == "pause_turn":
    # 一時停止されたコンテンツで会話を続ける
    messages = [
        {"role": "user", "content": "2025年の量子コンピューティングのブレークスルーに関する包括的な情報を検索してください"},
        {"role": "assistant", "content": response.content}
    ]
    
    # 継続リクエストを送信
    continuation = client.messages.create(
        model="claude-3-7-sonnet-latest",
        max_tokens=1024,
        messages=messages,
        tools=[{
            "type": "web_search_20250305",
            "name": "web_search",
            "max_uses": 10
        }]
    )
    
    print(continuation)
else:
    print(response)

pause_turnを処理する際：

  • 会話を継続する：一時停止されたレスポンスをそのまま後続のリクエストに渡して、Claudeがターンを続行できるようにします
  • 必要に応じて修正する：会話を中断または方向転換したい場合は、継続する前にコンテンツを任意で修正できます
  • ツールの状態を保持する：機能を維持するために継続リクエストに同じツールを含めます

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

Claudeでツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります：