---
title: ツール検索ツール
url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool
description: Claudeにツールカタログを検索させ、必要なツールだけを読み込ませることで、数百から数千のツールにスケールできます。
---

ツール検索ツール（tool search tool）を使用すると、Claudeはツールをオンデマンドで発見して読み込むことで、数百から数千のツールを扱えるようになります。すべてのツール定義を最初から「context window」（コンテキストウィンドウ）に読み込むのではなく、Claudeはツールカタログ（ツール名、説明、引数名、引数の説明を含む）を検索し、必要なツールだけを読み込みます。

すべてのツール定義を最初に読み込むと、ツールライブラリが大きくなるにつれて2つの問題が発生します。

* **コンテキストの肥大化：** 典型的なマルチサーバー構成（GitHub、Slack、Sentry、Grafana、Splunk）では、Claudeが何か作業を行う前に、定義だけで約55kトークンを消費することがあります。ツール検索は通常これを85パーセント以上削減し、特定のリクエストに対してClaudeが必要とする3〜5個のツールだけを読み込みます。
* **ツール選択の精度：** 利用可能なツールが30〜50個を超えると、Claudeが適切なツールを選ぶ能力は低下します。ツール検索は関連性の高いツールの絞り込まれたセットだけをオンデマンドで読み込むため、数千のツールがあっても選択精度は高く保たれます。

