콘텐츠로 이동

도구 검색 도구 (Tool Search Tool)

Claude가 여러분의 도구 카탈로그를 검색해서 필요한 도구만 불러오게 만들면, 수백~수천 개의 도구도 문제없이 다룰 수 있어요.

도구 검색 도구는 도구를 발견하고 필요할 때만 불러오는 방식(on-demand)으로, Claude가 수백 개에서 수천 개에 이르는 도구를 작업할 수 있게 해줍니다. 모든 도구 정의를 처음부터 컨텍스트 창에 다 넣는 대신, Claude가 여러분의 도구 카탈로그(도구 이름, 설명, 인자 이름, 인자 설명 포함)를 검색해서 필요한 도구만 불러오는 방식이죠.

모든 도구 정의를 미리 다 불러오면, 도구 라이브러리가 커질수록 두 가지 문제가 생깁니다.

  • 컨텍스트 비대화(Context bloat): 흔한 멀티서버 구성(GitHub, Slack, Sentry, Grafana, Splunk)은 Claude가 어떤 작업을 하기도 전에 정의만으로 약 55k 토큰을 소모해요. 도구 검색은 보통 이것을 85퍼센트 이상 줄여서, 한 요청에 Claude가 필요한 3~5개의 도구만 불러옵니다.
  • 도구 선택 정확도: 사용 가능한 도구가 30~50개를 넘어가면 Claude가 올바른 도구를 고르는 능력이 떨어져요. 도구 검색은 관련 도구만 골라서 필요할 때 불러오기 때문에, 수천 개의 도구가 있어도 선택 정확도는 높게 유지됩니다.

도구 검색을 지원하는 모델은 Model compatibility(모델 호환성)에서 확인할 수 있어요.

도구 검색은 서버 측 도구로 실행되지만, 여러분이 직접 클라이언트 쪽 도구 검색을 구현할 수도 있어요. 자세한 내용은 Custom tool search implementation을 참고하세요.

모델 호환성 (Model compatibility)

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

모델 도구 버전
Claude Fable 5.1 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Mythos 5.1 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Fable 5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Mythos 5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Opus 5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Opus 4.8 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Opus 4.7 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Opus 4.6 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Sonnet 4.6 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Opus 4.5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Sonnet 4.5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119
Claude Haiku 4.5 () tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119

Claude Opus 4.1 및 이전 모델은 도구 검색 도구를 지원하지 않습니다.

도구 검색의 동작 방식 (How tool search works)

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

  • 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를 설정합니다. 최소한 하나의 도구(보통 도구 검색 도구 자체)는 deferred로 두면 안 됩니다.
  3. 처음에는 Claude의 컨텍스트에 도구 검색 도구와 deferred가 아닌 도구만 들어 있습니다.
  4. Claude가 추가 도구가 필요하면 도구 검색 도구를 사용해 검색합니다.
  5. API가 검색을 실행하고, 일치하는 도구를 tool_reference 블록으로 반환합니다(기본 최대 5개; Claude는 검색 입력에서 limit을 설정할 수 있습니다).
  6. API가 이 참조를 자동으로 전체 도구 정의로 확장합니다.
  7. Claude가 발견한 도구 중에서 선택해 호출합니다.

빠른 시작 (Quick start)

아래 예시는 도구 검색 도구와 deferred 처리된 도구 두 개를 포함합니다.

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"로 끝나요. 발견된 도구를 실행하고 Handle tool calls에서처럼 tool_result를 반환하면 됩니다. Response format에서는 돌아오는 블록과 그다음 보내야 할 것을 보여줍니다.

도구 정의 (Tool definition)

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

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

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

지연 도구 로딩 (Deferred tool loading)

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은 무엇을 컨텍스트 창에 넣을지 결정하지, 요청에 무엇을 보낼지 결정하는 게 아니라는 점을 주의하세요.

  • deferred 도구를 포함해 모든 도구의 전체 정의를 매 요청마다 tools 배열에 계속 보냅니다. API가 서버 쪽에서 검색을 실행하고 tool_reference 블록을 확장하려면 그것들이 필요해요.
  • defer_loading이 없는 도구는 즉시 컨텍스트에 로드됩니다.
  • defer_loading: true가 붙은 도구는 Claude가 검색을 통해 발견할 때만 로드됩니다.
  • 도구 검색 도구 자체에는 절대 defer_loading: true를 설정하지 마세요.
  • 가장 자주 쓰는 3~5개 도구는 deferred로 두지 않고, Claude가 검색 없이 바로 호출할 수 있게 하는 게 좋아요.

컴퓨터 사용(computer use) 및 브라우저 사용(browser use) 도구셋(computer_toolset_20260801과 browser_toolset_20260801)은 항목 자체가 아니라 항목의 configs 객체 안에서 멤버 도구마다 defer_loading을 받아요. 항목 레벨에 설정한 요청은 거부됩니다. 도구셋은 하나의 단위로 지연·확장되므로 defer_loading은 활성화된 모든 멤버에서 같은 값이어야 하고, Claude가 검색으로 도구셋을 발견하면 활성화된 모든 멤버가 한 번에 로드됩니다. configs 형식은 Client toolsets에서 확인할 수 있어요.

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

내부적으로 API는 시스템 프롬프트 접두사에서 deferred 도구를 제외합니다. Claude가 도구 검색으로 deferred 도구를 발견하면 API가 대화 중간에 tool_reference 블록을 인라인으로 추가한 뒤, Claude에게 넘기기 전에 전체 도구 정의로 확장합니다. 접두사는 그대로 유지되므로 프롬프트 캐싱이 보존됩니다. strict mode(도구 호출 출력을 여러분의 스키마에 맞추도록 제약하는 규칙)의 문법은 전체 도구셋에서 만들어지기 때문에, defer_loading과 strict mode는 문법 재컴파일 없이 함께 사용할 수 있어요.

