---
title: 도구 검색 도구
url: https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool
description: Claude가 도구 카탈로그를 검색하여 필요한 도구만 로드하도록 함으로써 수백 또는 수천 개의 도구로 확장하세요.
---

도구 검색 도구(tool search tool)를 사용하면 Claude가 도구를 필요에 따라 발견하고 로드하여 수백 또는 수천 개의 도구로 작업할 수 있습니다. 모든 도구 정의를 "context window"(컨텍스트 윈도우)에 미리 로드하는 대신, Claude는 도구 카탈로그(도구 이름, 설명, 인수 이름, 인수 설명 포함)를 검색하여 필요한 도구만 로드합니다.

모든 도구 정의를 미리 로드하면 도구 라이브러리가 커짐에 따라 두 가지 문제가 발생합니다:

* **컨텍스트 비대화:** 일반적인 다중 서버 설정(GitHub, Slack, Sentry, Grafana, Splunk)은 Claude가 어떤 작업도 하기 전에 정의만으로 약 55k 토큰을 소비할 수 있습니다. 도구 검색은 일반적으로 이를 85퍼센트 이상 줄여, 주어진 요청에 Claude가 필요로 하는 3–5개의 도구만 로드합니다.
* **도구 선택 정확도:** 사용 가능한 도구가 30–50개를 초과하면 Claude가 올바른 도구를 선택하는 능력이 저하됩니다. 도구 검색은 관련성 있는 도구의 집중된 집합만 필요에 따라 로드하므로, 수천 개의 도구에서도 선택 정확도가 높게 유지됩니다.