ツール検索をサポートするモデルについては、[モデルの互換性](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool#model-compatibility)を参照してください。

<Tip>
  ツール検索が解決するスケーリングの課題の背景については、[Advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)を参照してください。ツール検索のオンデマンド読み込みは、[Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)で説明されている、より広範なジャストインタイム検索の原則の一例でもあります。
</Tip>

ツール検索はサーバーサイドツールとして実行されますが、独自のクライアントサイドのツール検索を実装することもできます。詳細については、[カスタムツール検索の実装](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool#custom-tool-search-implementation)を参照してください。

<Note>
  この機能に関するフィードバックは、[フィードバックフォーム](https://forms.gle/MhcGFFwLxuwnWTkYA)からお寄せください。
</Note>

<Note>
  「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、[APIとデータ保持](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention)を参照してください。
</Note>

<Warning>
  Amazon Bedrockでは、サーバーサイドのツール検索は [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html) 経由でのみ利用可能であり、Converse APIでは利用できません。
</Warning>

<Note>
  [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)では、サーバーサイドのツール検索はClaude APIとまったく同じように動作します。Claude Platform on AWSはAnthropic Messages APIを直接使用するため、InvokeModelとConverseの区別はありません。
</Note>

## モデルの互換性

両方のツール検索バリアントは、以下のモデルで利用できます。

| モデル                                                                                                                        | ツールバージョン                                                            |
| -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Claude Fable 5.1 (claude-fable-5-1)                                                                                        | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5.1 (claude-mythos-5-1)                                                                                      | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Fable 5 (claude-fable-5)                                                                                            | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Mythos 5 (claude-mythos-5)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5.5 (claude-opus-5-5)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 5 (claude-opus-5)                                                                                              | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5.5 (claude-sonnet-5-5)                                                                                      | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 5 (claude-sonnet-5)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 5.5 (claude-haiku-5-5)                                                                                        | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.8 (claude-opus-4-8)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.7 (claude-opus-4-7)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.6 (claude-opus-4-6)                                                                                          | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.6 (claude-sonnet-4-6)                                                                                      | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Opus 4.5 (claude-opus-4-5-20251101)                                                                                 | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)（[非推奨](https://platform.claude.com/docs/ja/about-claude/model-deprecations)） | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |
| Claude Haiku 4.5 (claude-haiku-4-5-20251001)                                                                               | `tool_search_tool_regex_20251119`, `tool_search_tool_bm25_20251119` |

Claude Opus 4.1以前のモデルは、ツール検索ツールをサポートしていません。

## ツール検索の仕組み

ツール検索には2つのバリアントがあります。

* **Regex**（`tool_search_tool_regex_20251119`）：Claudeは正規表現パターンを構築してツールを検索します。
* **BM25**（`tool_search_tool_bm25_20251119`）：Claudeは自然言語クエリを使用してツールを検索します。

ツール検索ツールを有効にすると、次のように動作します。

1. `tools`リストにツール検索ツール（たとえば、`tool_search_tool_regex_20251119`または`tool_search_tool_bm25_20251119`）を含めます。
2. `tools`配列にすべてのツール定義を指定し、最初に読み込むべきでないツールには`defer_loading: true`を設定します。少なくとも1つのツール（通常はツール検索ツール自体）は非遅延のままにする必要があります。
3. 初期状態では、Claudeのコンテキストにはツール検索ツールと非遅延のツールのみが含まれます。
4. Claudeが追加のツールを必要とする場合、ツール検索ツールを使用して検索します。
5. APIが検索を実行し、一致するツールを`tool_reference`ブロックとして返します（デフォルトでは最大5件。Claudeは検索入力で`limit`を設定できます）。
6. APIはこれらの参照を完全なツール定義に自動的に展開します。
7. Claudeは発見されたツールの中から選択して呼び出します。

## クイックスタート

次の例には、ツール検索ツールと2つの遅延ツールが含まれています。

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
      -H "x-api-key: $ANTHROPIC_API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "content-type: application/json" \
      -d '{
          "model": "claude-opus-5-5",
          "max_tokens": 2048,
          "messages": [
              {
                  "role": "user",
                  "content": "What is the weather in San Francisco?"
              }
          ],
          "tools": [
              {
                  "type": "tool_search_tool_regex_20251119",
                  "name": "tool_search_tool_regex"
              },
              {
                  "name": "get_weather",
                  "description": "Get the weather at a specific location",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "location": {"type": "string"},
                          "unit": {
                              "type": "string",
                              "enum": ["celsius", "fahrenheit"]
                          }
                      },
                      "required": ["location"]
                  },
                  "defer_loading": true
              },
              {
                  "name": "search_files",
                  "description": "Search through files in the workspace",
                  "input_schema": {
                      "type": "object",
                      "properties": {
                          "query": {"type": "string"},
                          "file_types": {
                              "type": "array",
                              "items": {"type": "string"}
                          }
                      },
                      "required": ["query"]
                  },
                  "defer_loading": true
              }
          ]
      }'
  ```

  ```bash CLI
  ant messages create <<'YAML'
  model: claude-opus-5-5
  max_tokens: 2048
  messages:
    - role: user
      content: What is the weather in San Francisco?
  tools:
    - type: tool_search_tool_regex_20251119
      name: tool_search_tool_regex
    - name: get_weather
      description: Get the weather at a specific location
      input_schema:
        type: object
        properties:
          location:
            type: string
          unit:
            type: string
            enum: [celsius, fahrenheit]
        required: [location]
      defer_loading: true
    - name: search_files
      description: Search through files in the workspace
      input_schema:
        type: object
        properties:
          query:
            type: string
          file_types:
            type: array
            items:
              type: string
        required: [query]
      defer_loading: true
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-opus-5-5",
      max_tokens=2048,
      messages=[{"role": "user", "content": "What is the weather in San Francisco?"}],
      tools=[
          {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"},
          {
              "name": "get_weather",
              "description": "Get the weather at a specific location",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "location": {"type": "string"},
                      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                  },
                  "required": ["location"],
              },
              "defer_loading": True,
          },
          {
              "name": "search_files",
              "description": "Search through files in the workspace",
              "input_schema": {
                  "type": "object",
                  "properties": {
                      "query": {"type": "string"},
                      "file_types": {"type": "array", "items": {"type": "string"}},
                  },
                  "required": ["query"],
              },
              "defer_loading": True,
          },
      ],
  )

  print(response)
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-opus-5-5",
    max_tokens: 2048,
    messages: [
      {
        role: "user",
        content: "What is the weather in San Francisco?"
      }
    ],
    tools: [
      {
        type: "tool_search_tool_regex_20251119",
        name: "tool_search_tool_regex"
      },
      {
        name: "get_weather",
        description: "Get the weather at a specific location",
        input_schema: {
          type: "object" as const,
          properties: {
            location: { type: "string" },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"]
            }
          },
          required: ["location"]
        },
        defer_loading: true
      },
      {
        name: "search_files",
        description: "Search through files in the workspace",
        input_schema: {
          type: "object" as const,
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  });

  console.log(response);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeOpus5_5,
      MaxTokens = 2048,
      Messages = [
          new() {
              Role = Role.User,
              Content = "What is the weather in San Francisco?"
          }
      ],
      Tools = [
          new ToolUnion(new ToolSearchToolRegex20251119
          {
              Type = ToolSearchToolRegex20251119Type.ToolSearchToolRegex20251119
          }),
          new ToolUnion(new Tool()
          {
              Name = "get_weather",
              Description = "Get the weather at a specific location",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["location"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["unit"] = JsonSerializer.SerializeToElement(new { type = "string", @enum = new[] { "celsius", "fahrenheit" } }),
                  },
                  Required = ["location"],
              },
              DeferLoading = true,
          }),
          new ToolUnion(new Tool()
          {
              Name = "search_files",
              Description = "Search through files in the workspace",
              InputSchema = new InputSchema()
              {
                  Properties = new Dictionary<string, JsonElement>
                  {
                      ["query"] = JsonSerializer.SerializeToElement(new { type = "string" }),
                      ["file_types"] = JsonSerializer.SerializeToElement(new { type = "array", items = new { type = "string" } }),
                  },
                  Required = ["query"],
              },
              DeferLoading = true,
          }),
      ]
  };

  var message = await client.Messages.Create(parameters);
  Console.WriteLine(message);
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeOpus5_5,
  	MaxTokens: 2048,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in San Francisco?")),
  	},
  	Tools: []anthropic.ToolUnionParam{
  		{OfToolSearchToolRegex20251119: &anthropic.ToolSearchToolRegex20251119Param{
  			Type: anthropic.ToolSearchToolRegex20251119TypeToolSearchToolRegex20251119,
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "get_weather",
  			Description: anthropic.String("Get the weather at a specific location"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"location": map[string]any{"type": "string"},
  					"unit": map[string]any{
  						"type": "string",
  						"enum": []string{"celsius", "fahrenheit"},
  					},
  				},
  				Required: []string{"location"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  		{OfTool: &anthropic.ToolParam{
  			Name:        "search_files",
  			Description: anthropic.String("Search through files in the workspace"),
  			InputSchema: anthropic.ToolInputSchemaParam{
  				Properties: map[string]any{
  					"query":      map[string]any{"type": "string"},
  					"file_types": map[string]any{"type": "array", "items": map[string]any{"type": "string"}},
  				},
  				Required: []string{"query"},
  			},
  			DeferLoading: anthropic.Bool(true),
  		}},
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }
  fmt.Println(response.RawJSON())
  ```

  ```java Java
  import com.anthropic.models.messages.ToolSearchToolRegex20251119;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      InputSchema weatherSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "location", Map.of("type", "string"),
              "unit", Map.of(
                  "type", "string",
                  "enum", List.of("celsius", "fahrenheit")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("location")))
          .build();

      InputSchema searchSchema = InputSchema.builder()
          .properties(JsonValue.from(Map.of(
              "query", Map.of("type", "string"),
              "file_types", Map.of(
                  "type", "array",
                  "items", Map.of("type", "string")
              )
          )))
          .putAdditionalProperty("required", JsonValue.from(List.of("query")))
          .build();

      MessageCreateParams params = MessageCreateParams.builder()
          .model(Model.CLAUDE_OPUS_5_5)
          .maxTokens(2048L)
          .addUserMessage("What is the weather in San Francisco?")
          .addTool(ToolSearchToolRegex20251119.builder()
              .type(ToolSearchToolRegex20251119.Type.TOOL_SEARCH_TOOL_REGEX_20251119)
              .build())
          .addTool(Tool.builder()
              .name("get_weather")
              .description("Get the weather at a specific location")
              .inputSchema(weatherSchema)
              .deferLoading(true)
              .build())
          .addTool(Tool.builder()
              .name("search_files")
              .description("Search through files in the workspace")
              .inputSchema(searchSchema)
              .deferLoading(true)
              .build())
          .build();

      Message response = client.messages().create(params);
      IO.println(response);
  }
  ```

  ```php PHP
  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 2048,
      messages: [
          ['role' => 'user', 'content' => 'What is the weather in San Francisco?'],
      ],
      model: 'claude-opus-5-5',
      tools: [
          [
              'type' => 'tool_search_tool_regex_20251119',
              'name' => 'tool_search_tool_regex',
          ],
          [
              'name' => 'get_weather',
              'description' => 'Get the weather at a specific location',
              'input_schema' => [
                  'type' => 'object',
                  'properties' => [
                      'location' => ['type' => 'string'],
                      'unit' => [
                          'type' => 'string',
                          'enum' => ['celsius', 'fahrenheit'],
                      ],
                  ],
                  'required' => ['location'],
              ],
              'defer_loading' => true,
          ],
          [
              'name' => 'search_files',
              'description' => 'Search through files in the workspace',
              'input_schema' => [
                  'type' => 'object',
                  'properties' => [
                      'query' => ['type' => 'string'],
                      'file_types' => [
                          'type' => 'array',
                          'items' => ['type' => 'string'],
                      ],
                  ],
                  'required' => ['query'],
              ],
              'defer_loading' => true,
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: "claude-opus-5-5",
    max_tokens: 2048,
    messages: [
      { role: "user", content: "What is the weather in San Francisco?" }
    ],
    tools: [
      {
        type: "tool_search_tool_regex_20251119",
        name: "tool_search_tool_regex"
      },
      {
        name: "get_weather",
        description: "Get the weather at a specific location",
        input_schema: {
          type: "object",
          properties: {
            location: { type: "string" },
            unit: {
              type: "string",
              enum: ["celsius", "fahrenheit"]
            }
          },
          required: ["location"]
        },
        defer_loading: true
      },
      {
        name: "search_files",
        description: "Search through files in the workspace",
        input_schema: {
          type: "object",
          properties: {
            query: { type: "string" },
            file_types: {
              type: "array",
              items: { type: "string" }
            }
          },
          required: ["query"]
        },
        defer_loading: true
      }
    ]
  )

  puts message
  ```
</CodeGroup>

Claudeはカタログを検索し、`get_weather`を発見して呼び出します。レスポンスは`stop_reason: "tool_use"`で終了します。[ツール呼び出しの処理](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/handle-tool-calls)と同様に、発見されたツールを実行して`tool_result`を返してください。[レスポンス形式](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool#response-format)では、返されるブロックと次に送信すべき内容を示しています。

## ツール定義

ツール検索ツールには2つのバリアントがあります。

```json JSON
{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}
```

```json JSON
{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}
```

<Warning>
  **Regexバリアントのクエリ形式：自然言語ではなくPythonの正規表現**

  `tool_search_tool_regex_20251119`では、Claudeは自然言語クエリではなく、Pythonの`re.search()`パターンを記述します。マッチングは大文字と小文字を区別しません。一般的なパターンには次のようなものがあります。

  * `"weather"`：「weather」を含むツール名と説明に一致します
  * `"get_.*_data"`：`get_user_data`や`get_weather_data`などのツールに一致します
  * `"database.*query|query.*database"`：どちらの語順にも一致します

  パターンの最大長：200文字
</Warning>

<Note>
  **BM25バリアントのクエリ形式：自然言語**

  `tool_search_tool_bm25_20251119`では、Claudeは自然言語クエリで検索します。クエリの最大長：500文字。
</Note>

### 遅延ツール読み込み

`defer_loading: true`を追加して、ツールをオンデマンド読み込みの対象としてマークします。

```json JSON
{
  "name": "get_weather",
  "description": "Get current weather for a location",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "unit": { "type": "string", "enum": ["celsius", "fahrenheit"] }
    },
    "required": ["location"]
  },
  "defer_loading": true
}
```

`defer_loading`は、リクエストで何を送信するかではなく、何がコンテキストウィンドウに入るかを制御します。

* 遅延ツールを含め、すべてのツールの完全な定義を毎回のリクエストで`tools`配列に送信する必要があります。APIは検索を実行し、`tool_reference`ブロックを展開するために、サーバーサイドでそれらを必要とします。
* `defer_loading`のないツールは、すぐにコンテキストに読み込まれます。
* `defer_loading: true`のツールは、Claudeが検索を通じて発見した場合にのみ読み込まれます。
* ツール検索ツール自体には決して`defer_loading: true`を設定しないでください。
* 最も頻繁に使用する3〜5個のツールは非遅延のままにして、Claudeが最初に検索せずに呼び出せるようにしてください。

コンピュータ使用およびブラウザ使用のツールセット（`computer_toolset_20260801`および`browser_toolset_20260801`）は、エントリ自体ではなく、エントリの`configs`オブジェクト内でメンバーツールごとに`defer_loading`を受け取ります。エントリレベルで設定したリクエストは拒否されます。ツールセットは1つの単位として遅延および展開されるため、`defer_loading`は有効なすべてのメンバーで同じ値に解決される必要があり、Claudeが検索を通じてツールセットを発見すると、有効なすべてのメンバーが一度に読み込まれます。`configs`の形式については、[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)を参照してください。

両方のツール検索バリアント（`regex`と`bm25`）は、ツール名、説明、引数名、引数の説明を検索します。

内部的には、APIは遅延ツールをシステムプロンプトのプレフィックスから除外します。Claudeがツール検索を通じて遅延ツールを発見すると、APIは会話内にインラインで`tool_reference`ブロックを追加し、Claudeに渡す前にそれを完全なツール定義に展開します。プレフィックスは変更されないため、「prompt caching」（プロンプトキャッシング）は維持されます。[strictモード](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/strict-tool-use)の文法（ツール呼び出しの出力をスキーマに一致するよう制約するルール）は完全なツールセットから構築されるため、`defer_loading`とstrictモードは文法の再コンパイルなしで組み合わせることができます。

## レスポンス形式

Claudeがツール検索ツールを使用すると、レスポンスには次のブロックタイプが含まれます。

```json JSON
{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "I'll search for tools to help with the weather information."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01ABC123",
      "name": "tool_search_tool_regex",
      "input": {
        "pattern": "weather",
        "limit": 10
      }
    },
    {
      "type": "tool_search_tool_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": {
        "type": "tool_search_tool_search_result",
        "tool_references": [{ "type": "tool_reference", "tool_name": "get_weather" }]
      }
    },
    {
      "type": "text",
      "text": "I found a weather tool. Let me get the weather for San Francisco."
    },
    {
      "type": "tool_use",
      "id": "toolu_01XYZ789",
      "name": "get_weather",
      "input": { "location": "San Francisco", "unit": "fahrenheit" }
    }
  ],
  "stop_reason": "tool_use"
}
```

### レスポンスの理解

* **`server_tool_use`：** Claudeによるツール検索ツールの呼び出しです。検索はAnthropicのサーバー上で実行されます。その`srvtoolu_...` IDに対して`tool_result`を返さないでください。`input`には検索内容（regexバリアントの場合は`pattern`、BM25の場合は`query`）が含まれ、オプションの`limit`を含む場合があります。`limit`は1から10,000までの整数で、検索が返す一致ツールの数の上限を設定します（デフォルト：5）。
* **`tool_search_tool_result`：** ネストされた`tool_search_tool_search_result`オブジェクト内の検索結果です。メッセージ履歴にそのまま保持してください。
* **`tool_references`：** 発見されたツールを指す`tool_reference`オブジェクトの配列です。APIがClaudeのためにこれらを展開します。自分で展開することはありません。
* **`tool_use`：** Claudeによる発見されたツールの呼び出しです。標準のツール使用とまったく同じように、実行して`tool_result`を返してください。

APIは、Claudeに表示する前に`tool_reference`ブロックを完全なツール定義に自動的に展開します。一致するすべてのツール定義を`tools`パラメータで提供している限り、この展開を自分で処理する必要はありません。

### 会話の継続

次のリクエストでは、`server_tool_use`ブロックと`tool_search_tool_result`ブロックを含め、アシスタントのコンテンツを変更せずにそのまま渡します。発見されたツールに対する`tool_result`をユーザーメッセージに追加し、同じ`tools`配列（検索ツールとすべての遅延定義）を送信します。`srvtoolu_...` IDに対して`tool_result`を返さないでください。APIはそのリクエストを拒否します。APIは会話履歴全体で`tool_reference`ブロックを展開するため、Claudeは再検索せずに後のターンで発見済みのツールを再利用できます。何にも一致しない検索は、エラーではなく、空の`tool_references`配列を持つ`tool_search_tool_search_result`を返します。

## MCP統合

ツールが[MCPコネクタ](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector)を通じてMCPサーバーから提供される場合、個々のツール定義に`defer_loading`を設定しません。代わりに、サーバー全体に対して`mcp_toolset`エントリの`default_config`で一度設定するか、`configs`でツールごとに設定します。[MCPツールセットの設定](https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector#mcp-toolset-configuration)を参照してください。

## カスタムツール検索の実装

カスタムツールから`tool_reference`ブロックを返すことで、独自のツール検索ロジック（たとえば、埋め込みやセマンティック検索を使用）を実装できます。Claudeがカスタム検索ツールを呼び出したら、content配列に`tool_reference`ブロックを含む標準の`tool_result`を返します。

```json JSON
{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}
```

参照されるすべてのツールには、トップレベルの`tools`パラメータに対応するツール定義が必要であり、通常は`defer_loading: true`を設定します。これにより、埋め込みベースの検索など、組み込みバリアントが提供しない検索方法を使用でき、APIは返された`tool_reference`ブロックを同じ方法で展開します。

<Note>
  [レスポンス形式](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool#response-format)セクションに示されている`tool_search_tool_result`形式は、Anthropicの組み込みツール検索が内部的に使用するサーバーサイドの形式です。カスタムのクライアントサイド実装では、前述の例に示すように、常に`tool_reference`コンテンツブロックを含む標準の`tool_result`形式を使用してください。
</Note>

埋め込みを使用した完全な例については、[埋め込みによるツール検索](https://platform.claude.com/cookbook/tool-use-tool-search-with-embeddings)のレシピを参照してください。

## エラー処理

<Note>
  [ツール使用の例](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/define-tools#providing-tool-use-examples) はツール検索と連携します。Claudeが遅延ツールを発見すると、APIは その定義とともに`input_examples`も展開します。
</Note>

### HTTPエラー（400ステータス）

これらのエラーは、APIによるリクエストの処理を妨げます。

**すべてのツールが遅延されている場合：**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "At least one tool must have defer_loading=false. All tools cannot be deferred."
  }
}
```

