Anthropic Advanced Tool Use: 프로그래매틱 도구 호출과 도구 검색으로 에이전트 컨텍스트 비용을 줄이는 방법

왜 지금 봐야 하나

에이전트가 쓸 수 있는 도구가 10개일 때는 아무 문제가 없다. 도구 정의를 모두 컨텍스트에 넣고, 모델이 적절한 것을 고른다. 하지만 Slack, GitHub, Sentry, Grafana, Splunk 다섯 개 MCP 서버만 붙여도 도구 정의만 약 55,000 토큰을 소비한다. 실제 작업 내용은 한 줄도 처리하기 전이다.

문제는 여기서 끝나지 않는다. Claude를 비롯한 LLM은 도구가 30~50개를 넘으면 선택 정확도 자체가 떨어진다. 모델이 너무 많은 도구 이름과 설명을 컨텍스트에 유지해야 하기 때문이다.

Anthropic이 2025~2026년에 걸쳐 공개한 세 가지 기능은 이 구조적 문제를 정면으로 다룬다.

• Tool Search (tool_search_tool_regex_20251119, tool_search_tool_bm25_20251119) — 도구를 필요할 때만 로드하는 지연 검색
• Programmatic Tool Calling (code_execution_20260120) — 코드 실행 샌드박스 안에서 도구를 배치 호출
• Advisor Strategy (advisor-tool-2026-03-01) — 에이전트가 행동하기 전 전략적 검토 단계를 삽입

이 글은 앞의 두 기능을 중심으로 동작 원리와 운영 판단 기준을 정리한다.

도구가 많아지면 무슨 일이 일어나는가

일반적인 에이전트 흐름은 이렇다.

1. 모든 도구 정의를 tools 배열에 담아 API에 보낸다.
2. 모델이 도구를 하나 고른다.
3. 결과를 받아서 다시 모델에 보낸다.
4. 다음 도구를 고를 때까지 반복한다.

각 단계마다 모델 한 번 호출이 발생한다. 20가지 데이터를 조회해야 한다면 최소 20번의 왕복이 필요하다. 그리고 각 왕복마다 이전 결과 전체가 컨텍스트에 누적된다. 조회 결과 하나가 1,000토큰이라면, 20번째 호출 시점에는 결과만 20,000토큰이 된다.

이것이 Anthropic이 말하는 컨텍스트 폭발의 실체다.

Tool Search: 지연 로딩으로 컨텍스트 폭발 방지

Tool Search는 도구 정의를 필요한 시점까지 컨텍스트에서 숨기는 기능이다. 사용 방식은 단순하다.

1. tools 배열에 모든 도구 정의를 보내되, 즉시 로드하지 않을 도구에 defer_loading: true를 붙인다.
2. Tool Search 도구 자체는 defer_loading 없이 즉시 로드한다.
3. Claude가 작업 중 필요한 도구를 찾아야 할 때 Tool Search 도구를 호출한다.
4. API가 검색을 실행하고 매칭된 도구의 tool_reference 블록을 반환한다.
5. API가 해당 정의를 Claude 컨텍스트에 자동으로 확장한다.

핵심은 서버 사이드에서 처리된다는 점이다. 개발자는 여전히 모든 도구 정의를 tools에 보내야 하지만, Claude가 받는 컨텍스트에는 실제로 필요한 것만 들어간다.

Regex 변형 vs BM25 변형

두 가지 Tool Search 변형이 있다.

Regex 변형은 "github_.*_pr" 같은 패턴으로 정확하게 필터링하기 좋다. BM25 변형은 Claude가 "pull request를 리뷰하는 도구"처럼 자연어로 검색할 수 있어 탐색적 사용에 유연하다.

검색은 도구 이름, 설명, 인수 이름, 인수 설명 모두를 대상으로 하며, 한 번에 최대 5개 결과를 반환한다.

실제 컨텍스트 절감 수치

Anthropic 기준으로 GitHub, Slack, Sentry, Grafana, Splunk 다섯 MCP 서버를 연결하면 도구 정의만 약 55,000토큰이 된다. Tool Search로 특정 요청에 필요한 3~5개만 로드하면 85% 이상의 컨텍스트 절감이 가능하다. 10,000개 도구까지 defer_loading으로 등록할 수 있다.

Programmatic Tool Calling: 왕복 횟수와 토큰 비용을 동시에 줄이기

Tool Search가 도구 정의 로드를 줄인다면, Programmatic Tool Calling(PTC)은 도구 실행 왕복 횟수를 줄인다.

PTC의 핵심 아이디어: Claude가 도구를 하나씩 호출하지 않고, 도구를 호출하는 Python 코드를 작성한다. 이 코드가 코드 실행 샌드박스 안에서 실행되어 여러 도구를 한 번에 처리한다.

20명의 예산 초과 여부를 확인하는 예를 보자.

기존 방식: 직원 20명 → 20번 API 왕복 → 각 결과가 컨텍스트에 누적 → 최종 분석 시 수백 킬로바이트가 컨텍스트에 있음

PTC 방식: Claude가 Python 코드 한 조각 작성 → 코드가 20번 도구 호출을 배치로 실행 → 예산 초과자만 필터링해서 결과 반환 → Claude가 받는 것은 "초과한 직원 4명"뿐

설정 방법

PTC는 두 가지 설정이 필요하다.

첫째, code_execution_20260120 타입의 도구를 tools 배열에 추가한다.

{"type": "code_execution_20260120", "name": "code_execution"}

둘째, PTC로만 호출되어야 하는 도구에 allowed_callers를 지정한다.

