Claude Developer Platform의 Anthropic 고급 도구 사용: 도구 검색 도구, 프로그래매틱 도구 호출, 도구 사용 예시

Anthropic은 Claude Developer Platform에서 세 가지 베타 기능 — 도구 검색 도구, 프로그래매틱 도구 호출, 도구 사용 예시 — 을 출시했습니다. 이 기능들은 Claude가 컨텍스트 창을 소진하지 않고도 매우 큰 도구 라이브러리로 작업할 수 있도록 설계되었습니다. 이 회사는 이러한 기능 덕분에 기존 도구 사용 패턴으로는 불가능했던 내부 빌드가 가능해졌다고 밝혔으며, 여기에는 프로그래매틱 도구 호출을 사용하여 수천 개의 행이 있는 스프레드시트를 읽고 수정하는 Claude for Excel도 포함됩니다.

Anthropic이 해결하려는 문제

Anthropic은 수백 또는 수천 개의 도구를 원활하게 작동하는 에이전트를 목표로 제시합니다. 예를 들어 git 작업, 파일 조작, 패키지 관리자, 테스트 프레임워크, 배포 파이프라인을 통합하는 IDE 어시스턴트, 또는 Slack, GitHub, Google Drive, Jira, 회사 데이터베이스, 수십 개의 MCP 서버를 동시에 연결하는 운영 코디네이터가 그 예입니다.

현재 이를 막는 세 가지 제약이 있습니다.

  • 도구 정의로 인한 컨텍스트 비대. 도구 결과와 정의는 에이전트가 요청을 읽기 전에 50,000개 이상의 토큰을 소비할 수 있습니다. 에이전트는 현재 작업에 관련된 항목만 유지하면서 필요에 따라 도구를 발견하고 로드해야 합니다.
  • 자연어 도구 호출로 인한 추론 오버헤드. 각 호출은 전체 추론 패스를 필요로 하며, 중간 결과는 유용 여부와 관계없이 컨텍스트에 쌓입니다. 코드는 루프, 조건문, 데이터 변환과 같은 오케스트레이션 로직에 자연스럽게 적합합니다.
  • 사용 지식에 대한 스키마 제한. JSON 스키마는 구조적으로 유효한 것을 정의하지만, 선택적 매개변수를 포함해야 하는 시기, 어떤 조합이 의미가 있는지, API가 기대하는 규칙을 표현할 수 없습니다.

도구 검색 도구: 온디맨드 도구 발견

도구 검색 도구는 Claude가 검색 도구를 사용하여 컨텍스트 창을 소비하지 않고도 수천 개의 도구에 액세스할 수 있게 합니다. 모든 도구 정의를 미리 로드하는 대신, Claude는 현재 작업에 실제로 필요한 도구만 볼 수 있습니다.

모든 도구를 미리 로드하는 토큰 비용

Anthropic은 5개 서버 MCP 설정으로 문제를 설명합니다.

서버 도구 대략적인 토큰 수
GitHub 35 ~26K
Slack 11 ~21K
Sentry 5 ~3K
Grafana 5 ~3K
Splunk 2 ~2K

대화가 시작되기 전에 약 55K 토큰을 소비하는 58개의 도구입니다. Jira(단독으로 약 ~17K 토큰 사용)와 같은 서버를 추가하면 오버헤드가 100K+ 토큰으로 증가합니다. Anthropic은 최적화 전에 도구 정의가 134K 토큰을 소비하는 것을 목격했다고 보고합니다.

토큰 비용만이 문제는 아닙니다. Anthropic은 가장 흔한 실패가 잘못된 도구 선택과 잘못된 매개변수라고 밝히며, 특히 notification-send-user 대 notification-send-channel과 같이 이름이 유사한 도구에서 그렇습니다.

도구 검색 도구가 보존하는 컨텍스트의 양

Anthropic은 도구 검색 도구가 기존 Claude의 접근 방식의 122,800 토큰과 비교하여 191,300 토큰의 컨텍스트를 보존한다고 보고합니다.