**ツール定義が欠落している場合：**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' not found in available tools"
  }
}
```

### ツール結果エラー（200ステータス）

実行中にツール検索操作が失敗した場合、APIは本文にエラーを含む200レスポンスを返します。

```json JSON
{
  "type": "tool_search_tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_tool_input",
    "error_message": "Invalid regular expression pattern: missing ) at position 1"
  }
}
```

`error_code`フィールドには4つの値があります。

* `invalid_tool_input`：検索入力が無効でした。たとえば、不正な形式の正規表現パターンや、200文字の制限を超えるパターンなどです
* `unavailable`：検索を実行できませんでした。たとえば、タイムアウトした場合やサービスが利用できなかった場合などです
* `too_many_requests`：ツール検索操作のレート制限を超えました
* `execution_time_exceeded`：検索が実行時間の制限を超えました

### よくある間違い

<Accordion title="400エラー：すべてのツールが遅延されている">
  **原因：** ツール検索ツールを含むすべてのツールに`defer_loading: true`を設定しています。

  **修正方法：** ツール検索ツールから`defer_loading`を削除します。

  ```json
  {
    "type": "tool_search_tool_regex_20251119",
    "name": "tool_search_tool_regex"
  }
  ```
</Accordion>

<Accordion title="400エラー：ツール定義が欠落している">
  **原因：** `tool_reference`が`tools`配列にないツールを指しています。

  **修正方法：** 発見される可能性のあるすべてのツールに完全な定義があることを確認します。

  ```json
  {
    "name": "my_tool",
    "description": "Full description here",
    "input_schema": {
      "type": "object"
    },
    "defer_loading": true
  }
  ```
</Accordion>

<Accordion title="Claudeが期待するツールを見つけられない">
  **原因：** 正規表現パターンが、ツールの名前、説明、引数名、または引数の説明に一致していません。

  **デバッグ手順：**

  1. ツール名、説明、引数名、引数の説明を確認します。Claudeはこれらすべてのフィールドを検索します。
  2. パターンをテストします：`import re; re.search(r"your_pattern", "tool_name", re.IGNORECASE)`。
  3. マッチングは大文字と小文字を区別しないため、大文字小文字の違いは問題ではありません。
  4. Claudeは完全一致ではなく、`".*weather.*"`のような幅広いパターンを使用します。

  **ヒント：** 発見しやすくするために、ツールの説明に一般的なキーワードを追加してください。
</Accordion>

## プロンプトキャッシング

`defer_loading`がプロンプトキャッシングをどのように維持するかについては、[プロンプトキャッシングを使用したツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching)を参照してください。

`defer_loading: true`のツールに`cache_control`を同時に設定することはできません。APIは400を返します。キャッシュブレークポイントは非遅延のツールに配置してください。

## ストリーミング

ストリーミングを有効にすると、ストリームの一部としてツール検索イベントを受信します。

```sse
event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "tool_search_tool_regex"}}

