도구 검색 도구

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

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

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

도구 검색을 지원하는 모델은 모델 호환성을 참조하세요.

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

모델 호환성

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

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가 발견된 도구 중에서 선택하여 호출합니다.

빠른 시작

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

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)

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

컴퓨터 사용 및 브라우저 사용 도구 세트(computer_toolset_20260801 및 browser_toolset_20260801)는 항목 자체가 아닌 항목의 configs 객체 내부에서 멤버 도구별로 defer_loading을 받습니다. 항목 수준에서 이를 설정하는 요청은 거부됩니다. 도구 세트는 하나의 단위로 지연되고 확장되므로, defer_loading은 활성화된 모든 멤버에서 동일한 값으로 해석되어야 하며, Claude가 검색을 통해 도구 세트를 발견하면 활성화된 모든 멤버가 한 번에 로드됩니다. configs 형식은 클라이언트 도구 세트를 참조하세요.

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

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

응답 형식

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

사용자 정의 도구 검색 구현

사용자 정의 도구에서 tool_reference 블록을 반환하여 자체 도구 검색 로직(예: 임베딩 또는 시맨틱 검색 사용)을 구현할 수 있습니다. Claude가 사용자 정의 검색 도구를 호출하면, content 배열에 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: 검색이 실행 시간 제한을 초과함

일반적인 실수

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

{
  "name": "my_tool",
  "description": "Full description here",
  "input_schema": {
    "type": "object"
  },
  "defer_loading": true
}

프롬프트 캐싱

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개의 일치 도구를 반환합니다. Claude는 검색 입력에서 limit을 1에서 10,000 사이의 정수로 설정할 수 있습니다
• 패턴 및 쿼리 길이: 정규식 패턴은 최대 200자, BM25 쿼리는 최대 500자
• 모델 지원: 모델 호환성 참조

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

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

• 사용 가능한 도구가 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 객체에는 도구 검색 필드가 없으며, 검색이 컨텍스트에 로드하는 도구 정의는 다른 도구 정의와 마찬가지로 입력 토큰으로 계산됩니다.

다음 단계