기존 접근 방식:

  • 모든 도구 정의를 미리 로드(50개 이상의 MCP 도구에 대해 ~72K 토큰)
  • 대화 기록과 시스템 프롬프트가 나머지 공간을 차지하기 위해 경쟁
  • 작업이 시작되기 전 총 컨텍스트 소비: ~77K 토큰

도구 검색 도구 사용 시:

  • 도구 검색 도구만 미리 로드(~500 토큰)
  • 필요에 따라 도구 발견(3-5개의 관련 도구, ~3K 토큰)
  • 총 컨텍스트 소비: ~8.7K 토큰, 컨텍스트 창의 95% 보존

Anthropic은 이를 전체 도구 라이브러리에 대한 액세스를 유지하면서 토큰 사용량 85% 감소로 설명합니다.

MCP 평가의 정확도 향상

Anthropic은 대규모 도구 라이브러리로 작업할 때 MCP 평가에서 상당한 정확도 향상을 보고합니다.

  • Opus 4: 49%에서 74%로 향상
  • Opus 4.5: 79.5%에서 88.1%로 향상

도구 검색 도구 작동 방식

API에 모든 도구 정의를 제공하지만 defer_loading: true로 표시하여 필요에 따라 검색 가능하게 만듭니다. 지연된 도구는 처음에 Claude의 컨텍스트에 로드되지 않습니다. Claude는 도구 검색 도구 자체와 defer_loading: false로 표시된 도구(가장 중요하고 자주 사용되는 도구)만 볼 수 있습니다.

Claude가 특정 기능이 필요할 때 관련 도구를 검색합니다. 도구 검색 도구는 일치하는 도구에 대한 참조를 반환하고, 이는 Claude의 컨텍스트에서 전체 정의로 확장됩니다. 예를 들어 Claude가 GitHub와 상호 작용해야 하는 경우 "github"를 검색하고 github.createPullRequest와 github.listIssues만 로드됩니다. Slack, Jira, Google Drive의 다른 50개 이상의 도구는 로드되지 않습니다.

MCP 서버의 경우 전체 서버를 지연시키면서 특정 고사용 도구는 로드된 상태로 유지할 수 있습니다.

Claude Developer Platform은 기본적으로 정규식 기반 및 BM25 기반 검색 도구를 제공하며, 임베딩이나 다른 전략을 사용하여 사용자 정의 검색 도구를 구현할 수도 있습니다.

프롬프트 캐싱 참고: 도구 검색 도구는 지연된 도구가 초기 프롬프트에서 완전히 제외되므로 프롬프트 캐싱을 깨지 않습니다. 도구는 Claude가 검색한 후에만 컨텍스트에 추가되므로 시스템 프롬프트와 핵심 도구 정의는 캐시 가능한 상태로 유지됩니다.

도구 검색 도구가 효과적인 경우

Anthropic은 이 기능이 도구 호출 전에 검색 단계를 추가하므로, 컨텍스트 절약과 정확도 향상이 추가 대기 시간보다 클 때 가장 좋은 효과를 발휘한다고 설명합니다.

다음과 같은 경우에 사용하세요:

  • 도구 정의가 >10K 토큰을 소비하는 경우
  • 도구 선택 정확도 문제가 발생하는 경우
  • 여러 서버를 사용하는 MCP 기반 시스템을 구축하는 경우
  • 10개 이상의 도구를 사용할 수 있는 경우

효과가 적은 경우:

  • 도구 라이브러리가 작은 경우(<10개 도구)
  • 모든 도구가 모든 세션에서 자주 사용되는 경우
  • 도구 정의가 간결한 경우

프로그래매틱 도구 호출: 코드에서 도구 오케스트레이션

프로그래매틱 도구 호출은 Claude가 코드 실행 환경에서 도구를 호출할 수 있게 하여 모델의 컨텍스트 창에 미치는 영향을 줄입니다. Claude는 각 결과를 컨텍스트에 반환하면서 한 번에 하나씩 도구를 요청하는 대신, 여러 도구를 호출하고 출력을 처리하며 실제로 컨텍스트 창에 들어가는 정보를 제어하는 코드를 작성합니다.

