도구 검색 도구

도구 검색

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

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

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

도구 검색이 해결하는 확장 문제에 대한 배경 정보는 고급 도구 사용을 참조하세요. 도구 검색의 온디맨드 로딩은 효과적인 컨텍스트 엔지니어링에서 설명하는 더 광범위한 적시 검색 원칙의 인스턴스이기도 합니다.

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

피드백 양식을 통해 이 기능에 대한 피드백을 공유하세요.

This feature qualifies for Zero Data Retention (ZDR) with limited technical retention. See the Data retention section for details on what is retained and why.

Amazon Bedrock에서 서버 측 도구 검색은 역 API가 아닌 invoke API를 통해서만 사용 가능합니다.

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

도구 검색 작동 방식

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

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

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

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

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

빠른 시작

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

도구 정의

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

JSON

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

JSON

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

정규식 변형 쿼리 형식: 자연어가 아닌 Python 정규식

tool_search_tool_regex_20251119를 사용할 때 Claude는 자연어 쿼리가 아닌 Python의 re.search() 구문을 사용하여 정규식 패턴을 구성합니다. 일반적인 패턴:

"weather" - "weather"를 포함하는 도구 이름/설명과 일치
"get_.*_data" - get_user_data, get_weather_data와 같은 도구와 일치
"database.*query|query.*database" - 유연성을 위한 OR 패턴
"(?i)slack" - 대소문자를 구분하지 않는 검색

최대 쿼리 길이: 200자

BM25 변형 쿼리 형식: 자연어

tool_search_tool_bm25_20251119를 사용할 때 Claude는 자연어 쿼리를 사용하여 도구를 검색합니다.

지연된 도구 로딩

defer_loading: true를 추가하여 온디맨드 로딩을 위해 도구를 표시합니다:

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

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

지연 작동 방식: 지연된 도구는 시스템 프롬프트 접두사에 포함되지 않습니다. 모델이 도구 검색을 통해 지연된 도구를 발견하면 도구 정의가 대화에 tool_reference 블록으로 인라인으로 추가됩니다. 접두사는 변경되지 않으므로 프롬프트 캐싱이 보존됩니다. 엄격한 모드의 문법은 전체 도구 세트에서 빌드되므로 defer_loading과 엄격한 모드는 문법 재컴파일 없이 구성됩니다.

응답 형식

Claude가 도구 검색 도구를 사용할 때 응답에는 새로운 블록 유형이 포함됩니다:

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": {
        "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를 반환합니다:

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "content": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
}

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

응답 형식 섹션에 표시된 tool_search_tool_result 형식은 Anthropic의 기본 제공 도구 검색에서 내부적으로 사용되는 서버 측 형식입니다. 사용자 정의 클라이언트 측 구현의 경우 항상 위에 표시된 대로 tool_reference 콘텐츠 블록이 있는 표준 tool_result 형식을 사용하세요.

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

오류 처리

도구 검색 도구는 도구 사용 예제와 호환되지 않습니다. 도구 사용 예제를 제공해야 하는 경우 도구 검색 없이 표준 도구 호출을 사용하세요.

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 응답을 반환합니다:

JSON

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

오류 코드:

too_many_requests: 도구 검색 작업에 대한 속도 제한 초과
invalid_pattern: 잘못된 형식의 정규식 패턴
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"}}

// Search query streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"query\":\"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에 도구 검색 도구를 포함할 수 있습니다. Messages Batches API를 통한 도구 검색 작업은 일반 Messages API 요청과 동일하게 가격이 책정됩니다.

데이터 보존

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

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

제한 및 모범 사례

제한

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

도구 검색을 사용할 때

좋은 사용 사례:

시스템에서 10개 이상의 도구 사용 가능
도구 정의가 >10k 토큰 소비
대규모 도구 세트로 도구 선택 정확도 문제 경험
MCP 기반 시스템 구축(200개 이상의 도구)
시간이 지남에 따라 도구 라이브러리 증가

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

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

최적화 팁

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

사용

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

JSON

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

다음 단계

도구 참조

모델 호환성 및 매개변수가 있는 전체 도구 카탈로그입니다.

MCP 커넥터

지연된 로딩으로 MCP 도구 세트를 구성합니다.

프롬프트 캐싱

캐시된 도구 정의와 도구 검색을 결합합니다.

client = anthropic.Anthropic()

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

도구 검색 작동 방식

빠른 시작

도구 정의

지연된 도구 로딩

응답 형식

응답 이해

MCP 통합

사용자 정의 도구 검색 구현

오류 처리

HTTP 오류(400 상태)

도구 결과 오류(200 상태)

일반적인 실수

400 오류: 모든 도구가 지연됨

400 오류: 누락된 도구 정의

Claude가 예상된 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

데이터 보존

제한 및 모범 사례

제한

도구 검색을 사용할 때

최적화 팁

사용

다음 단계