ツール呼び出しの処理

tool_use ブロックの解析、tool_result レスポンスのフォーマット、is_error によるエラー処理について説明します。

このページでは、ツール呼び出しのライフサイクルについて説明します。Claudeのレスポンスから tool_use ブロックを読み取り、返信で tool_result ブロックをフォーマットし、エラーを通知する方法です。これを自動的に処理するSDKの抽象化については、Tool Runnerを参照してください。

Claudeのレスポンスは、クライアントツールとサーバーツールのどちらを使用するかによって異なります。

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

レスポンスの stop_reason は tool_use となり、以下を含む1つ以上の tool_use コンテンツブロックが含まれます。

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

computer useまたはbrowser useツールセットのメンバーに対する tool_use ブロックには、toolset_name フィールド（"computer" または "browser"）も含まれます。その name は、screenshot や navigate など、Claudeが呼び出しているメンバーツールであるため、これらのブロックは両方のフィールドに基づいてディスパッチしてください。

JSON

{
  "id": "msg_01Aq9w938a90dw8q",
  "model": "claude-opus-5-5",
  "stop_reason": "tool_use",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll check the current weather in San Francisco for you."
    },
    {
      "type": "tool_use",
      "id": "toolu_01A09q90qw90lq917835lq9",
      "name": "get_weather",
      "input": { "location": "San Francisco, CA", "unit": "celsius" }
    }
  ]
}

クライアントツールに対するツール使用レスポンスを受け取ったら、次のようにします。

tool_use ブロックから name、id、input を抽出します。
そのツール名に対応するコードベース内の実際のツールを、ツールの input を渡して実行します。
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、または search_result タイプを使用できます。
- is_error（オプション）：ツールの実行がエラーになった場合は true に設定します。

computer useまたはbrowser useのメンバーブロックに応答する tool_result は、tool_use ブロックと同じ toolset_name の値もそのまま返す必要があります。これを省略したメンバー結果は拒否されます。また、その content はより限定されています。メンバー結果には text ブロックと image ブロックのみを含めることができ、browser useの結果には1つの browser_state ブロックを追加できます（タブ管理メンバーはそのブロックのみを返します）。

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

ツール結果ブロックは、メッセージ履歴内で対応するツール使用ブロックの直後に配置する必要があります。アシスタントのツール使用メッセージとユーザーのツール結果メッセージの間に、他のメッセージを含めることはできません。
ツール結果を含むユーザーメッセージでは、tool_result ブロックを content 配列の最初に配置する必要があります。テキストはすべてのツール結果の後に配置する必要があります。
アシスタントのターンで、まだ結果ブロックのないサーバーツールも呼び出された場合、ユーザーメッセージには tool_result ブロックのみを含める必要があります。結果の後にテキストがあるとターンが早期に終了します。Claudeが直接呼び出したサーバーツールの場合、リクエストは未解決のサーバーツールの名前を示す400エラーで失敗します。停止理由とフォールバックを参照してください。

たとえば、次の場合は400エラーが発生します。

{
  "role": "user",
  "content": [
    { "type": "text", "text": "Here are the results:" }, // ❌ Text before tool_result
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ }
  ]
}

アシスタントのターンがクライアントツールのみを呼び出す場合、次の形式が正しいです。

{
  "role": "user",
  "content": [
    { "type": "tool_result", "tool_use_id": "toolu_01" /* ... */ },
    { "type": "text", "text": "What should I do next?" } // ✅ Text after tool_result
  ]
}

「tool_use ids were found without tool_result blocks immediately after」のようなエラーを受け取った場合は、ツール結果が正しくフォーマットされているか確認してください。

ツール結果には、Webページ、受信メール、ユーザーのアップロード、サードパーティAPIなど、制御できないソースからのコンテンツが含まれることがよくあります。そのようなコンテンツは信頼できないものとして扱ってください。それに影響を与えられる攻撃者は、Claudeを誘導しようとする指示を埋め込む可能性があります（間接的プロンプトインジェクション）。信頼できないコンテンツは、system プロンプトやプレーンなユーザー text ブロックではなく tool_result ブロック内に保持し、さらなる強化策についてはジェイルブレイクとプロンプトインジェクションの軽減を参照してください。

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "15 degrees" },
        {
          "type": "image",
          "source": {
            "type": "base64",
            "media_type": "image/jpeg",
            "data": "/9j/4AAQSkZJRg..."
          }
        }
      ]
    }
  ]
}

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": [
        { "type": "text", "text": "The weather is" },
        {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "15 degrees"
          }
        }
      ]
    }
  ]
}

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

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

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

is_error によるエラー処理

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

ツール自体が実行中にエラーをスローした場合（たとえば、天気データの取得時のネットワークエラー）、"is_error": true とともにエラーメッセージを content で返すことができます。

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "ConnectionError: the weather service API is not available (HTTP 500)",
      "is_error": true
    }
  ]
}

Claudeはこのエラーをユーザーへのレスポンスに組み込みます。たとえば、「申し訳ありませんが、天気サービスAPIが利用できないため、現在の天気を取得できませんでした。後でもう一度お試しください。」のようになります。

Claudeによるツール使用の試みが無効な場合（たとえば、必須パラメータの欠落）、通常はClaudeがツールを正しく使用するための情報が不足していたことを意味します。開発中の最善の方法は、ツール定義の description の値をより詳細にしてリクエストを再試行することです。

ただし、エラーを示す tool_result で会話を先に進めることもでき、Claudeは不足している情報を補ってツールを再度使用しようとします。

JSON

{
  "role": "user",
  "content": [
    {
      "type": "tool_result",
      "tool_use_id": "toolu_01A09q90qw90lq917835lq9",
      "content": "Error: Missing required 'location' parameter",
      "is_error": true
    }
  ]
}

ツールリクエストが無効であるかパラメータが不足している場合、Claudeはユーザーに謝罪する前に、修正を加えて2〜3回再試行します。

次のステップ

並列ツール使用

Claudeが1回のターンで複数のツールを呼び出すレスポンスを処理します。

Tool Runner（SDK）

tool_use ループ、結果のフォーマット、再試行をSDKに任せます。

ツールの定義

Claudeを適切なツールへ導くスキーマと説明を記述します。

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

`tool_use` コンテンツブロックを含むAPIレスポンスの例

成功したツール結果の例

画像を含むツール結果の例

空のツール結果の例

ドキュメントを含むツール結果の例

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

is_error によるエラー処理

ツール実行エラー

無効なツール名

サーバーツールのエラー

次のステップ

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

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

is_error によるエラー処理

次のステップ