기존 도구 호출의 두 가지 문제

Anthropic은 워크플로가 더 복잡해짐에 따라 두 가지 근본적인 문제를 식별합니다.

  • 중간 결과로 인한 컨텍스트 오염. Claude가 10MB 로그 파일에서 오류 패턴을 분석할 때, 오류 빈도 요약만 필요한 경우에도 전체 파일이 컨텍스트 창에 들어갑니다. 여러 테이블에서 고객 데이터를 가져올 때 관련성과 무관하게 모든 레코드가 컨텍스트에 누적됩니다.
  • 추론 오버헤드와 수동 합성. 각 도구 호출은 전체 모델 추론 패스를 필요로 합니다. 결과를 받은 후 Claude는 관련 정보를 추출하고, 조각이 어떻게 맞는지 추론하고, 다음에 무엇을 할지 결정해야 합니다. 5개 도구 워크플로는 각 결과를 구문 분석하고 값을 비교하며 결론을 종합하는 Claude와 함께 5번의 추론 패스를 의미합니다.

작업 예시: Q3 여행 예산 준수 여부

Anthropic은 "Q3 여행 예산을 초과한 팀원은 누구입니까?"라는 작업을 세 가지 도구로 다룹니다.

  • get_team_members(department) — ID와 레벨이 있는 팀원 목록 반환
  • get_expenses(user_id, quarter) — 사용자의 비용 라인 항목 반환
  • get_budget_by_level(level) — 직원 레벨의 예산 한도 반환

기존 접근 방식: 팀원(20명)을 가져옵니다. 각 사람에 대해 Q3 비용을 가져옵니다(20번의 도구 호출, 각각 항공편, 호텔, 식사, 영수증을 포함한 50-100개의 라인 항목 반환). 직원 레벨별 예산 한도를 가져옵니다. 이 모든 것이 Claude의 컨텍스트에 들어갑니다 — 2,000개 이상의 비용 라인 항목(50KB 이상) — Claude는 각 사람의 비용을 수동으로 합산하고, 예산을 찾아보고, 비용과 예산 한도를 비교해야 하며, 모델에 더 많은 왕복이 발생합니다.

프로그래매틱 도구 호출 사용 시: Claude는 전체 워크플로를 오케스트레이션하는 Python 스크립트를 작성합니다. 스크립트는 코드 실행 도구(샌드박스 환경)에서 실행되며, 도구 결과가 필요할 때 일시 중지됩니다. API를 통해 도구 결과를 반환하면 모델이 소비하는 것이 아니라 스크립트가 처리합니다. 스크립트는 계속 실행되고 Claude는 최종 출력(예산을 초과한 2-3명)만 봅니다. Anthropic은 이를 통해 200KB의 원시 비용 데이터를 1KB의 결과로 줄일 수 있다고 보고합니다.

측정된 효율성 향상

  • 토큰 절약: 복잡한 연구 작업에서 평균 사용량이 43,588에서 27,297 토큰으로 감소, 37% 감소.
  • 지연 시간 감소: 각 API 왕복은 모델 추론(수백 밀리초에서 수 초)을 필요로 합니다. 단일 코드 블록에서 20개 이상의 도구 호출을 오케스트레이션하면 19개 이상의 추론 패스가 제거됩니다. API가 매번 모델로 돌아가지 않고 도구 실행을 처리하기 때문입니다.
  • 정확도 향상: 내부 지식 검색이 25.6%에서 28.5%로 향상; GIA 벤치마크가 46.5%에서 51.2%로 향상.

