도구 인프라

도구 검색 도구

Claude가 수백 또는 수천 개의 도구를 동적으로 검색하고 온디맨드로 로드하여 작업할 수 있게 하는 도구 검색 도구에 대해 알아보세요.

도구 검색 도구는 Claude가 수백 또는 수천 개의 도구를 동적으로 검색하고 온디맨드로 로드하여 작업할 수 있게 합니다. 모든 도구 정의를 컨텍스트 윈도우에 미리 로드하는 대신, Claude가 도구 이름, 설명, 인수 이름, 인수 설명을 포함한 도구 카탈로그를 검색하여 필요한 도구만 로드합니다.

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

컨텍스트 효율성: 도구 정의가 컨텍스트 윈도우의 상당 부분을 차지할 수 있어(50개 도구 ≈ 10-20K 토큰), 실제 작업에 사용할 공간이 줄어듭니다
도구 선택 정확도: 기존 방식으로 사용 가능한 도구가 30-50개를 초과하면 Claude의 올바른 도구 선택 능력이 크게 저하됩니다

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

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

서버 측 도구 검색은 제로 데이터 보존(ZDR) 계약의 적용을 받지 않습니다. 데이터는 해당 기능의 표준 보존 정책에 따라 보존됩니다. 커스텀 클라이언트 측 도구 검색 구현은 표준 Messages API를 사용하며 ZDR 적용 대상입니다.

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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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_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 통합

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

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "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_toolset",
        "mcp_server_name": "database-server",
        "default_config": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP 구성 옵션:

default_config.defer_loading: MCP 서버의 모든 도구에 대한 기본값을 설정합니다
configs: 이름으로 특정 도구의 기본값을 재정의합니다
대규모 도구 라이브러리를 위해 여러 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" }
  ]
}

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

응답 형식 섹션에 표시된 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: 도구 검색 서비스 일시적으로 사용 불가

일반적인 실수

프롬프트 캐싱

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

Python

import anthropic

client = anthropic.Anthropic()

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

response1 = client.messages.create(
    model="claude-opus-4-6",
    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.messages.create(
    model="claude-opus-4-6",
    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_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가 발견된 도구로 계속 진행

배치 요청

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가 발견하는 도구를 모니터링하여 설명을 개선하세요

사용량

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

JSON

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

Was this page helpful?

도구 인프라

도구 검색 도구

Claude가 수백 또는 수천 개의 도구를 동적으로 검색하고 온디맨드로 로드하여 작업할 수 있게 하는 도구 검색 도구에 대해 알아보세요.

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

컨텍스트 효율성: 도구 정의가 컨텍스트 윈도우의 상당 부분을 차지할 수 있어(50개 도구 ≈ 10-20K 토큰), 실제 작업에 사용할 공간이 줄어듭니다
도구 선택 정확도: 기존 방식으로 사용 가능한 도구가 30-50개를 초과하면 Claude의 올바른 도구 선택 능력이 크게 저하됩니다

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

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 "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-6",
        "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_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가 발견된 도구를 호출합니다

MCP 통합

curl https://api.anthropic.com/v1/messages \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  --header "anthropic-version: 2023-06-01" \
  --header "anthropic-beta: mcp-client-2025-11-20" \
  --header "content-type: application/json" \
  --data '{
    "model": "claude-opus-4-6",
    "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_toolset",
        "mcp_server_name": "database-server",
        "default_config": {
          "defer_loading": true
        },
        "configs": {
          "search_events": {
            "defer_loading": false
          }
        }
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "What events are in my database?"
      }
    ]
  }'

MCP 구성 옵션:

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

커스텀 도구 검색 구현

JSON

{
  "type": "tool_result",
  "tool_use_id": "toolu_your_tool_id",
  "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.messages.create(
    model="claude-opus-4-6",
    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.messages.create(
    model="claude-opus-4-6",
    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_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가 발견된 도구로 계속 진행

배치 요청

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가 발견하는 도구를 모니터링하여 설명을 개선하세요

사용량

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

JSON

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

Was this page helpful?

도구 검색 작동 방식

빠른 시작

도구 정의

지연 도구 로딩

응답 형식

응답 이해하기

MCP 통합

커스텀 도구 검색 구현

오류 처리

HTTP 오류 (400 상태)

도구 결과 오류 (200 상태)

일반적인 실수

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

400 오류: 도구 정의 누락

Claude가 예상 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

제한 사항 및 모범 사례

제한 사항

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

최적화 팁

사용량

도구 검색 작동 방식

빠른 시작

도구 정의

지연 도구 로딩

응답 형식

응답 이해하기

MCP 통합

커스텀 도구 검색 구현

오류 처리

HTTP 오류 (400 상태)

도구 결과 오류 (200 상태)

일반적인 실수

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

400 오류: 도구 정의 누락

Claude가 예상 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

제한 사항 및 모범 사례

제한 사항

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

최적화 팁

사용량