도구 검색 도구

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

이 접근 방식은 도구 라이브러리가 확장됨에 따라 빠르게 복잡해지는 두 가지 문제를 해결합니다:

• 컨텍스트 비대화: 도구 정의는 컨텍스트 예산을 빠르게 소모합니다. 일반적인 멀티 서버 설정(GitHub, Slack, Sentry, Grafana, Splunk)은 Claude가 실제 작업을 시작하기 전에 정의에서 55k 토큰을 소비할 수 있습니다. 도구 검색은 일반적으로 이를 85% 이상 줄여, 특정 요청에 Claude가 실제로 필요한 35개의 도구만 로드합니다.
• 도구 선택 정확도: 사용 가능한 도구가 30~50개를 초과하면 Claude의 올바른 도구 선택 능력이 크게 저하됩니다. 필요에 따라 관련 도구의 집중된 세트를 표시함으로써, 도구 검색은 수천 개의 도구에서도 선택 정확도를 높게 유지합니다.

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

자체 검색 구현에서 tool_reference 블록을 반환하여 클라이언트 측 도구 검색을 구현할 수도 있습니다.

도구 검색 작동 방식

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

• Regex (tool_search_tool_regex_20251119): Claude가 도구를 검색하기 위해 regex 패턴을 구성합니다
• BM25 (tool_search_tool_bm25_20251119): Claude가 자연어 쿼리를 사용하여 도구를 검색합니다

도구 검색 도구를 활성화하면:

1. 도구 목록에 도구 검색 도구(예: tool_search_tool_regex_20251119 또는 tool_search_tool_bm25_20251119)를 포함합니다
2. 즉시 로드되지 않아야 하는 도구에 defer_loading: true를 사용하여 모든 도구 정의를 제공합니다
3. Claude는 처음에 도구 검색 도구와 지연되지 않은 도구만 봅니다
4. Claude가 추가 도구가 필요할 때 도구 검색 도구를 사용하여 검색합니다
5. API는 가장 관련성 높은 3-5개의 tool_reference 블록을 반환합니다
6. 이 참조들은 자동으로 전체 도구 정의로 확장됩니다
7. Claude는 발견된 도구 중에서 선택하여 호출합니다

이를 통해 컨텍스트 창을 효율적으로 유지하면서 높은 도구 선택 정확도를 유지합니다.

빠른 시작

다음은 지연된 도구를 사용하는 간단한 예입니다:

도구 정의

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

{
  "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이 없는 도구는 즉시 컨텍스트에 로드됩니다
• defer_loading: true가 있는 도구는 Claude가 검색을 통해 발견할 때만 로드됩니다
• 도구 검색 도구 자체는 절대로 defer_loading: true를 가져서는 안 됩니다
• 최적의 성능을 위해 가장 자주 사용되는 3-5개의 도구를 비지연 상태로 유지하세요

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

지연이 내부적으로 작동하는 방식: 지연된 도구는 시스템 프롬프트 접두사에 포함되지 않습니다. 모델이 도구 검색을 통해 지연된 도구를 발견하면, 도구 정의가 대화에서 tool_reference 블록으로 인라인으로 추가됩니다. 접두사는 변경되지 않으므로 프롬프트 캐싱이 보존됩니다. 엄격 모드의 문법은 전체 도구 세트에서 구축되므로, 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": {
        "query": "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가 도구 검색 도구를 호출하고 있음을 나타냅니다
• tool_search_tool_result: 중첩된 tool_search_tool_search_result 객체와 함께 검색 결과를 포함합니다
• tool_references: 발견된 도구를 가리키는 tool_reference 객체의 배열
• tool_use: Claude가 발견된 도구를 호출합니다

tool_reference 블록은 Claude에게 표시되기 전에 자동으로 전체 도구 정의로 확장됩니다. 이 확장을 직접 처리할 필요가 없습니다. tools 매개변수에 일치하는 모든 도구 정의를 제공하는 한 API에서 자동으로 처리됩니다.

MCP 통합

defer_loading을 사용하여 mcp_toolset을 구성하는 방법은 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" }]
}

참조된 모든 도구는 defer_loading: true가 있는 최상위 tools 매개변수에 해당하는 도구 정의가 있어야 합니다. 이 접근 방식을 사용하면 도구 검색 시스템과의 호환성을 유지하면서 더 정교한 검색 알고리즘을 사용할 수 있습니다.

임베딩을 사용하는 완전한 예제는 임베딩을 사용한 도구 검색 쿡북을 참조하세요.

오류 처리

HTTP 오류 (400 상태)

