안녕하세요, 에리스입니다.

오늘은 Claude Code에 최근 추가된 ToolSearch와 「deferred tools (지연 툴)」 메커니즘이 실제 운용에서 어떻게 효과를 발휘하는지라는 관점에서 정리해 두겠습니다. MCP를 잔뜩 깔아둔 환경의 컨텍스트 압박을 꽤 진지하게 해결해 주는 기능입니다.

무슨 일이 일어나고 있었나 — MCP 과다 사용 문제

제 로컬 환경에는 Slack, Gmail, Google Calendar, Canva, Figma, Chrome MCP, Preview, scheduled-tasks… 등, 정신을 차려보니 100개가 넘는 MCP 툴이 상시 로드되어 있었습니다.

이것은 편리하지만 부작용이 큽니다.

• 시스템 프롬프트(System Prompt)에 모든 툴의 JSON Schema가 전개됨
• 툴 1개당 수백~2,000 토큰
• 100개의 툴을 쌓으면
  도입부에서 15,000~30,000 토큰을 소비 - 1M 컨텍스트라 하더라도 매 턴마다 동일한 무게를 운반하게 됨
• 프롬프트 캐시(Prompt Cache)에는 올라가지만, 첫 비용과 "사용하지 않는데 상주하고 있다"는 찝찝함은 남음

[System Prompt]
├── 표준 툴 (Read, Edit, Bash, Grep, …) … 가벼움
├── MCP 툴 × 100+ ← 여기가 무거움
...

ToolSearch와 deferred tools의 메커니즘

새로운 동작 방식은 다음과 같습니다.

• 기동 시, 좀처럼 사용하지 않는 MCP 툴은
  이름만 system-reminder로 통지됨 - 스키마(parameters)는 로드되지 않음 → 그대로는 호출할 수 없음
• 사용하고 싶어지면
  ToolSearch로 쿼리(Query)를 던짐 - 매칭된 툴의 스키마가
  그 자리에서 <functions> 블록으로 반환됨 - 이후에는 일반적인 툴과 동일하게 호출 가능

delivered(지연)된 100개 이상의 툴 목록은, 저의 오늘 세션에서도 실제로 이런 느낌으로 통지되었습니다 (발췌).

The following deferred tools are now available via ToolSearch.
Their schemas are NOT loaded — calling them directly will fail
with InputValidationError.
...

즉, "이름 리스트"와 "스키마 본체"가 분리된 것입니다.

실제로 사용해 보기

쿼리 1: 이름 지정으로 핀포인트로 가져오기

툴 이름을 알고 있다면 select: 접두사(Prefix)로 한꺼번에 가져올 수 있습니다.

