도구 검색 도구

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

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

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

도구 검색은 Claude API에서 정식으로 제공됩니다. 지원되는 모델은 모델 호환성을 참조하세요.

도구 검색은 서버 측 도구로 실행되지만, 자체 클라이언트 측 도구 검색을 구현할 수도 있습니다. 자세한 내용은 커스텀 도구 검색 구현을 참조하세요.



모델 호환성

두 가지 도구 검색 변형 모두 다음 모델에서 사용할 수 있습니다:

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개).
6. API가 이러한 참조를 전체 도구 정의로 자동 확장합니다.
7. Claude가 발견된 도구 중에서 선택하여 호출합니다.



빠른 시작

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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)

Claude는 카탈로그를 검색하고 get_weather를 발견한 후 호출합니다. 응답은 stop_reason: "tool_use"로 끝납니다. 도구 호출 처리에서와 같이 발견된 도구를 실행하고 tool_result를 반환하세요. 응답 형식에서 반환되는 블록과 다음에 보내야 할 내용을 확인할 수 있습니다.



도구 정의

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

{
  "type": "tool_search_tool_regex_20251119",
  "name": "tool_search_tool_regex"
}

{
  "type": "tool_search_tool_bm25_20251119",
  "name": "tool_search_tool_bm25"
}



지연된 도구 로딩

defer_loading: true를 추가하여 도구를 온디맨드 로딩으로 표시하세요:

{
  "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가 먼저 검색하지 않고도 호출할 수 있도록 하세요.

두 도구 검색 변형(regex 및 bm25) 모두 도구 이름, 설명, 인수 이름, 인수 설명을 검색합니다.

내부적으로 API는 시스템 프롬프트 접두사에서 지연된 도구를 제외합니다. Claude가 도구 검색을 통해 지연된 도구를 발견하면, API는 대화에 tool_reference 블록을 인라인으로 추가한 다음 Claude에 전달하기 전에 전체 도구 정의로 확장합니다. 접두사는 변경되지 않으므로 프롬프트 캐싱이 유지됩니다. 엄격 모드(도구 호출 출력이 스키마와 일치하도록 제한하는 규칙)의 문법은 전체 도구 집합에서 구축되므로, defer_loading과 엄격 모드는 문법 재컴파일 없이 함께 사용할 수 있습니다.



응답 형식

Claude가 도구 검색 도구를 사용하면 응답에 다음 블록 유형이 포함됩니다:

{
  "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"
      }
    },
    {
      "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를 절대 반환하지 마세요.
• 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 커넥터를 통해 MCP 서버에서 제공되는 경우, 개별 도구 정의에 defer_loading을 설정하지 않습니다. 대신 전체 서버에 대해 mcp_toolset 항목의 default_config에 한 번 설정하거나, configs에서 도구별로 설정하세요. MCP 도구 집합 구성을 참조하세요.



커스텀 도구 검색 구현

커스텀 도구에서 tool_reference 블록을 반환하여 자체 도구 검색 로직(예: 임베딩 또는 시맨틱 검색 사용)을 구현할 수 있습니다. Claude가 커스텀 검색 도구를 호출하면, 콘텐츠 배열에 tool_reference 블록이 포함된 표준 tool_result를 반환하세요:

{
  "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 블록을 동일한 방식으로 확장합니다.

임베딩을 사용하는 전체 예제는 임베딩을 사용한 도구 검색 레시피를 참조하세요.



오류 처리



HTTP 오류 (400 상태)

이러한 오류는 API가 요청을 처리하지 못하게 합니다:

모든 도구가 지연됨:

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

도구 정의 누락:

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



도구 결과 오류 (200 상태)

실행 중에 도구 검색 작업이 실패하면 API는 본문에 오류가 포함된 200 응답을 반환합니다:

{
  "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: 검색이 실행 시간 제한을 초과함



일반적인 실수



프롬프트 캐싱

defer_loading이 프롬프트 캐싱을 유지하는 방법은 프롬프트 캐싱과 함께하는 도구 사용을 참조하세요.

defer_loading: true가 설정된 도구에는 cache_control을 함께 사용할 수 없습니다. API가 400을 반환합니다. 캐시 중단점은 지연되지 않은 도구에 설정하세요.



스트리밍

스트리밍이 활성화되면 스트림의 일부로 도구 검색 이벤트를 받게 됩니다:

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에 도구 검색 도구를 포함할 수 있습니다.



제한 및 모범 사례



제한

• 최대 지연 도구 수: 요청당 defer_loading: true가 설정된 도구 10,000개
• 검색 결과: 각 검색은 기본적으로 최대 5개의 일치하는 도구를 반환
• 패턴 및 쿼리 길이: 정규식 패턴은 최대 200자, BM25 쿼리는 최대 500자
• 모델 지원: 모델 호환성 참조



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

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

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

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



최적화 팁

• 가장 자주 사용되는 3–5개의 도구는 지연되지 않은 상태로 유지하세요.
• 명확하고 설명적인 도구 이름과 설명을 작성하세요.
• 도구 이름에 일관된 네임스페이스를 사용하세요. 서비스 또는 리소스별로 접두사를 붙이면(예: github_, slack_) 하나의 검색으로 전체 그룹이 매칭됩니다.
• 사용자가 작업을 설명하는 방식과 일치하는 키워드를 설명에 사용하세요.
• 사용 가능한 도구 카테고리를 설명하는 시스템 프롬프트 섹션을 추가하세요: "Slack, GitHub, Jira와 상호작용하기 위한 도구를 검색할 수 있습니다."
• Claude가 발견하는 도구를 모니터링하여 설명을 개선하세요.



사용량

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



다음 단계