{
  "name": "query_sales_db",
  "description": "영업 데이터베이스에서 SQL 쿼리를 실행합니다.",
  "input_schema": {...},
  "allowed_callers": ["code_execution_20260120"]
}

allowed_callers를 설정하면 해당 도구는 코드 실행 샌드박스에서만 호출 가능하다. Claude가 직접 호출하려 해도 API가 막는다.

성능 데이터

Anthropic이 공개한 수치는 명확하다.

• BrowseComp·DeepSearchQA 멀티스텝 검색 벤치마크에서 기본 검색 도구 위에 PTC 추가 시: 입력 토큰 24% 감소, 성능 11% 향상
• 75개 도구 프로젝트 관리 에이전트 벤치마크: 청구 입력 토큰 38% 감소, 작업 정확도는 동일
• 도구 10~49개 환경의 실제 API 트래픽: 일반적으로 20~40% 토큰 절감

코드 실행 샌드박스의 성격

PTC에 쓰이는 코드 실행 환경은 Python 샌드박스다. 중요한 제약이 있다.

• 파일시스템, 네트워크 직접 접근 불가
• 도구 호출은 반드시 allowed_callers로 허가된 것만
• 실행 결과 중 Claude에게 돌아오는 것은 코드가 명시적으로 반환한 것뿐

이 제약이 오히려 핵심 장점이다. 코드가 데이터를 필터·집계·가공해서 압축된 결과만 모델 컨텍스트로 전달하기 때문이다.

Tool Search + Programmatic Tool Calling 조합

두 기능은 독립적으로도 쓸 수 있지만, 함께 쓸 때 시너지가 크다.

1. Tool Search로 수천 개 도구 중 작업에 필요한 도구를 찾는다.
2. 찾은 도구를 PTC로 한 번에 배치 호출한다.
3. 결과를 코드 안에서 가공해서 압축된 형태로 반환한다.

MCP 서버와 함께 쓸 때는 개별 도구에 defer_loading: true를 붙이는 대신 mcp_toolset의 default_config에서 서버 단위로 설정한다.

한 가지 제약: defer_loading: true인 도구에는 cache_control을 붙일 수 없다. 캐시 분기점은 deferred가 아닌 도구에 두어야 한다.

운영자가 확인해야 할 것

1) allowed_callers 설정 여부

외부 시스템을 호출하는 도구(DB, API, 파일시스템)가 Claude에 의해 직접 호출되는 것이 아니라 코드 실행 샌드박스에서만 호출되어야 한다면, allowed_callers로 경로를 제한해야 한다. 설정하지 않으면 Claude가 직접 호출하는 기존 방식도 허용된다.

2) 비용 모델의 변화

PTC를 쓰면 청구 방식이 바뀐다. 모델 왕복이 줄면서 API 호출 횟수는 감소하지만, 코드 실행 컨테이너 사용 시간이 추가된다. Anthropic 기준 토큰 비용은 줄지만 코드 실행 비용이 발생하므로, 실제 절감 여부는 워크로드 특성에 따라 다르다.

3) 가용성 범위

PTC는 현재 Amazon Bedrock Converse API와 Google Cloud에서 지원되지 않는다. 클라우드 플랫폼별 가용성을 먼저 확인한다.

4) 도구 설명 품질이 더 중요해진다

Tool Search를 쓰면 도구 이름·설명·인수 설명이 검색 대상이 된다. 설명이 모호하거나 짧으면 Claude가 적절한 도구를 찾지 못할 수 있다.

좋은 설명 원칙:

• 서비스별 접두어 사용: github_, slack_, sentry_
• 도구가 해결하는 작업을 동사 중심으로 서술
• 중요 키워드를 설명 앞부분에 배치

도입 전 체크리스트

• [ ] 도구 수가 10개 이상이거나 도구 정의 총 토큰이 10k를 넘는지 확인한다.
• [ ] Tool Search Regex/BM25 중 워크로드에 맞는 변형을 선택한다.
• [ ] 자주 쓰는 3~5개 도구는 defer_loading 없이 즉시 로드 상태로 유지한다.
• [ ] 코드 실행 샌드박스에서만 호출되어야 할 도구에 allowed_callers 설정 여부를 검토한다.
• [ ] 실제 워크로드에서 토큰 절감 전후를 측정해 비교한다.
• [ ] MCP 서버 환경이라면 mcp_toolset에서 서버 단위 defer_loading을 설정한다.
• [ ] Amazon Bedrock 또는 Google Cloud 기반이라면 PTC 대신 Tool Search만 적용한다.

한 문장으로

Anthropic Advanced Tool Use는 도구 정의를 지연 로드하고(Tool Search), 도구 호출을 코드로 배치 처리해(Programmatic Tool Calling), 수백 킬로바이트가 되어야 할 컨텍스트를 수 줄로 압축하는 인프라 레이어다. 도구 수가 많아질수록, 반복 호출이 많아질수록 효과가 커진다.

References

• Introducing advanced tool use on the Claude Developer Platform (Anthropic Engineering): https://www.anthropic.com/engineering/advanced-tool-use
• Tool search tool — Claude Platform Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool
• Programmatic tool calling — Claude Platform Docs: https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling
• Effective context engineering for AI agents (Anthropic Engineering): https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents
• BrowseComp benchmark (arXiv): https://arxiv.org/abs/2504.12516
• Improved web search with dynamic filtering (Anthropic Blog): https://claude.com/blog/improved-web-search-with-dynamic-filtering
• liteLLM Anthropic Programmatic Tool Calling: https://docs.litellm.ai/docs/providers/anthropic_programmatic_tool_calling