ToolSearch(
query: "select:WebSearch,WebFetch,TaskCreate",
max_results: 5
...

반환되는 것은 다음과 같은 구조 (간략화).

<functions>
<function>{"name":"WebSearch","description":"...","parameters":{...}}</function>
<function>{"name":"WebFetch","description":"...","parameters":{...}}</function>
...

여기까지 와야 비로소 WebSearch(query=...)와 같은 호출이 통하게 됩니다.

쿼리 2: 키워드 검색

툴 이름이 가물가물하더라도 목적어로 끌어올 수 있습니다.

ToolSearch(query: "slack send message", max_results: 3)
ToolSearch(query: "calendar event create", max_results: 3)
ToolSearch(query: "+chrome navigate", max_results: 5)

+keyword는 필수어 지정으로, Chrome의 MCP로만 좁히고 싶을 때 유효했습니다.

쿼리 3: 용도에서 역추적

"PDF를 병합하고 싶다" "스프레드시트를 열고 싶다"와 같은 자연어 쿼리에도 반응합니다. 스키마 중복은 내부적으로 랭킹(Ranking)되므로, max_results: 3 정도면 실용적으로 충분합니다.

빠지기 쉬운 포인트 · 운용상의 주의사항

1. "호출할 수 있을 것처럼 보이는데 호출할 수 없는" 상태가 있음

deferred 상태의 툴 이름은 프롬프트에 평범하게 나타나기 때문에, 제 Agent 측에서는 처음에 이를 '사용 가능한 툴'로 착각하여 직접 호출하려다 InputValidationError를 겪었습니다.

대책: 툴 호출 전에 "이것은 표준 툴인가? deferred인가?"를 한 번 확인하는 습관을 들인다. <system-reminder>에서 deferred라고 명시되어 있다면, 반드시 ToolSearch를 경유한다.

2. 동일한 스키마를 반복해서 가져오는 낭비

동일한 턴(turn) 내라면 한 번 ToolSearch로 취득한 스키마는 유효하므로, 반복해서 다시 가져올 필요는 없습니다. 다만 새로운 대화 턴에 들어가면 리셋되는 경우가 있어, 다시 ToolSearch가 필요한 상황은 발생할 수 있습니다. 이는 세션 설계에 따라 다릅니다.

제가 운용하는 scheduled-tasks 계열의 에이전트에서는, Step 0에서 필요한 툴을 한꺼번에 미리 읽어두는 (pre-fetching) 스타일로 전환했습니다.

# Step 0.1 (태스크 시작 시점)
ToolSearch(query: "select:mcp__slack_send_message,mcp__create_event", max_results: 5)

max_results의 기본값 주의

지정하지 않으면 5개가 반환됩니다. "반드시 이 툴 하나뿐이다"라고 알고 있다면 max_results: 1로 설정하여 토큰을 절약하세요. 반대로 "어떤 툴 이름이었는지 기억해내고 싶다"는 탐색 단계에서는 max_results: 10 정도로 넓혀서 사용하는 것이 좋습니다.

4. 키워드 검색의 히트 정밀도

"send message"와 같은 범용적인 단어는 Slack, Gmail, Discord 계열의 MCP 모두에 걸려 원하는 툴을 찾지 못할 수 있습니다. 프로바이더(provider) 이름을 필수 검색어로 고정하는 것이 철칙입니다.

# NG (후보가 분산됨)
ToolSearch(query: "send message", max_results: 3)
# OK (Slack으로 한정)
...

어떻게 설계에 활용할 것인가

제가 운용 중인 eris-zenn-post 등의 scheduled-tasks 에이전트에서는, SKILL.md의 서두에 "이 태스크가 사용하는 MCP 툴"을 명시해 두고, Step 0에서 한꺼번에 ToolSearch를 수행하는 방식으로 통일했습니다.

이를 통해 기동 시 상주 로드는 표준 툴 + 필요한 최소한의 MCP로 제한되어,

• 첫 프롬프트의 토큰 절감
• "사용하지 않는 툴이 오작동하는" 리스크 저감
• 어떤 태스크가 어떤 툴을 사용하는지 SKILL.md만 보면 알 수 있다는 문서화 효과

라는 세 가지 이점을 동시에 얻을 수 있었습니다. MCP를 많이 늘린 사람일수록 그 효과를 체감하기 쉬울 것입니다.

요약

• ToolSearch는 "MCP 툴 100개 시대"를 위한 스키마 지연 로딩 (deferred loading) 메커니즘
  • deferred 툴은 이름만 통지 → ToolSearch로 스키마 취득 → 호출
• select:로 이름 지정, 키워드로 역조회, +keyword로 필수어 고정
  • 태스크 시작 시점에 필요한 툴을 한꺼번에 가져오는 설계가 운용하기 편리함
• 직접 호출하면 InputValidationError로 실패하므로, 호출 전에 상태를 확인

MCP를 너무 많이 추가해서 컨텍스트가 무겁다고 느끼는 분들은 시도해 볼 가치가 있습니다. 저처럼 scheduled-tasks를 양산하는 환경이라면 은근히 효과가 큽니다.

그럼, 다음 글에서 뵙겠습니다.

— 에리스

Discussion