Introducing advanced tool use on the Claude Developer Platform

생각 덩어리

수백·수천 개 툴을 넘나드는 에이전트 — 발견·실행·학습의 세 병목

The future of AI agents is one where models work seamlessly across hundreds or thousands of tools. An IDE assistant that integrates git operations, file manipulation, package managers, testing frameworks, and deployment pipelines.

Agents should discover and load tools on-demand, keeping only what's relevant for the current task.

Agents also need to learn correct tool usage from examples, not just schema definitions. JSON schemas define what's structurally valid, but can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.

For example, Claude for Excel uses Programmatic Tool Calling to read and modify spreadsheets with thousands of rows without overloading the model’s context window.

툴 정의가 먹어치우는 컨텍스트 — 대화 시작 전에 55K 토큰

That's 58 tools consuming approximately 55K tokens before the conversation even starts. Add more servers like Jira (which alone uses ~17K tokens) and you're quickly approaching 100K+ token overhead. At Anthropic, we've seen tool definitions consume 134K tokens before optimization.

But token cost isn't the only issue. The most common failures are wrong tool selection and incorrect parameters, especially when tools have similar names like notification-send-user vs. notification-send-channel.

Tool Search Tool — 필요한 툴만 온디맨드로, 85% 절감

Instead of loading all tool definitions upfront, the Tool Search Tool discovers tools on-demand. Claude only sees the tools it actually needs for the current task.

Total context consumption: ~8.7K tokens, preserving 95% of context window

This represents an 85% reduction in token usage while maintaining access to your full tool library. Internal testing showed significant accuracy improvements on MCP evaluations when working with large tool libraries. Opus 4 improved from 49% to 74%, and Opus 4.5 improved from 79.5% to 88.1% with Tool Search Tool enabled.

defer_loading — 핵심 툴만 상시 로드, prompt caching도 깨지지 않는다

You provide all your tool definitions to the API, but mark tools with defer_loading: true to make them discoverable on-demand. Deferred tools aren't loaded into Claude's context initially.

if Claude needs to interact with GitHub, it searches for "github," and only github.createPullRequest and github.listIssues get loaded—not your other 50+ tools from Slack, Jira, and Google Drive.

Tool Search Tool doesn't break prompt caching because deferred tools are excluded from the initial prompt entirely.

The Claude Developer Platform provides regex-based and BM25-based search tools out of the box, but you can also implement custom search tools using embeddings or other strategies.

도입 기준 — 검색 한 단계를 추가할 가치가 있는가

Like any architectural decision, enabling the Tool Search Tool involves trade-offs. The feature adds a search step before tool invocation, so it delivers the best ROI when the context savings and accuracy improvements outweigh additional latency.

쓸 때: 툴 정의 10K 토큰 초과, 툴 선택 정확도 문제, 멀티 서버 MCP, 툴 10개 이상. 덜 유익할 때: 툴 10개 미만, 모든 툴을 매 세션 쓰는 경우, 정의가 콤팩트한 경우.

전통적 툴 호출의 두 가지 문제 — 컨텍스트 오염과 추론 오버헤드

When Claude analyzes a 10MB log file for error patterns, the entire file enters its context window, even though Claude only needs a summary of error frequencies.

These intermediate results consume massive token budgets and can push important information out of the context window entirely.

A five tool workflow means five inference passes plus Claude parsing each result, comparing values, and synthesizing conclusions. This is both slow and error-prone.

Programmatic Tool Calling — 자연어 추론 대신 코드로 오케스트레이션

Instead of Claude requesting tools one at a time with each result being returned to its context, Claude writes code that calls multiple tools, processes their outputs, and controls what information actually enters its context window.

Claude excels at writing code and by letting it express orchestration logic in Python rather than through natural language tool invocations, you get more reliable, precise control flow. Loops, conditionals, data transformations, and error handling are all explicit in code rather than implicit in Claude's reasoning.

예산 초과 검사 사례 — 200KB 중간 데이터가 1KB 결과로, 토큰 37% 절감

"Q3 출장 예산을 초과한 팀원은?" — 전통 방식은 팀원 20명 × 경비 50~100건이 전부 컨텍스트로 들어온다. PTC에서는 Claude가 파이썬 스크립트 하나로 전체 워크플로를 짠다.

The script runs in the Code Execution tool (a sandboxed environment), pausing when it needs results from your tools. When you return tool results via the API, they're processed by the script rather than consumed by the model. The script continues executing, and Claude only sees the final output.

Claude's context receives only the final result: the two to three people who exceeded their budget. The 2,000+ line items, the intermediate sums, and the budget lookups do not affect Claude’s context, reducing consumption from 200KB of raw expense data to just 1KB of results.

Average usage dropped from 43,588 to 27,297 tokens, a 37% reduction on complex research tasks.

