도구

도구 검색 도구

Claude가 수백 개 또는 수천 개의 도구로 작업할 수 있도록 하는 도구 검색 도구에 대해 알아봅니다.

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

이 접근 방식은 도구 라이브러리가 확장될 때 두 가지 중요한 문제를 해결합니다:

컨텍스트 효율성: 도구 정의는 컨텍스트 윈도우의 상당한 부분을 소비할 수 있습니다(50개 도구 ≈ 10-20K 토큰). 실제 작업을 위한 공간이 줄어듭니다
도구 선택 정확도: Claude의 도구 선택 능력은 30-50개 이상의 기존 도구가 있을 때 크게 저하됩니다

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

도구 검색 도구는 현재 공개 베타 버전입니다.

이 기능을 사용하려면 API 요청에 "advanced-tool-use-2025-11-20" 베타 헤더를 추가하세요.

도구 검색 도구 사용 경험을 공유하려면 피드백 양식을 통해 연락주세요.

플랫폼 및 모델 지원

플랫폼	지원되는 모델
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Amazon Bedrock에서는 서버 측 도구 검색이 invoke API를 통해서만 사용 가능하며, converse API는 지원하지 않습니다.

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

도구 검색 작동 방식

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

Regex (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는 발견된 도구 중에서 선택하고 호출합니다

이렇게 하면 컨텍스트 윈도우를 효율적으로 유지하면서 높은 도구 선택 정확도를 유지할 수 있습니다.

빠른 시작

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

도구 정의

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

JSON

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

JSON

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

Regex 변형 쿼리 형식: 자연어가 아닌 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)은 도구 이름, 설명, 인수 이름 및 인수 설명을 검색합니다.

응답 형식

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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result with tool_reference: 발견된 도구에 대한 참조를 포함하는 검색 결과
tool_use: Claude가 발견된 도구를 호출합니다

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

MCP 통합

도구 검색 도구는 MCP 서버와 함께 작동합니다. API 요청에 "mcp-client-2025-11-20" 베타 헤더를 추가한 다음, default_configs와 함께 mcp_tool_set을 사용하여 MCP 도구 로드를 지연합니다:

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP 구성 옵션:

default_configs.defer_loading: MCP 서버의 모든 도구에 대한 기본값 설정
configs: 이름으로 특정 도구의 기본값 재정의
대규모 도구 라이브러리를 위해 여러 MCP 서버를 도구 검색과 결합

사용자 정의 도구 검색 구현

사용자 정의 도구에서 tool_reference 블록을 반환하여 자신의 도구 검색 로직(예: 임베딩 또는 의미론적 검색 사용)을 구현할 수 있습니다:

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_custom_search",
  "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 응답을 반환합니다:

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: 도구 검색 서비스를 일시적으로 사용할 수 없음

일반적인 실수

프롬프트 캐싱

도구 검색은 프롬프트 캐싱과 함께 작동합니다. 다중 턴 대화를 최적화하기 위해 cache_control 중단점을 추가합니다:

Python

import anthropic

client = anthropic.Anthropic()

# 도구 검색을 사용한 첫 번째 요청
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Claude의 응답을 대화에 추가
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 캐시 중단점을 사용한 두 번째 요청
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

시스템은 전체 대화 기록 전체에서 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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude가 발견된 도구로 계속 진행

배치 요청

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

제한 및 모범 사례

제한

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

도구 검색을 사용할 때

좋은 사용 사례:

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

기존 도구 호출이 더 나을 때:

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

최적화 팁

가장 자주 사용되는 3-5개 도구를 지연되지 않은 상태로 유지
명확하고 설명적인 도구 이름과 설명 작성
사용자가 작업을 설명하는 방식과 일치하는 의미론적 키워드를 설명에 사용
사용 가능한 도구 카테고리를 설명하는 시스템 프롬프트 섹션 추가: "Slack, GitHub 및 Jira와 상호 작용할 도구를 검색할 수 있습니다"
Claude가 발견하는 도구를 모니터링하여 설명 개선

사용량 및 가격

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

JSON

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

현재 가격 정보는 가격 페이지를 참조하세요.

도구

도구 검색 도구

Claude가 수백 개 또는 수천 개의 도구로 작업할 수 있도록 하는 도구 검색 도구에 대해 알아봅니다.

이 접근 방식은 도구 라이브러리가 확장될 때 두 가지 중요한 문제를 해결합니다:

컨텍스트 효율성: 도구 정의는 컨텍스트 윈도우의 상당한 부분을 소비할 수 있습니다(50개 도구 ≈ 10-20K 토큰). 실제 작업을 위한 공간이 줄어듭니다
도구 선택 정확도: Claude의 도구 선택 능력은 30-50개 이상의 기존 도구가 있을 때 크게 저하됩니다

도구 검색 도구는 현재 공개 베타 버전입니다.

이 기능을 사용하려면 API 요청에 "advanced-tool-use-2025-11-20" 베타 헤더를 추가하세요.

도구 검색 도구 사용 경험을 공유하려면 피드백 양식을 통해 연락주세요.

플랫폼 및 모델 지원

플랫폼	지원되는 모델
Claude API	Claude Opus 4.5, Claude Sonnet 4.5
Microsoft Foundry	Claude Opus 4.5, Claude Sonnet 4.5
Google Cloud Vertex AI	Claude Opus 4.5, Claude Sonnet 4.5
Amazon Bedrock	Claude Opus 4.5

