MCP Tool Search Tool

This is the long-form blog cut of a note I originally posted on LinkedIn. The claims, numbers, and product names are the same; the formatting is for reading on the site.

Context

Original framing (translated in place for key technical posts; substance preserved):

MCP 서버 7개 연결한 유저가 GitHub에 올린 이슈가 있어요. 도구 설명만으로 67,000 토큰이 날아갔다는 내용이었는데, Anthropic에서 가장 많이 요청받은 기능이었다고 해요.

이번에 Claude Code에 Tool Search Tool이 정식 롤아웃되면서 이 lazy loading 문제가 해결됐어요. 사실 저도 tool registry 기반으로 tool calling 을 자체적으로 하던 입장에서 이번 클로드 코드 업데이트는 반가웠습니다.

1️⃣ 작동 방식은 단순해요

Claude Code가 MCP 도구 설명이 컨텍스트의 10%를 넘는지 자동으로 체크합니다.

• 10% 초과 시: 도구를 미리 로드하지 않고, 필요할 때 검색해서 가져옴 • 10% 이하 시: 기존과 완전히 동일하게 동작 • 사용자 입장에서 별도 설정 필요 없음

2️⃣ 두 가지 검색 방식 지원

상황에 따라 Regex와 BM25 중 선택할 수 있어요.

• Regex(tool_search_tool

MCP 서버 7개 연결한 유저가 GitHub에 올린 이슈가 있어요. 도구 설명만으로 67,000 토큰이 날아갔다는 내용이었는데, Anthropic에서 가장 많이 요청받은 기능이었다고 해요.

이번에 Claude Code에 Tool Search Tool이 정식 롤아웃되면서 이 lazy loading 문제가 해결됐어요. 사실 저도 tool registry 기반으로 tool calling 을 자체적으로 하던 입장에서 이번 클로드 코드 업데이트는 반가웠습니다.

1️⃣ 작동 방식은 단순해요

Claude Code가 MCP 도구 설명이 컨텍스트의 10%를 넘는지 자동으로 체크합니다.

• 10% 초과 시: 도구를 미리 로드하지 않고, 필요할 때 검색해서 가져옴 • 10% 이하 시: 기존과 완전히 동일하게 동작 • 사용자 입장에서 별도 설정 필요 없음

2️⃣ 두 가지 검색 방식 지원

상황에 따라 Regex와 BM25 중 선택할 수 있어요.

• Regex(tool_search_tool_regex): get_.*_data 같은 패턴 매칭. 도구 네이밍 규칙이 명확할 때 유용 • BM25(tool_search_tool_bm25): 자연어 쿼리 지원. “슬랙 메시지 보내는 도구” 같은 검색 가능 • 검색당 3~5개 도구만 로드, 최대 10,000개 도구 카탈로그 지원

3️⃣ API 사용자는 Custom Search도 가능

임베딩 기반 시맨틱 검색 같은 고급 로직을 직접 구현할 수 있어요.

• 커스텀 도구에서 tool_reference 블록을 반환하면 됨 • 반환된 도구명에 해당하는 정의가 tools 파라미터에 defer_loading: true로 있어야 함 • Anthropic Cookbook에 임베딩 활용 예제도 공개되어 있음

4️⃣ MCP 서버 개발자라면 체크할 것

Tool Search가 활성화되면 “server instructions” 필드가 중요해져요.

• Claude가 언제 해당 서버의 도구를 검색해야 하는지 판단하는 기준이 됨 • Skills 설명하듯이 “이 서버는 ~할 때 사용” 형태로 작성하면 검색 정확도 올라감 • 도구 이름과 description에 시맨틱 키워드 잘 넣어두는 게 핵심

한 가지 참고할 점은, Anthropic이 MCP 도구끼리 코드로 조합하는 programmatic tool calling도 실험했는데, 컨텍스트 절약이 더 급해서 Tool Search를 먼저 출시했다고 해요. 이 부분은 계속 개발 중이라고 하니 후속 업데이트 기대해봐도 될 것 같아요.