Internal knowledge retrieval improved from 25.6% to 28.5%; GIA benchmarks from 46.5% to 51.2%.

작동 구조 — caller 필드로 구분되고, 모델은 최종 출력만 본다

allowed_callers로 코드 실행을 옵트인하면 API가 툴 정의를 파이썬 함수로 변환한다. 코드가 툴을 부르면 caller 필드가 붙은 툴 요청이 오고, 결과는 모델이 아니라 샌드박스가 받는다.

You provide the result, which is processed in the Code Execution environment rather than Claude's context. This request-response cycle repeats for each tool call in the code.

When Claude orchestrates 20+ tool calls in a single code block, you eliminate 19+ inference passes. The API handles tool execution without returning to the model each time.

This is all Claude sees, not the 2000+ expense line items processed along the way.

PTC 도입 기준 — 집계만 필요할 때, 중간 데이터가 판단을 흐릴 때

• Processing large datasets where you only need aggregates or summaries
• Running multi-step workflows with three or more dependent tool calls
• Handling tasks where intermediate data shouldn't influence Claude's reasoning
• Running parallel operations across many items (checking 50 endpoints, for example)

덜 유익할 때: 단일 툴 호출, Claude가 모든 중간 결과를 직접 보고 추론해야 하는 작업, 응답이 작은 빠른 조회.

JSON Schema의 한계 — 구조는 정의해도 관례는 못 담는다

JSON Schema excels at defining structure–types, required fields, allowed enums–but it can't express usage patterns: when to include optional parameters, which combinations make sense, or what conventions your API expects.

Format ambiguity: Should due_date use "2024-11-06", "Nov 6, 2024", or "2024-11-06T00:00:00Z"?

ID conventions: Is reporter.id a UUID, "USR-12345", or just "12345"?

These ambiguities can lead to malformed tool calls and inconsistent parameter usage.

Tool Use Examples — 예시 세 개가 가르치는 패턴, 72%→90%

티켓 생성 툴에 풀 스펙(크리티컬 버그)·부분 스펙(기능 요청)·최소 스펙(제목만) 세 가지 input_examples를 넣으면, Claude는 스키마가 못 담는 관례를 읽어낸다.

Format conventions: Dates use YYYY-MM-DD, user IDs follow USR-XXXXX, labels use kebab-case

Optional parameter correlations: Critical bugs have full contact info + escalation with tight SLAs; feature requests have reporter but no contact/escalation; internal tasks have title only

In our own internal testing, tool use examples improved accuracy from 72% to 90% on complex parameter handling.

Tool Use Examples 도입 기준 — 예시도 토큰이다

Tool Use Examples add tokens to your tool definitions, so they’re most valuable when accuracy improvements outweigh the additional cost.

• Complex nested structures where valid JSON doesn't imply correct usage
• Tools with many optional parameters and inclusion patterns matter
• APIs with domain-specific conventions not captured in schemas
• Similar tools where examples clarify which one to use (e.g., create_ticket vs create_incident)

덜 유익할 때: 사용법이 자명한 단일 파라미터 툴, URL·이메일처럼 Claude가 이미 아는 표준 포맷, JSON Schema 제약으로 처리하는 게 나은 검증 문제.

병목부터 하나씩 — 세 기능은 상호보완

Not every agent needs to use all three features for a given task. Start with your biggest bottleneck:

• Context bloat from tool definitions → Tool Search Tool
• Large intermediate results polluting context → Programmatic Tool Calling
• Parameter errors and malformed calls → Tool Use Examples

They're complementary: Tool Search Tool ensures the right tools are found, Programmatic Tool Calling ensures efficient execution, and Tool Use Examples ensure correct invocation.

운영 팁 — 이름은 검색되게, 반환 포맷은 문서로, 예시는 리얼하게

Tool search matches against names and descriptions, so clear, descriptive definitions improve discovery accuracy.

Keep your three to five most-used tools always loaded, defer the rest. This balances immediate access for common operations with on-demand discovery for everything else.

Since Claude writes code to parse tool outputs, document return formats clearly. This helps Claude write correct parsing logic

Use realistic data (real city names, plausible prices, not "string" or "value")

함수 호출에서 지능적 오케스트레이션으로

These features move tool use from simple function calling toward intelligent orchestration. As agents tackle more complex workflows spanning dozens of tools and large datasets, dynamic discovery, efficient execution, and reliable invocation become foundational.

(베타 헤더 advanced-tool-use-2025-11-20 으로 활성화. 원문 말미에 Tool Search Tool·Programmatic Tool Calling·Tool Use Examples 각각의 문서와 쿡북 링크, 그리고 Cloudflare Code Mode 등 영감을 받은 생태계 작업들에 대한 감사가 이어진다.)