// Search pattern streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"pattern\":\"weather\"}"}}

// Pause while search executes

// Search results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "tool_search_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "tool_search_tool_search_result", "tool_references": [{"type": "tool_reference", "tool_name": "get_weather"}]}}}

// Claude continues with discovered tools
```

## バッチリクエスト

[Messages Batches API](https://platform.claude.com/docs/ja/build-with-claude/batch-processing)にツール検索ツールを含めることができます。

## 制限とベストプラクティス

### 制限

* **遅延ツールの最大数：** リクエストごとに`defer_loading: true`のツールは10,000個まで
* **検索結果：** 各検索はデフォルトで最大5件の一致ツールを返します。Claudeは検索入力で`limit`を1から10,000までの任意の整数に設定できます
* **パターンとクエリの長さ：** 正規表現パターンは最大200文字、BM25クエリは最大500文字
* **モデルのサポート：** [モデルの互換性](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-search-tool#model-compatibility)を参照してください

### ツール検索を使用すべき場合

次のいずれかに該当する場合は、ツール検索を使用してください。

* 利用可能なツールが10個以上ある。
* ツール定義が10kトークン以上を消費する。
* ツールセットが大きくなるにつれてツール選択の精度が低下する。
* 複数のMCPサーバーを集約している（200個以上のツール）。
* ツールライブラリが時間とともに増加する。

ツールが10個未満の場合、すべてのリクエストですべてのツールが使用される場合、またはツール定義が小さい場合（合計100トークン未満）は、ツール検索を使用しない標準のツール呼び出しの方が適しています。

### 最適化のヒント

* 最も頻繁に使用する3〜5個のツールは非遅延のままにします。
* 明確で説明的なツール名と説明を記述します。
* ツール名に一貫した名前空間を使用します。サービスまたはリソースごとにプレフィックスを付け（たとえば、`github_`、`slack_`）、1回の検索でグループ全体に一致するようにします。
* ユーザーがタスクを説明する方法に一致するキーワードを説明に使用します。
* 利用可能なツールカテゴリを説明するシステムプロンプトのセクションを追加します：「Slack、GitHub、Jiraとやり取りするためのツールを検索できます。」
* Claudeがどのツールを発見するかを監視して、説明を改善します。

## 使用量

ツール検索は、個別のサーバーツールとして計測されません。レスポンスの`usage.server_tool_use`オブジェクトにはツール検索のフィールドはなく、検索によってコンテキストに読み込まれたツール定義は、他のツール定義と同様に入力トークンとしてカウントされます。

## 次のステップ

<CardGroup cols={2}>
  <Card title="メモリツール" icon="brain" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/memory-tool">
    アプリケーションにメモリツールのファイル操作を実装することで、Claudeが会話をまたいで情報を保存および取得できるようにします。
  </Card>

  <Card title="ツールリファレンス" icon="book" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference">
    Anthropicが提供するツールの一覧と、オプションのツール定義プロパティのリファレンスです。
  </Card>

  <Card title="MCPコネクタ" icon="link" href="https://platform.claude.com/docs/ja/agents-and-tools/mcp-connector">
    遅延読み込みを使用してMCPツールセットを設定します。
  </Card>

  <Card title="プロンプトキャッシングを使用したツール使用" icon="bolt" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    ターンをまたいでツール定義をキャッシュし、何がキャッシュを無効化するかを理解します。
  </Card>

  <Card title="ツールの定義" icon="hammer" href="https://platform.claude.com/docs/ja/agents-and-tools/tool-use/define-tools">
    ツールスキーマを指定し、効果的な説明を記述し、Claudeがツールを呼び出すタイミングを制御します。
  </Card>
</CardGroup>