응답 형식 (Response format)

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"
}

응답 이해하기 (Understanding the response)

  • 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 매개변수에 일치하는 모든 도구 정의를 제공하는 한, 확장을 직접 처리할 필요는 없어요.

대화 계속하기 (Continuing the conversation)

다음 요청에서는 server_tool_use와 tool_search_tool_result 블록을 포함해 assistant의 콘텐츠를 그대로 전달하세요. 사용자 메시지에 발견된 도구에 대한 tool_result를 추가하고, 검색 도구와 모든 deferred 정의를 포함한 같은 tools 배열을 보내면 됩니다. srvtoolu_... ID에는 tool_result를 반환하지 마세요. API가 요청을 거부합니다. API는 대화 기록 전체에서 tool_reference 블록을 확장하므로, Claude는 나중 턴에서 다시 검색하지 않고 발견한 도구를 재사용할 수 있어요. 검색이 아무것도 일치하지 않으면 오류 대신 빈 tool_references 배열을 가진 tool_search_tool_search_result를 반환합니다.

MCP 통합 (MCP integration)

도구가 MCP connector를 통해 MCP 서버에서 오는 경우, 개별 도구 정의에 defer_loading을 설정하지 않고, mcp_toolset 항목의 default_config에 서버 전체에 대해 한 번 설정하거나 configs에서 도구별로 설정합니다. MCP toolset configuration을 참고하세요.

커스텀 도구 검색 구현 (Custom tool search implementation)

커스텀 도구에서 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 블록을 같은 방식으로 확장합니다.

임베딩을 사용한 완전한 예시는 tool search with embeddings 레시피를 참고하세요.

오류 처리 (Error handling)

HTTP 오류 (400 상태)

다음 오류들은 API가 요청을 처리하지 못하게 만듭니다.

모든 도구가 deferred인 경우:

{
  "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: 도구 검색 작업의 요청 한도(rate limit)를 초과했습니다.
  • execution_time_exceeded: 검색이 실행 시간 제한을 초과했습니다.

프롬프트 캐싱 (Prompt caching)

defer_loading이 프롬프트 캐싱을 어떻게 보존하는지 알아보려면 Tool use with prompt caching을 참고하세요.

defer_loading: true가 붙은 도구에는 cache_control을 함께 넣을 수 없어요. API가 400을 반환합니다. 캐시 중단점(breakpoint)은 deferred가 아닌 도구에 두세요.

스트리밍 (Streaming)

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

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

배치 요청 (Batch requests)

Messages Batches API에 도구 검색 도구를 포함할 수 있어요.

제한과 모범 사례 (Limits and best practices)

제한 (Limits)

  • 최대 deferred 도구 수: 요청당 defer_loading: true가 붙은 도구 최대 10,000개
  • 검색 결과: 각 검색은 기본적으로 일치하는 도구 최대 5개를 반환합니다. Claude는 검색 입력의 limit을 1~10,000 사이의 정수로 설정할 수 있어요.
  • 패턴·질의 길이: regex 패턴은 최대 200자, BM25 질의는 최대 500자
  • 모델 지원: Model compatibility(모델 호환성) 참고

다음 중 하나에 해당하면 도구 검색을 사용하세요.

  • 사용 가능한 도구가 10개 이상일 때
  • 도구 정의가 10k 토큰을 초과할 때
  • 도구셋이 커질수록 도구 선택 정확도가 떨어질 때
  • 여러 MCP 서버를 통합할 때(200개 이상 도구)
  • 도구 라이브러리가 시간이 지나며 계속 커질 때

도구가 10개 미만이고, 모든 도구를 매 요청마다 쓰고, 도구 정의가 작다면(총 100 토큰 미만) 도구 검색 없이 표준 도구 호출이 더 맞아요.

최적화 팁 (Optimization tips)

  • 가장 자주 쓰는 3~5개 도구는 deferred로 두지 마세요.
  • 도구 이름과 설명을 명확하고 설명적으로 작성하세요.
  • 도구 이름에 일관된 네임스페이스를 사용하세요. 서비스나 리소스로 접두사를 붙여서(예: github_, slack_) 한 번의 검색으로 전체 그룹이 일치하도록 하면 돼요.
  • 설명에 사용자가 작업을 표현하는 방식과 맞는 키워드를 넣으세요.
  • 시스템 프롬프트에 사용 가능한 도구 범주를 설명하는 섹션을 추가하세요. "You can search for tools to interact with Slack, GitHub, and Jira." 같은 식이죠.
  • Claude가 어떤 도구를 발견하는지 모니터링해서 설명을 다듬으세요.

사용량 (Usage)

도구 검색은 별도의 서버 도구로 계량되지 않아요. 응답의 usage.server_tool_use 객체에는 도구 검색 필드가 없고, 검색이 컨텍스트에 불러오는 도구 정의는 다른 도구 정의처럼 입력 토큰으로 계산됩니다.

다음 단계 (Next steps)

애플리케이션에 memory 도구의 파일 연산을 구현해서 Claude가 대화 전반에 걸쳐 정보를 저장하고 검색하게 해보세요.

Anthropic 제공 도구의 디렉터리와 선택적 도구 정의 속성의 참조.

도구 스키마를 지정하고, 효과적인 설명을 작성하고, Claude가 도구를 호출하는 시점을 제어하세요.