프로그래매틱 도구 호출 작동 방식

  1. 코드에서 호출 가능한 도구로 표시. 도구에 code_execution을 추가하고 allowed_callers를 설정하여 프로그래매틱 실행을 위한 도구를 선택합니다. API는 이러한 도구 정의를 Claude가 호출할 수 있는 Python 함수로 변환합니다.
  2. Claude가 오케스트레이션 코드를 작성. Claude는 한 번에 하나씩 도구를 요청하는 대신 Python 코드를 생성합니다.
  3. 도구가 Claude의 컨텍스트에 영향을 주지 않고 실행. 코드가 get_expenses()와 같은 도구를 호출하면 caller 필드가 있는 도구 요청을 받습니다. 결과를 제공하면 코드 실행 환경에서 처리되며 Claude의 컨텍스트에는 들어가지 않습니다. 이 요청-응답 주기는 코드의 각 도구 호출에 대해 반복됩니다.
  4. 최종 출력만 컨텍스트에 들어감. 코드 실행이 완료되면 코드의 결과만 Claude에 반환됩니다. 처리 과정에서 발생한 2,000개 이상의 비용 라인 항목은 반환되지 않습니다.

프로그래매틱 도구 호출이 효과적인 경우

다음과 같은 경우에 가장 효과적입니다:

  • 집계 또는 요약만 필요한 대규모 데이터 세트를 처리하는 경우
  • 세 개 이상의 의존적인 도구 호출이 있는 다단계 워크플로를 실행하는 경우
  • Claude가 보기 전에 도구 결과를 필터링, 정렬 또는 변환해야 하는 경우
  • 중간 데이터가 Claude의 추론에 영향을 주지 않아야 하는 작업을 처리하는 경우
  • 많은 항목에 대해 병렬 작업을 실행하는 경우(예: 50개 엔드포인트 확인)

효과가 적은 경우:

  • 간단한 단일 도구 호출을 하는 경우
  • Claude가 모든 중간 결과를 보고 추론해야 하는 작업을 하는 경우
  • 응답이 작은 빠른 조회를 실행하는 경우

도구 사용 예시: 스키마가 표현할 수 없는 규칙 교육

도구 사용 예시는 주어진 도구를 효과적으로 사용하는 방법을 보여주는 보편적인 표준을 제공합니다. 도구 정의에 샘플 도구 호출을 직접 제공할 수 있으므로, Claude는 스키마에만 의존하지 않고 구체적인 사용 패턴을 학습합니다.

JSON 스키마가 남기는 모호성

Anthropic은 지원 티켓 API를 사용하여 설명합니다. 스키마는 유효한 것을 정의하지만 중요한 질문에 대한 답을 남깁니다.

  • 형식 모호성: due_date는 "2024-11-06", "Nov 6, 2024", 또는 "2024-11-06T00:00:00Z"를 사용해야 합니까?
  • ID 규칙: reporter.id는 UUID, "USR-12345", 또는 그냥 "12345"입니까?
  • 중첩 구조 사용: Claude는 언제 reporter.contact를 채워야 합니까?
  • 매개변수 상관관계: escalation.level과 escalation.sla_hours는 우선 순위와 어떤 관련이 있습니까?

이러한 모호성은 잘못된 도구 호출과 일관되지 않은 매개변수 사용으로 이어질 수 있습니다.

Claude가 예시에서 배우는 것

지원 티켓 API의 세 가지 샘플 호출에서 Anthropic은 Claude가 다음을 학습한다고 밝힙니다.

  • 형식 규칙: 날짜는 YYYY-MM-DD, 사용자 ID는 USR-XXXXX, 레이블은 케밥-케이스 사용
  • 중첩 구조 패턴: 중첩된 contact 객체로 reporter 객체를 구성하는 방법
  • 선택적 매개변수 상관관계: 치명적인 버그는 전체 연락처 정보와 긴밀한 SLA의 에스컬레이션이 있고, 기능 요청은 리포터가 있지만 연락처나 에스컬레이션이 없으며, 내부 작업은 제목만 있습니다.

Anthropic의 내부 테스트에서 도구 사용 예시는 복잡한 매개변수 처리에서 정확도를 72%에서 90%로 향상시켰습니다.

도구 사용 예시가 효과적인 경우

Anthropic은 예시가 도구 정의에 토큰을 추가하므로 정확도 향상이 추가 비용보다 클 때 가장 가치가 있다고 설명합니다.

