- 컨텍스트 효율성: 도구 정의는 컨텍스트 윈도우의 큰 부분을 차지할 수 있습니다(50개의 도구는 10-20K 토큰을 사용할 수 있음). 이로 인해 실제 작업을 위한 공간이 줄어듭니다.
- 도구 선택 정확도: 30-50개 이상의 도구가 동시에 로드되면 도구 선택 정확도가 저하됩니다.
도구 검색의 작동 방식
도구 검색이 기본적으로 활성화되어 있으며, 도구 검색 구성에 나열된 예외가 있습니다. 활성화되면 도구 정의는 컨텍스트 윈도우에서 제외됩니다. 에이전트는 사용 가능한 도구의 요약을 받고, 작업에 이미 로드되지 않은 기능이 필요할 때 관련 도구를 검색합니다. 가장 관련성이 높은 최대 5개의 도구가 기본적으로 컨텍스트에 로드되며, SDK가 에이전트가 도구를 발견한 메시지를 압축할 때까지 이후 턴에서도 계속 사용할 수 있습니다. 그 압축 이후에는 에이전트가 필요할 때 해당 도구를 다시 검색합니다. 도구 검색은 Claude가 도구를 검색할 때마다 한 번의 추가 왕복을 추가하지만, 큰 도구 세트의 경우 모든 턴에서 더 작은 컨텍스트로 인한 이점이 있습니다. 컨텍스트 윈도우에 편하게 맞는 약 10개 미만의 도구가 있는 경우, 모든 것을 미리 로드하는 것이 일반적으로 더 빠릅니다. 기본 API 메커니즘에 대한 자세한 내용은 API의 도구 검색을 참조하십시오.도구 검색은 Microsoft Foundry Azure에서 호스팅되는 배포에서 지원되지 않으며, 서버 측에서 거부합니다. SDK는 거부를 감지하고 해당 배포에 대해 대신 도구 정의를 미리 로드합니다.
ENABLE_TOOL_SEARCH는 배포 자체에서 거부가 발생하므로 이를 재정의할 수 없습니다.도구 검색 구성
도구 검색은 기본적으로 켜져 있습니다. SDK의 지원되지 않는 모델 목록에 있는 모델의 경우 SDK는 도구 정의를 미리 로드하며,ENABLE_TOOL_SEARCH 값이 이를 재정의할 수 없습니다. Google Cloud의 Agent Platform에서는 SDK가 모델 세대에 따라 결정합니다:
- Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 버전: 도구 검색이 기본적으로 켜져 있습니다.
- 이전 Agent Platform 모델: SDK는 도구 정의를 미리 로드합니다. 필요한 베타 헤더를 거부하는 서빙 스택이 있기 때문입니다.
ENABLE_TOOL_SEARCH는 이를 재정의할 수 없습니다.
ENABLE_TOOL_SEARCH를 설정하지 않으면 SDK가 Google Cloud의 Agent Platform의 모든 모델에 대해 도구 검색을 비활성화했습니다.
SDK는 또한 ANTHROPIC_BASE_URL이 비공식 호스트를 가리킬 때 도구 검색을 비활성화합니다. 대부분의 프록시는 tool_reference 블록을 전달하지 않기 때문입니다. ENABLE_TOOL_SEARCH 환경 변수로 기본값을 재정의할 수 있습니다:
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 설정은 도구 검색을 끕니다. ENABLE_TOOL_SEARCH를 직접 설정하여 이를 재정의할 수 없습니다. 조직은 Claude Code v2.1.227 이상에서 관리 설정을 통해 도구 검색을 켜진 상태로 유지할 수 있습니다. 사전 릴리스 기능 비활성화는 재정의가 적용되는 위치와 변수가 제거하는 항목을 다룹니다.
도구 검색은 원격 MCP 서버에서 오든 사용자 정의 SDK MCP 서버에서 오든 모든 등록된 도구에 적용됩니다. auto를 사용할 때 SDK는 도구 검색이 연기할 수 있는 모든 정의를 하나의 결합된 임계값으로 계산합니다: alwaysLoad로 표시되지 않은 모든 MCP 도구(모든 서버에서), 그리고 필요에 따라 로드되는 기본 제공 도구입니다. SDK는 항상 Bash, Read, Edit과 같은 핵심 기본 제공 도구를 미리 로드하고 임계값에 계산하지 않습니다.
query()의 env 옵션에서 값을 설정합니다. TypeScript에서 env는 서브프로세스 환경을 대체하므로 상속된 변수를 유지하려면 ...process.env를 전개합니다. Python에서 env는 상속된 환경 위에 병합됩니다. 이 예제는 많은 도구를 노출하는 원격 MCP 서버에 연결하고, 와일드카드로 모두 사전 승인하며, 도구 검색이 연기할 수 있는 정의가 컨텍스트 윈도우의 5%에 도달할 때 도구 검색이 활성화되도록 auto:5를 사용합니다:
https://tools.example.com/mcp를 자신의 MCP 서버 URL로 바꿉니다. 성공하면 결과 텍스트가 콘솔에 출력됩니다.
이것이 단일 query() 호출이므로 SDK는 오류 결과를 생성한 후 발생시키므로 예제는 루프를 try 블록으로 래핑합니다. 실행이 실패한 이유를 확인하려면 루프 내에서 결과 메시지의 subtype(예: error_during_execution)을 확인합니다. 결과 메시지에 대한 자세한 내용은 결과 처리를 참조하세요.
도구 발견 최적화
검색 메커니즘은 도구 이름과 설명에 대해 쿼리를 일치시킵니다.search_slack_messages와 같은 이름은 query_slack보다 더 넓은 범위의 요청에 대해 표시됩니다. 특정 키워드가 있는 설명(“키워드, 채널 또는 날짜 범위별로 Slack 메시지 검색”)은 일반적인 설명(“Slack 쿼리”)보다 더 많은 쿼리와 일치합니다.
사용 가능한 도구 카테고리를 나열하는 시스템 프롬프트 섹션을 추가할 수도 있습니다. 이는 에이전트에게 검색할 수 있는 도구의 종류에 대한 컨텍스트를 제공합니다. TypeScript에서는 systemPrompt 옵션을 통해, Python에서는 system_prompt를 통해 텍스트를 전달하며, claude_code 프리셋과 함께 append를 사용하여 프리셋의 프롬프트에 텍스트를 추가합니다(대체하지 않음):
제한 사항
- 최대 도구: 카탈로그에 10,000개의 도구
- 검색 결과: 기본적으로 검색당 가장 관련성이 높은 5개의 도구 반환
- 모델 지원: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 및 이후 모델; 현재 목록은 API 문서의 모델 호환성을 참조하십시오. Google Cloud의 Agent Platform에서도 동일한 최소 요구 사항이 적용됩니다.
관련 문서
- API의 도구 검색: 사용자 정의 구현을 포함한 도구 검색의 전체 API 문서
- MCP 서버 연결: MCP 서버를 통해 외부 도구에 연결
- 사용자 정의 도구: SDK MCP 서버로 자신의 도구 구축
- TypeScript SDK 참조: 전체 API 참조
- Python SDK 참조: 전체 API 참조