​
モデルの選択

一般的に、複雑なツールや曖昧なクエリには 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を呼び出すと、ツール定義、ツール設定、およびユーザー指定のシステムプロンプトから特別なシステムプロンプトを構築します。構築されたプロンプトは、モデルに指定されたツールを使用し、ツールが適切に動作するために必要なコンテキストを提供するよう指示するように設計されています：

この環境では、ユーザーの質問に答えるために使用できるツールのセットにアクセスできます。
{{ フォーマット指示 }}
文字列とスカラーパラメータはそのまま指定し、リストとオブジェクトはJSON形式を使用してください。文字列値のスペースは削除されないことに注意してください。出力は有効なXMLである必要はなく、正規表現で解析されます。
JSONSchema形式で利用可能な関数は以下の通りです：
{{ JSON SCHEMA形式のツール定義 }}
{{ ユーザーシステムプロンプト }}
{{ ツール設定 }}

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

ツールを使用する際に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 パラメータの変更はキャッシュされたメッセージブロックを無効にします。ツール定義とシステムプロンプトはキャッシュされたままですが、メッセージコンテンツは再処理される必要があります。

この図は各オプションがどのように機能するかを示しています：

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

ツール使用で拡張思考を使用する場合、tool_choice: {"type": "any"} と tool_choice: {"type": "tool", "name": "..."} はサポートされておらず、エラーが発生します。拡張思考と互換性があるのは tool_choice: {"type": "auto"} （デフォルト）と tool_choice: {"type": "none"} のみです。

私たちのテストでは、これがパフォーマンスを低下させることはないことが示されています。（特にOpusで）思考の連鎖を維持しながら、モデルに特定のツールの使用を要求したい場合は、tool_choice に {"type": "auto"} （デフォルト）を使用し、user メッセージに明示的な指示を追加できます。例：ロンドンの天気はどうですか？回答でget_weatherツールを使用してください。

​
JSON出力

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

​
思考の連鎖

ツールを使用する際、Claudeはしばしば「思考の連鎖」、つまり問題を分解し、どのツールを使用するかを決定するために使用する段階的な推論を示します。Claude Opus 3 モデルは、tool_choice が auto に設定されている場合にこれを行います（これはデフォルト値です。ツール使用の強制を参照）。SonnetとHaikuはプロンプトでこれを行うよう促すことができます。

例えば、「今のサンフランシスコの天気はどうで、そこの時間は何時ですか？」というプロンプトに対して、Claudeは以下のように応答する場合があります：

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

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

Claude Sonnet 3 モデルでは、思考の連鎖はデフォルトではあまり一般的ではありませんが、ユーザーメッセージやシステムプロンプトに「答える前に、<thinking>タグで段階的に推論を説明してください。」のような内容を追加することで、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 4 モデルはデフォルトで優れた並列ツール使用機能を持っていますが、すべてのモデルで対象を絞ったプロンプトを使用して並列ツール実行の可能性を高めることができます：

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

Claude Sonnet 3.7は、disable_parallel_tool_use を設定していない場合でも、応答で並列ツール呼び出しを実行する可能性が低い場合があります。これを回避するために、トークン効率的ツール使用を有効にすることをお勧めします。これにより、Claudeが並列ツールを使用することが促進されます。このベータ機能は、レイテンシを削減し、出力トークンを平均14%節約します。

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

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

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

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

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

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

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

クライアントツールのツール使用応答を受信した場合、以下を行う必要があります：

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

重要なフォーマット要件:

  • ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に続く必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間にメッセージを含めることはできません。
  • ツール結果を含むユーザーメッセージでは、tool_resultブロックがコンテンツ配列の最初に来る必要があります。テキストはすべてのツール結果の後に来る必要があります。

例えば、これは400エラーを引き起こします：

{"role": "user", "content": [
  {"type": "text", "text": "結果は以下の通りです:"},  // ❌ tool_resultの前のテキスト
  {"type": "tool_result", "tool_use_id": "toolu_01", ...}
]}

これは正しいです：

{"role": "user", "content": [
  {"type": "tool_result", "tool_use_id": "toolu_01", ...},
  {"type": "text", "text": "次に何をすべきですか？"}  // ✅ tool_resultの後のテキスト
]}

「tool_use idsがtool_resultブロックの直後に見つからない」のようなエラーを受信した場合は、ツール結果が正しくフォーマットされていることを確認してください。

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

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

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

他のAPIとの違い

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

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

​
max_tokens 停止理由の処理

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

# ツール使用中に応答が切り捨てられたかチェック
if response.stop_reason == "max_tokens":
    # 最後のコンテンツブロックが不完全なtool_useかチェック
    last_block = response.content[-1]
    if last_block.type == "tool_use":
        # より高いmax_tokensでリクエストを送信
        response = client.messages.create(
            model="claude-opus-4-20250514",
            max_tokens=4096,  # 制限を増加
            messages=messages,
            tools=tools
        )

​
pause_turn 停止理由の処理

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

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でツールを使用する際に発生する可能性のあるエラーにはいくつかの種類があります：