Scale to many tools with tool search

기준일: 2026-07-26
공식 기준: Scale to many tools with tool search

Scale to many tools with tool search 문서는 Claude Code 공식 문서(agent-sdk/tool-search)를 한국어로 정리한 가이드입니다. Scale your agent to thousands of tools by discovering and loading only what's needed, on demand. 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Scale your agent to thousands of tools by discovering and loading only what's needed, on demand.

한국어 가이드 범위: agent-sdk/tool-search 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Scale to many tools with tool search
• How tool search works
• Configure tool search
• Optimize tool discovery
• Limits
• Related documentation

상세 내용

Scale to many tools with tool search

Scale your agent to thousands of tools by discovering and loading only what's needed, on demand.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

• Context efficiency: Tool definitions can consume large portions of the context window (50 tools can use 10-20K tokens), leaving less room for actual work.
• Tool selection accuracy: Tool selection accuracy degrades with more than 30-50 tools loaded at once.

How tool search works

When tool search is active, tool definitions are withheld from the context window. The agent receives a summary of available tools and searches for relevant ones when the task requires a capability not already loaded. Up to five of the most relevant tools are loaded into context by default, where they stay available for subsequent turns. If the conversation is long enough that the SDK compacts earlier messages to free space, previously discovered tools may be removed, and the agent searches again as needed.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Configure tool search

Tool search is on by default. It is disabled by default on Google Cloud's Agent Platform, where it is supported for Claude Sonnet 4.5 and later and Claude Opus 4.5 and later. It is also disabled when ANTHROPIC_BASE_URL points to a non-first-party host, since most proxies do not forward tool_reference blocks. You can override either default with the ENABLE_TOOL_SEARCH environment variable:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Value	Behavior
(unset)	Tool search is on. Tool definitions are deferred and discovered on demand. Falls back to loading upfront on Google Cloud's Agent Platform or a non-first-party ANTHROPIC_BASE_URL.
true	Tool search is always on. The SDK sends the beta header even on Google Cloud's Agent Platform and through proxies. Requests fail on Google Cloud's Agent Platform models earlier than Sonnet 4.5 or Opus 4.5, or on proxies that do not support tool_reference blocks.
auto	Checks the combined token count of all tool definitions against the model's context window. If they exceed 10%, tool search activates. If they're under 10%, all tools are loaded into context normally.
auto:N	Same as auto with a custom percentage. auto:5 activates when tool definitions exceed 5% of the context window. Lower values activate sooner.
false	Tool search is off. All tool definitions are loaded into context on every turn.

Optimize tool discovery

The search mechanism matches queries against tool names and descriptions. Names like search_slack_messages surface for a wider range of requests than query_slack. Descriptions with specific keywords ("Search Slack messages by keyword, channel, or date range") match more queries than generic ones ("Query Slack").

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

Limits

주요 항목:

• Maximum tools: 10,000 tools in your catalog
• Search results: returns up to five most relevant tools per search by default
• Model support: Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5, and later models; see model compatibility in the API docs for the current list. On Google Cloud's Agent Platform, Claude Sonnet 4.5 and later and Claude Opus 4.5 and later.

Related documentation

주요 항목:

• Tool search in the API: Full API documentation for tool search, including custom implementations
• Connect MCP servers: Connect to external tools via MCP servers
• Custom tools: Build your own tools with SDK MCP servers
• TypeScript SDK reference: Full API reference
• Python SDK reference: Full API reference

실습 체크리스트

1. 공식 문서와 로컬/SDK 버전을 대조합니다.
2. 관련 CLI·SDK 옵션은 공식 페이지와 --help로 교차 확인합니다.
3. Agent SDK 예시는 TypeScript/Python 패키지 최신 API를 우선합니다.
4. 권한·호스팅·보안 설정 변경 후 통합 테스트를 실행합니다.

자주 쓰는 명령·설정 예시

To run this example, replace `https://tools.example.com/mcp` with the URL of your own MCP server. On success the result text prints to the console.

Because this is a single-shot `query()` call, the SDK raises after yielding an error result, so the example wraps the loop in a try block. To see why a run failed, check the result message's `subtype`, such as `error_during_execution`, inside the loop. For more on result messages, see [Handle the result](/docs/en/agent-sdk/agent-loop#handle-the-result).

Setting `ENABLE_TOOL_SEARCH` to `"false"` disables tool search and loads all tool definitions into context on every turn. This removes the search round-trip, which can be faster when the tool set is small (fewer than \~10 tools) and the definitions fit comfortably in the context window.

## Optimize tool discovery

The search mechanism matches queries against tool names and descriptions. Names like `search_slack_messages` surface for a wider range of requests than `query_slack`. Descriptions with specific keywords ("Search Slack messages by keyword, channel, or date range") match more queries than generic ones ("Query Slack").

You can also add a system prompt section listing available tool categories. This gives the agent context about what kinds of tools are available to search for. Pass the text through the `systemPrompt` option in TypeScript or `system_prompt` in Python, using the `claude_code` preset with `append`, which adds your text to the preset's prompt instead of replacing it:

관련 링크

• 공식 원문: agent-sdk/tool-search
• 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·API 이름은 설치 버전에 따라 달라질 수 있습니다.