도구 검색을 지원하는 모델은 [모델 호환성](https://platform.claude.com/docs/ko/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)에 설명된 보다 광범위한 just-in-time 검색 원칙의 한 사례이기도 합니다.
</Tip>

도구 검색은 서버 측 도구로 실행되지만, 자체 클라이언트 측 도구 검색을 구현할 수도 있습니다. 자세한 내용은 [사용자 정의 도구 검색 구현](https://platform.claude.com/docs/ko/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/ko/manage-claude/api-and-data-retention)을 참조하세요.
</Note>

<Warning>
  Amazon Bedrock에서 서버 측 도구 검색은 Converse API가 아닌 [InvokeModel API](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-runtime_example_bedrock-runtime_InvokeModel_AnthropicClaude_section.html)를 통해서만 사용할 수 있습니다.
</Warning>

<Note>
  [Claude Platform on AWS](https://platform.claude.com/docs/ko/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/ko/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 및 이전 모델은 도구 검색 도구를 지원하지 않습니다.

## 도구 검색 작동 방식

도구 검색에는 두 가지 변형이 있습니다:

* **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`를 설정합니다. 최소 하나의 도구(일반적으로 도구 검색 도구 자체)는 지연되지 않은 상태로 유지되어야 합니다.
3. 처음에 Claude의 컨텍스트에는 도구 검색 도구와 지연되지 않은 도구만 포함됩니다.
4. Claude가 추가 도구를 필요로 할 때 도구 검색 도구를 사용하여 검색합니다.
5. API가 검색을 실행하고 일치하는 도구를 `tool_reference` 블록으로 반환합니다(기본적으로 최대 5개; Claude는 검색 입력에서 `limit`을 설정할 수 있습니다).
6. API가 이러한 참조를 전체 도구 정의로 자동 확장합니다.
7. Claude가 발견된 도구 중에서 선택하여 호출합니다.

## 빠른 시작

다음 예제에는 도구 검색 도구와 두 개의 지연된 도구가 포함되어 있습니다:

<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/ko/agents-and-tools/tool-use/handle-tool-calls)에서와 같이 발견된 도구를 실행하고 `tool_result`를 반환하세요. [응답 형식](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#response-format)에서 반환되는 블록과 다음에 보낼 내용을 확인할 수 있습니다.

## 도구 정의

도구 검색 도구에는 두 가지 변형이 있습니다:

```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`을 받습니다. 항목 수준에서 이를 설정하는 요청은 거부됩니다. 도구 세트는 하나의 단위로 지연되고 확장되므로, `defer_loading`은 활성화된 모든 멤버에서 동일한 값으로 해석되어야 하며, Claude가 검색을 통해 도구 세트를 발견하면 활성화된 모든 멤버가 한 번에 로드됩니다. `configs` 형식은 [클라이언트 도구 세트](https://platform.claude.com/docs/ko/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/ko/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`)이 포함되며, 검색이 반환하는 일치 도구 수를 제한하는 1에서 10,000 사이의 정수인 선택적 `limit`(기본값: 5)이 포함될 수 있습니다.
* **`tool_search_tool_result`:** 중첩된 `tool_search_tool_search_result` 객체에 담긴 검색 결과입니다. 메시지 기록에 그대로 유지하세요.
* **`tool_references`:** 발견된 도구를 가리키는 `tool_reference` 객체의 배열입니다. API가 Claude를 위해 이를 확장합니다. 직접 확장할 필요는 없습니다.
* **`tool_use`:** 발견된 도구에 대한 Claude의 호출입니다. 표준 도구 사용과 정확히 동일하게 실행하고 `tool_result`를 반환하세요.

API는 `tool_reference` 블록을 Claude에게 보여주기 전에 전체 도구 정의로 자동 확장합니다. `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/ko/agents-and-tools/mcp-connector)를 통해 MCP 서버에서 제공되는 경우, 개별 도구 정의에 `defer_loading`을 설정하지 않습니다. 대신 전체 서버에 대해 `mcp_toolset` 항목의 `default_config`에 한 번 설정하거나, `configs`에서 도구별로 설정하세요. [MCP 도구 세트 구성](https://platform.claude.com/docs/ko/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/ko/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/ko/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` 필드에는 네 가지 가능한 값이 있습니다:

* `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/ko/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/ko/build-with-claude/batch-processing)에 도구 검색 도구를 포함할 수 있습니다.

## 제한 및 모범 사례

### 제한

* **최대 지연 도구 수:** 요청당 `defer_loading: true`가 있는 도구 10,000개
* **검색 결과:** 각 검색은 기본적으로 최대 5개의 일치 도구를 반환합니다. Claude는 검색 입력에서 `limit`을 1에서 10,000 사이의 정수로 설정할 수 있습니다
* **패턴 및 쿼리 길이:** 정규식 패턴은 최대 200자, BM25 쿼리는 최대 500자
* **모델 지원:** [모델 호환성](https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-search-tool#model-compatibility) 참조

### 도구 검색을 사용해야 하는 경우

다음 중 하나라도 해당되면 도구 검색을 사용하세요:

* 사용 가능한 도구가 10개 이상입니다.
* 도구 정의가 10k 토큰 이상을 소비합니다.
* 도구 세트가 커짐에 따라 도구 선택 정확도가 떨어집니다.
* 여러 MCP 서버를 통합합니다(200개 이상의 도구).
* 도구 라이브러리가 시간이 지남에 따라 커집니다.

도구가 10개 미만이거나, 모든 도구가 모든 요청에서 사용되거나, 도구 정의가 작은 경우(총 100 토큰 미만)에는 도구 검색 없는 표준 도구 호출이 더 적합합니다.

### 최적화 팁

* 가장 자주 사용하는 3–5개의 도구는 지연되지 않은 상태로 유지하세요.
* 명확하고 설명적인 도구 이름과 설명을 작성하세요.
* 도구 이름에 일관된 네임스페이스를 사용하세요. 서비스 또는 리소스별로 접두사를 붙여(예: `github_`, `slack_`) 한 번의 검색으로 전체 그룹이 일치하도록 하세요.
* 사용자가 작업을 설명하는 방식과 일치하는 키워드를 설명에 사용하세요.
* 사용 가능한 도구 카테고리를 설명하는 시스템 프롬프트 섹션을 추가하세요: "You can search for tools to interact with Slack, GitHub, and Jira."
* Claude가 어떤 도구를 발견하는지 모니터링하여 설명을 개선하세요.

## 사용량

도구 검색은 별도의 서버 도구로 계량되지 않습니다. 응답의 `usage.server_tool_use` 객체에는 도구 검색 필드가 없으며, 검색이 컨텍스트에 로드하는 도구 정의는 다른 도구 정의와 마찬가지로 입력 토큰으로 계산됩니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="메모리 도구" icon="brain" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/memory-tool">
    애플리케이션에서 메모리 도구의 파일 작업을 구현하여 Claude가 대화 전반에 걸쳐 정보를 저장하고 검색할 수 있도록 하세요.
  </Card>

  <Card title="도구 참조" icon="book" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-reference">
    Anthropic 제공 도구 디렉터리 및 선택적 도구 정의 속성에 대한 참조입니다.
  </Card>

  <Card title="MCP 커넥터" icon="link" href="https://platform.claude.com/docs/ko/agents-and-tools/mcp-connector">
    지연 로딩으로 MCP 도구 세트를 구성하세요.
  </Card>

  <Card title="프롬프트 캐싱과 함께 도구 사용" icon="bolt" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/tool-use-with-prompt-caching">
    턴 전반에 걸쳐 도구 정의를 캐시하고 무엇이 캐시를 무효화하는지 이해하세요.
  </Card>

  <Card title="도구 정의" icon="hammer" href="https://platform.claude.com/docs/ko/agents-and-tools/tool-use/define-tools">
    도구 스키마를 지정하고, 효과적인 설명을 작성하고, Claude가 도구를 호출하는 시점을 제어하세요.
  </Card>
</CardGroup>