이러한 오류는 요청이 처리되지 않도록 합니다:

모든 도구가 지연됨:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "All tools have defer_loading set. At least one tool must be non-deferred."
  }
}

도구 정의 누락:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Tool reference 'unknown_tool' has no corresponding tool definition"
  }
}

도구 결과 오류 (200 상태)

도구 실행 중 오류는 본문에 오류 정보가 있는 200 응답을 반환합니다:

{
  "type": "tool_result",
  "tool_use_id": "srvtoolu_01ABC123",
  "content": {
    "type": "tool_search_tool_result_error",
    "error_code": "invalid_pattern"
  }
}

오류 코드:

• too_many_requests: 도구 검색 작업에 대한 속도 제한 초과
• invalid_pattern: 잘못된 형식의 regex 패턴
• pattern_too_long: 패턴이 200자 제한을 초과
• unavailable: 도구 검색 서비스 일시적으로 사용 불가

일반적인 실수

프롬프트 캐싱

defer_loading이 프롬프트 캐싱을 보존하는 방법은 프롬프트 캐싱을 사용한 도구 사용을 참조하세요.

시스템은 전체 대화 기록에서 tool_reference 블록을 자동으로 확장하므로, Claude는 다시 검색하지 않고도 후속 턴에서 발견된 도구를 재사용할 수 있습니다.

스트리밍

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

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

// 검색 쿼리 스트리밍
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"weather\"}"}}

// 검색 실행 중 일시 중지

// 검색 결과 스트리밍
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가 발견된 도구로 계속 진행

배치 요청

메시지 배치 API에 도구 검색 도구를 포함할 수 있습니다. 메시지 배치 API를 통한 도구 검색 작업은 일반 메시지 API 요청과 동일한 가격으로 책정됩니다.

데이터 보존

서버 측 도구 검색(tool_search 도구)은 즉각적인 API 응답을 넘어 도구 카탈로그 데이터(도구 이름, 설명, 인수 메타데이터)를 인덱싱하고 저장합니다. 이 카탈로그 데이터는 Anthropic의 표준 보존 정책에 따라 보존됩니다. 표준 메시지 API를 사용하는 사용자 정의 클라이언트 측 도구 검색 구현은 완전히 ZDR 적격입니다.

모든 기능에 걸친 ZDR 적격성에 대해서는 API 및 데이터 보존을 참조하세요.

제한 및 모범 사례

제한

• 최대 도구 수: 카탈로그에 10,000개의 도구
• 검색 결과: 검색당 가장 관련성 높은 3-5개의 도구 반환
• 패턴 길이: regex 패턴의 최대 200자
• 모델 지원: Claude Mythos Preview, Sonnet 4.0+, Opus 4.0+만 지원 (Haiku 제외)

도구 검색을 사용해야 할 때

좋은 사용 사례:

• 시스템에 10개 이상의 도구가 있는 경우
• 도구 정의가 >10k 토큰을 소비하는 경우
• 대규모 도구 세트에서 도구 선택 정확도 문제가 발생하는 경우
• 여러 서버(200개 이상의 도구)가 있는 MCP 기반 시스템을 구축하는 경우
• 시간이 지남에 따라 도구 라이브러리가 성장하는 경우

전통적인 도구 호출이 더 나을 수 있는 경우:

• 총 10개 미만의 도구
• 모든 도구가 모든 요청에서 자주 사용되는 경우
• 매우 작은 도구 정의 (<100 토큰 총계)

최적화 팁

• 가장 자주 사용되는 3-5개의 도구를 비지연 상태로 유지하세요
• 명확하고 설명적인 도구 이름과 설명을 작성하세요
• 도구 이름에 일관된 네임스페이싱 사용: 서비스 또는 리소스별로 접두사 지정(예: github_, slack_)하여 검색 쿼리가 자연스럽게 올바른 도구 그룹을 표시하도록 합니다
• 사용자가 작업을 설명하는 방식과 일치하는 시맨틱 키워드를 설명에 사용하세요
• 사용 가능한 도구 카테고리를 설명하는 시스템 프롬프트 섹션 추가: "Slack, GitHub, Jira와 상호 작용하는 도구를 검색할 수 있습니다"
• Claude가 발견하는 도구를 모니터링하여 설명을 개선하세요

사용량

도구 검색 도구 사용량은 응답 사용량 객체에서 추적됩니다:

{
  "usage": {
    "input_tokens": 1024,
    "output_tokens": 256,
    "server_tool_use": {
      "tool_search_requests": 2
    }
  }
}

다음 단계