Claude Advanced Tool Use: Tool Search, Programmatic Tool Calling, Tool Use Examples
Claude Advanced Tool Use
TL;DR Highlight
Anthropic이 Claude API에 도구를 동적으로 검색·코드로 호출·예시로 학습하는 3가지 베타 기능을 추가했다. MCP 도구가 많아질수록 컨텍스트 윈도우를 잡아먹는 문제를 정면으로 해결하는 접근.
Who Should Read
MCP 서버나 다수의 외부 도구를 연동하는 AI 에이전트를 만들고 있는 백엔드/풀스택 개발자. 특히 도구 정의가 많아서 토큰 비용이나 컨텍스트 부족 문제를 겪고 있는 경우.
Core Mechanics
- MCP 도구가 5개 서버만 연결해도 58개 도구에 약 55K 토큰을 잡아먹고, Anthropic 내부에서는 134K 토큰까지 올라간 적도 있다. 도구 정의를 전부 컨텍스트에 넣는 기존 방식의 한계가 명확해진 것.
- Tool Search Tool은 도구 정의에 defer_loading: true를 붙여서 처음에는 로드하지 않고, Claude가 필요할 때 검색해서 가져오는 방식이다. 기존 ~77K 토큰 소비가 ~8.7K로 줄어 85% 절감되고, Opus 4 기준 MCP 평가 정확도가 49%에서 74%로 올랐다.
- Programmatic Tool Calling은 Claude가 Python 샌드박스 안에서 코드로 도구를 호출하는 기능이다. 기존에는 도구 하나 부를 때마다 추론 패스가 필요했는데, 반복문·조건문·데이터 변환 같은 오케스트레이션을 코드로 처리해서 컨텍스트 오버헤드를 크게 줄인다.
- Claude for Excel이 이미 Programmatic Tool Calling을 써서 수천 행짜리 스프레드시트를 컨텍스트 윈도우 과부하 없이 읽고 수정하고 있다고 한다.
- Tool Use Examples는 도구의 JSON 스키마만으로는 표현 못 하는 사용 패턴(언제 선택적 파라미터를 넣을지, 어떤 조합이 맞는지)을 예시로 보여주는 기능이다. 스키마는 구조적 유효성만 정의하지, 실제 사용 컨벤션은 못 담기 때문.
- 도구가 많아질수록 가장 흔한 실패 원인은 잘못된 도구 선택과 잘못된 파라미터인데, 특히 notification-send-user vs notification-send-channel처럼 이름이 비슷한 도구들이 문제다. Tool Search가 이걸 완화한다.
- Opus 4.5에서는 Tool Search Tool 적용 시 정확도가 79.5%에서 88.1%로 올랐다. 도구 수가 많을수록 효과가 극대화되는 구조.
Evidence
- CLI 도구로 충분하다는 의견이 있었다. MCP 서버 대신 jira 같은 CLI 도구를 만들면 AI가 --help로 사용법을 배울 수 있고, 사람에게도 도움이 된다는 주장. 도구 정의 프로토콜 자체가 과잉이라는 시각.
- GraphQL을 단일 도구로 쓰는 실사용 경험이 공유됐다. 50개 이상의 REST API 도구 대신 graphql이라는 도구 하나만 주고 에이전트가 쿼리를 직접 작성하게 했더니, 토큰 절약은 물론 N+1 문제도 해결되고 더 잘 동작했다는 사례.
- Tool Search Tool은 직접 구현 가능하다는 의견이 많았다. 첫 번째 LLM 호출에서 검색 도구만 넘기고, 반환된 도구 목록을 두 번째 호출에 넣는 식으로 이미 비슷하게 만들어 쓰고 있다는 경험담. 다른 모델/프로바이더에도 적용 가능한 패턴.
- Programmatic Tool Calling에 대한 기대가 높았다. 기존에는 LLM이 데이터를 가져온 뒤 분석 코드를 작성할 때 데이터를 수동으로 인터프리터에 복사해야 했는데, 이제 샌드박스 VM 안에서 코드와 도구 호출을 같이 할 수 있어 LangChain식 Rube Goldberg 머신보다 훨씬 낫다는 평가.
- 반론도 있었다. 도구를 수백·수천 개 연결하는 방향이 맞느냐는 의문으로, ShellTool 하나로도 충분하고 '더 적은 도구, 더 나은 활용 스킬'이 올바른 방향이라는 주장. 또한 이 기능이 결국 정교한 프롬프트 엔지니어링의 리브랜딩 아니냐는 회의적 시각도 있었다.
How to Apply
- MCP 서버를 3개 이상 연결하는 에이전트를 만들고 있다면, 자주 쓰는 핵심 도구 2~3개만 즉시 로드하고 나머지는 defer_loading: true로 설정해서 Tool Search Tool 패턴을 적용하면 토큰 비용을 80% 이상 줄일 수 있다.
- 에이전트가 데이터 조회 후 가공·분석하는 워크플로우를 갖고 있다면, Programmatic Tool Calling을 도입해서 데이터 fetch와 처리를 하나의 코드 블록 안에서 실행하게 하면 컨텍스트 오염 없이 복잡한 작업을 처리할 수 있다.
- 도구 정의가 많아서 모델이 잘못된 도구를 선택하는 문제를 겪고 있다면, Tool Use Examples로 올바른 사용 패턴을 명시하거나, 댓글에서 나온 것처럼 GraphQL 단일 엔드포인트로 통합하는 것도 고려할 만하다.
- Anthropic API를 안 쓰더라도 동일 패턴을 직접 구현할 수 있다. 첫 번째 호출에서 도구 검색만 수행하고, 결과로 나온 도구만 두 번째 호출에 넘기는 2-pass 방식은 어떤 LLM에서든 적용 가능하다.
Terminology
MCPModel Context Protocol. AI 모델이 외부 도구(슬랙, GitHub 등)와 표준화된 방식으로 통신하는 프로토콜. USB처럼 어떤 도구든 같은 규격으로 꽂으면 바로 쓸 수 있게 해주는 것.
defer_loading도구 정의를 처음부터 컨텍스트에 넣지 않고, 필요할 때 검색해서 로드하는 옵션. 앱의 lazy loading과 같은 개념.
Tool Search Tool수백~수천 개 도구 중 현재 작업에 필요한 것만 검색해서 가져오는 메타 도구. 도구를 찾아주는 도구.
Programmatic Tool CallingLLM이 자연어 대신 Python 코드로 도구를 호출하는 방식. 반복문이나 조건 분기가 필요한 작업에서 추론 횟수를 줄여준다.
컨텍스트 윈도우LLM이 한 번에 처리할 수 있는 텍스트의 최대 크기. 도구 정의가 이 공간을 많이 차지하면 실제 대화에 쓸 공간이 줄어든다.