도구

도구 검색 도구

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

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

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

컨텍스트 효율성: 도구 정의는 컨텍스트 윈도우의 대부분을 차지할 수 있습니다(50개 도구 ≈ 10-20K 토큰). 이는 실제 작업을 위한 공간을 줄입니다
도구 선택 정확도: Claude의 도구 올바른 선택 능력은 30-50개 이상의 기존 사용 가능한 도구가 있으면 크게 저하됩니다

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

도구 검색 도구는 현재 공개 베타 상태입니다. 공급자에 맞는 적절한 베타 헤더를 포함하세요:

공급자	베타 헤더	지원되는 모델
Claude API Microsoft Foundry	`advanced-tool-use-2025-11-20`	Claude Opus 4.5 Claude Sonnet 4.5
Google Cloud의 Vertex AI	`tool-search-tool-2025-10-19`	Claude Opus 4.5 Claude Sonnet 4.5
Amazon Bedrock	`tool-search-tool-2025-10-19`

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

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

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

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_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?"
      }
    ]
  }'

JSON

{
  "type": "tool_search_tool_result",
  "tool_use_id": "toolu_custom_search",
  "content": {
    "type": "tool_search_tool_search_result",
    "tool_references": [{ "type": "tool_reference", "tool_name": "discovered_tool_name" }]
  }
}

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

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가 발견된 도구로 계속 진행

도구 검색 도구

도구 검색 도구

도구 검색 작동 방식

빠른 시작

도구 정의

지연된 도구 로드

응답 형식

응답 이해하기

MCP 통합

사용자 정의 도구 검색 구현

오류 처리

HTTP 오류(400 상태)

도구 결과 오류(200 상태)

일반적인 실수

프롬프트 캐싱

스트리밍

배치 요청

제한 및 모범 사례

제한

도구 검색을 사용할 때

최적화 팁

사용

도구 검색 작동 방식

빠른 시작

도구 정의

지연된 도구 로드

응답 형식

응답 이해하기

MCP 통합

사용자 정의 도구 검색 구현

오류 처리

HTTP 오류(400 상태)

도구 결과 오류(200 상태)

일반적인 실수

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

400 오류: 누락된 도구 정의

Claude가 예상되는 도구를 찾지 못함

프롬프트 캐싱

스트리밍

배치 요청

제한 및 모범 사례

제한

도구 검색을 사용할 때

최적화 팁

사용