컨텍스트가 도구 정의로 먼저 찬다
GitHub·Slack·Sentry·Grafana·Splunk 다섯 개 서버를 한 에이전트에 묶으면 작업을 시작하기도 전에 도구 정의만으로 약 55,000토큰이 소모됩니다(Anthropic 공식 문서 기준). 문제는 토큰 비용만이 아니라 선택 정확도로도 번집니다. 사용 가능한 도구가 30~50개를 넘어서는 순간부터 Claude가 올바른 도구를 고르는 능력이 떨어지며, MCP 서버 여러 개를 묶어 200개 이상을 노출하는 구성은 이 문턱을 가볍게 넘깁니다.
해법은 도구 정의를 지우는 게 아니라 필요할 때만 로드하는 구조입니다. 요청마다 전체 목록은 그대로 보내되, 모델 컨텍스트에 실제로 들어가는 시점을 검색 결과가 나온 뒤로 미룹니다. 이 지연 로드로 확인된 절감 폭은 85% 이상이며, 컨텍스트에 남는 도구는 검색당 3~5개로 좁혀집니다.
정규식과 자연어, 두 갈래의 검색 도구
검색형 호출은 tool_search_tool_regex_20251119와 tool_search_tool_bm25_20251119 두 변형으로 제공됩니다. 정규식 변형은 Claude가 re.search() 패턴으로 도구 이름·설명·인자명을 매칭하고(최대 200자), BM25 변형은 자연어 질의로 같은 필드를 검색합니다(최대 500자). 두 변형 모두 검색당 최대 5개까지 tool_reference 블록을 돌려주며, API가 이를 완전한 도구 정의로 자동 확장해 넘깁니다.
개별 도구에는 defer_loading: true를 붙여 지연 로드 대상으로 표시합니다. 요청에는 여전히 모든 정의를 담아 보내야 하고 — 서버가 검색·확장을 수행하려면 정의가 필요합니다 — 검색 도구 자신을 포함해 최소 하나는 지연 로드를 걸 수 없습니다. 지연된 도구는 시스템 프롬프트 접두부에서 빠져 프롬프트 캐시 히트율은 그대로 유지됩니다.
설계에서 운영까지: 검색형 도구 호출 체크리스트
도입 여부는 세 신호로 판단합니다. 도구가 10개를 넘거나, 정의 총량이 10,000토큰을 넘거나, 도구가 늘수록 선택 정확도가 떨어지는 게 관측되면 켤 시점입니다. 목표 지표는 컨텍스트 절감률 85% 이상, 검색당 로드 도구 수 3~5개, 요청당 지연 로드 상한 10,000개를 기준선으로 두고, 자주 쓰는 도구 3~5개는 지연 로드에서 빼 검색 없이 바로 호출되게 남겨 둡니다.
실패는 요청 단계에서부터 생깁니다. 지연 로드 전용이 아닌 도구가 하나도 남지 않으면 400 오류(All tools cannot be deferred)가 나고, tool_reference가 가리키는 정의를 tools 배열에서 빠뜨려도 별도의 400(Tool reference not found)이 발생합니다. 두 경우 다 요청을 보내기 전 정적 검증으로 걸러낼 수 있습니다.
실행 단계에서는 검색 자체가 실패할 수 있고, 오류 코드는 네 갈래입니다 — 패턴·길이 오류인 invalid_tool_input, 서비스 타임아웃인 unavailable, 속도 제한인 too_many_requests, 실행 시간 초과인 execution_time_exceeded. 복구 분기도 코드별로 나눕니다. invalid_tool_input은 패턴을 고쳐 즉시 재시도하고, unavailable·execution_time_exceeded는 지수 백오프로 재시도하며, too_many_requests는 요청 속도 자체를 낮춥니다. 정규식 200자·BM25 500자 상한을 넘는 질의는 클라이언트에서 미리 잘라 400을 예방합니다.
MCP 커넥터로 도구를 끌어올 때는 개별 도구가 아니라 mcp_toolset 항목의 default_config에 지연 로드를 한 번에 걸거나, 서버 안 도구별로 configs를 세분화합니다. 서버 하나가 도구 수십 개를 한꺼번에 늘리는 구조라 서버 단위 설정이 누락을 줄입니다. 이름은 github_·slack_처럼 서비스별 접두어로 일관되게 붙여 한 번의 검색이 그룹 전체를 잡도록 하고, 설명 문구에는 실사용자가 쓰는 표현을 넣어 매칭률을 높입니다.
cache_control은 지연 로드 도구에 걸 수 없으므로(위반 시 400) 캐시 브레이크포인트는 반드시 비지연 도구 쪽에 둡니다. 배포 전에는 검색이 아무것도 못 찾아 tool_references가 빈 배열로 돌아오는 시나리오를 별도로 테스트합니다. 매주 어떤 질의가 어떤 도구를 찾아냈는지 로그로 모아 설명 문구를 다듬고, 실패율이 줄지 않는 그룹은 접두어나 키워드 설계를 다시 봅니다. 내장 검색의 한계를 느끼면 임베딩 기반 커스텀 검색으로 옮길 수 있는데, 이때도 결과는 같은 tool_reference 형식으로 반환해야 API 확장 로직을 그대로 씁니다.
바로 쓰는 체크리스트
자주 쓰는 도구 3~5개만 남기고 나머지를 defer_loading으로 지연시키면 컨텍스트 소모를 85% 이상 줄이면서도 검색당 3~5개 도구로 정확도를 지킵니다. 오류 코드별 재시도·백오프 분기를 미리 설계해 두면 MCP 서버를 하나 더 추가할 때도 같은 절차가 그대로 돌아갑니다.