다음과 같은 경우에 가장 효과적입니다:

  • 유효한 JSON이 올바른 사용을 의미하지 않는 복잡한 중첩 구조
  • 포함 패턴이 중요한 많은 선택적 매개변수가 있는 도구
  • 스키마에 캡처되지 않은 도메인별 규칙이 있는 API
  • 예시가 어떤 도구를 사용할지 명확히 하는 유사한 도구(예: create_ticket 대 create_incident)

효과가 적은 경우:

  • 사용법이 명확한 간단한 단일 매개변수 도구
  • Claude가 이미 이해하는 URL 또는 이메일과 같은 표준 형식
  • JSON 스키마 제약 조건으로 더 잘 처리되는 검증 문제

세 가지 기능을 결합하는 모범 사례

Anthropic은 세 가지 기능을 모두 한 번에 채택하기보다 가장 큰 병목 현상부터 시작할 것을 권장합니다.

  • 도구 정의로 인한 컨텍스트 비대 → 도구 검색 도구
  • 컨텍스트를 오염시키는 대규모 중간 결과 → 프로그래매틱 도구 호출
  • 매개변수 오류 및 잘못된 호출 → 도구 사용 예시

이 기능들은 상호 보완적입니다. 도구 검색 도구는 올바른 도구를 찾고, 프로그래매틱 도구 호출은 효율적인 실행을 보장하며, 도구 사용 예시는 올바른 호출을 보장합니다.

더 나은 발견을 위한 도구 검색 도구 설정

도구 검색은 이름과 설명과 일치하므로 명확하고 설명적인 정의가 발견 정확도를 향상시킵니다. Anthropic은 Claude가 사용 가능한 것을 알 수 있도록 시스템 프롬프트 지침을 추가하고, 가장 많이 사용하는 3-5개 도구는 항상 로드하고 나머지는 지연할 것을 권장합니다. 일반적인 작업에 대한 즉시 액세스와 나머지에 대한 온디맨드 발견의 균형을 유지합니다.

올바른 실행을 위한 프로그래매틱 도구 호출 설정

Claude가 도구 출력을 구문 분석하는 코드를 작성하므로, 반환 형식을 명확하게 문서화하여 Claude가 올바른 구문 분석 논리를 작성하도록 해야 합니다. 프로그래매틱 오케스트레이션의 이점이 가장 큰 도구는 병렬로 실행할 수 있는(독립적인 작업) 도구와 재시도해도 안전한(멱등성) 작업입니다.

매개변수 정확성을 위한 도구 사용 예시 설정

Anthropic의 예시 작성 지침:

  • 현실적인 데이터 사용(실제 도시 이름, 그럴듯한 가격, "string" 또는 "value" 사용 금지)
  • 최소, 부분, 전체 지정 패턴의 다양성 보여주기
  • 간결하게 유지: 도구당 1-5개 예시
  • 모호성에 집중 — 스키마에서 올바른 사용이 명확하지 않은 경우에만 예시 추가

사용 가능 여부 및 시작하기

세 가지 기능은 베타로 제공됩니다. 활성화하려면 베타 헤더를 추가하고 필요한 도구를 포함하세요. Anthropic은 각 기능에 대한 문서와 쿡북 노트북을 안내합니다.

  • 도구 검색 도구 — 임베딩을 사용한 도구 검색에 대한 문서 및 쿡북 노트북
  • 프로그래매틱 도구 호출 — PTC에 대한 문서 및 쿡북 노트북
  • 도구 사용 예시 — 도구 사용 구현에 대한 문서

Anthropic은 이러한 기능을 도구 사용을 "단순한 함수 호출에서 지능적인 오케스트레이션으로" 이동시키는 것으로 설명하며, 에이전트가 수십 개의 도구와 대규모 데이터 세트를 아우르는 더 복잡한 워크플로를 처리함에 따라 동적 발견, 효율적인 실행, 안정적인 호출이 기본이 된다고 주장합니다.

Sources