Amazon Bedrock에서는 서버 측 도구 검색이 invoke API를 통해서만 사용 가능하며, converse API는 지원하지 않습니다.

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

도구 검색 작동 방식

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

Regex (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는 발견된 도구 중에서 선택하고 호출합니다

이렇게 하면 컨텍스트 윈도우를 효율적으로 유지하면서 높은 도구 선택 정확도를 유지할 수 있습니다.

빠른 시작

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

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: advanced-tool-use-2025-11-20" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-sonnet-4-5-20250929",
        "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
            }
        ]
    }'

도구 정의

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

JSON

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

JSON

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

Regex 변형 쿼리 형식: 자연어가 아닌 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)은 도구 이름, 설명, 인수 이름 및 인수 설명을 검색합니다.

응답 형식

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_result",
      "tool_use_id": "srvtoolu_01ABC123",
      "content": [{ "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_result with tool_reference: 발견된 도구에 대한 참조를 포함하는 검색 결과
tool_use: Claude가 발견된 도구를 호출합니다

MCP 통합

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: advanced-tool-use-2025-11-20,mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 2048,
    "mcp_servers": [
      {
        "type": "url",
        "name": "database-server",
        "url": "https://mcp-db.example.com"
      }
    ],
    "tools": [
      {
        "type": "tool_search_tool_regex_20251119",
        "name": "tool_search_tool_regex"
      },
      {
        "type": "mcp_tool_set",
        "mcp_server_name": "database-server",
        "default_configs": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP 구성 옵션:

default_configs.defer_loading: MCP 서버의 모든 도구에 대한 기본값 설정
configs: 이름으로 특정 도구의 기본값 재정의
대규모 도구 라이브러리를 위해 여러 MCP 서버를 도구 검색과 결합

사용자 정의 도구 검색 구현

사용자 정의 도구에서 tool_reference 블록을 반환하여 자신의 도구 검색 로직(예: 임베딩 또는 의미론적 검색 사용)을 구현할 수 있습니다:

JSON

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

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

오류 처리

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

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: 도구 검색 서비스를 일시적으로 사용할 수 없음

일반적인 실수

프롬프트 캐싱

도구 검색은 프롬프트 캐싱과 함께 작동합니다. 다중 턴 대화를 최적화하기 위해 cache_control 중단점을 추가합니다:

Python

import anthropic

client = anthropic.Anthropic()

# 도구 검색을 사용한 첫 번째 요청
messages = [
    {
        "role": "user",
        "content": "What's the weather in Seattle?"
    }
]

response1 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

# Claude의 응답을 대화에 추가
messages.append({
    "role": "assistant",
    "content": response1.content
})

# 캐시 중단점을 사용한 두 번째 요청
messages.append({
    "role": "user",
    "content": "What about New York?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.beta.messages.create(
    model="claude-sonnet-4-5-20250929",
    betas=["advanced-tool-use-2025-11-20"],
    max_tokens=2048,
    messages=messages,
    tools=[
        {
            "type": "tool_search_tool_regex_20251119",
            "name": "tool_search_tool_regex"
        },
        {
            "name": "get_weather",
            "description": "Get weather for a location",
            "input_schema": {
                "type": "object",
                "properties": {
                    "location": {"type": "string"}
                },
                "required": ["location"]
            },
            "defer_loading": True
        }
    ]
)

print(f"Cache read tokens: {response2.usage.get('cache_read_input_tokens', 0)}")

시스템은 전체 대화 기록 전체에서 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_result", "tool_use_id": "srvtoolu_xyz789", "content": [{"type": "tool_reference", "tool_name": "get_weather"}]}}

// Claude가 발견된 도구로 계속 진행

배치 요청

제한 및 모범 사례

제한

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

도구 검색을 사용할 때

좋은 사용 사례:

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

기존 도구 호출이 더 나을 때:

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

최적화 팁

가장 자주 사용되는 3-5개 도구를 지연되지 않은 상태로 유지
명확하고 설명적인 도구 이름과 설명 작성
사용자가 작업을 설명하는 방식과 일치하는 의미론적 키워드를 설명에 사용
사용 가능한 도구 카테고리를 설명하는 시스템 프롬프트 섹션 추가: "Slack, GitHub 및 Jira와 상호 작용할 도구를 검색할 수 있습니다"
Claude가 발견하는 도구를 모니터링하여 설명 개선

사용량 및 가격

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

JSON

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

현재 가격 정보는 가격 페이지를 참조하세요.

플랫폼 및 모델 지원

도구 검색 작동 방식

빠른 시작

도구 정의

지연된 도구 로드

응답 형식

응답 이해

MCP 통합

사용자 정의 도구 검색 구현

오류 처리

HTTP 오류 (400 상태)

도구 결과 오류 (200 상태)

일반적인 실수

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

400 오류: 누락된 도구 정의

Claude가 예상 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

제한 및 모범 사례

제한

도구 검색을 사용할 때

최적화 팁

사용량 및 가격

플랫폼 및 모델 지원

도구 검색 작동 방식

빠른 시작

도구 정의

지연된 도구 로드

응답 형식

응답 이해

MCP 통합

사용자 정의 도구 검색 구현

오류 처리

HTTP 오류 (400 상태)

도구 결과 오류 (200 상태)

일반적인 실수

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

400 오류: 누락된 도구 정의

Claude가 예상 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

제한 및 모범 사례

제한

도구 검색을 사용할 때

최적화 팁

사용량 및 가격