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. An operations coordinator that connects Slack, GitHub, Google Drive, Jira, company databases, and dozens of MCP servers simultaneously.

Будущее ИИ-агентов — это мир, где модели бесшовно работают с сотнями и тысячами инструментов. Ассистент в IDE, интегрирующий git-операции, работу с файлами, пакетные менеджеры, фреймворки тестирования и пайплайны деплоя. Координатор операций, одновременно подключённый к Slack, GitHub, Google Drive, Jira, корпоративным базам данных и десяткам MCP-серверов.

To build effective agents, they need to work with unlimited tool libraries without stuffing every definition into context upfront. Our blog article on using code execution with MCP discussed how tool results and definitions can sometimes consume 50,000+ tokens before an agent reads a request. Agents should discover and load tools on-demand, keeping only what's relevant for the current task.

Чтобы создавать эффективных агентов, им нужна возможность работать с неограниченными библиотеками инструментов, не загружая все определения в контекст заранее. В нашей статье об использовании выполнения кода с MCP мы обсуждали, как результаты и определения инструментов могут потреблять более 50 000 токенов ещё до того, как агент прочитает запрос. Агенты должны обнаруживать и загружать инструменты по требованию, сохраняя лишь то, что релевантно текущей задаче.

Agents also need the ability to call tools from code. When using natural language tool calling, each invocation requires a full inference pass, and intermediate results pile up in context whether they're useful or not. Code is a natural fit for orchestration logic, such as loops, conditionals, and data transformations. Agents need the flexibility to choose between code execution and inference based on the task at hand.

Агентам также нужна возможность вызывать инструменты из кода. При использовании вызова инструментов на естественном языке каждый вызов требует полного прохода инференса, а промежуточные результаты накапливаются в контексте вне зависимости от их полезности. Код — естественный выбор для логики оркестрации: циклов, условий и преобразований данных. Агентам нужна гибкость в выборе между выполнением кода и инференсом в зависимости от задачи.

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.

Агентам также нужно учиться правильному использованию инструментов на примерах, а не только по определениям схем. JSON-схемы определяют, что структурно допустимо, но не могут выразить паттерны использования: когда включать опциональные параметры, какие комбинации имеют смысл или какие конвенции ожидает ваш API.

Today, we're releasing three features that make this possible:

Сегодня мы выпускаем три функции, которые делают это возможным:

Tool Search Tool — позволяет Claude использовать поисковые инструменты для доступа к тысячам инструментов без расходования контекстного окнаProgrammatic Tool Calling — позволяет Claude вызывать инструменты в среде выполнения кода, снижая нагрузку на контекстное окно моделиTool Use Examples — предоставляет универсальный стандарт для демонстрации эффективного использования конкретного инструмента

In internal testing, we’ve found these features have helped us build things that wouldn’t have been possible with conventional tool use patterns. 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.

Во внутреннем тестировании мы обнаружили, что эти функции помогли нам создавать то, что было бы невозможно с обычными паттернами использования инструментов. Например, Claude for Excel использует Programmatic Tool Calling для чтения и модификации электронных таблиц с тысячами строк без перегрузки контекстного окна модели.

Based on our experience, we believe these features open up new possibilities for what you can build with Claude.

Основываясь на нашем опыте, мы считаем, что эти функции открывают новые возможности для того, что вы можете создать с Claude.

Tool Search Tool

Tool Search Tool

The challenge

Проблема

MCP tool definitions provide important context, but as more servers connect, those tokens can add up. Consider a five-server setup:

Определения MCP-инструментов предоставляют важный контекст, но по мере подключения всё большего числа серверов эти токены накапливаются. Рассмотрим конфигурацию из пяти серверов:

GitHub: 35 инструментов (~26K токенов)Slack: 11 инструментов (~21K токенов)Sentry: 5 инструментов (~3K токенов)Grafana: 5 инструментов (~3K токенов)Splunk: 2 инструмента (~2K токенов)

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.

Это 58 инструментов, потребляющих около 55K токенов ещё до начала разговора. Добавьте больше серверов, таких как Jira (который сам по себе использует ~17K токенов), и вы быстро приближаетесь к 100K+ токенов накладных расходов. В Anthropic мы наблюдали потребление 134K токенов определениями инструментов до оптимизации.

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.

Но стоимость токенов — не единственная проблема. Наиболее частые ошибки — неправильный выбор инструмента и некорректные параметры, особенно когда инструменты имеют похожие названия, такие как notification-send-user и notification-send-channel.

Our solution

Наше решение

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.

Вместо загрузки всех определений инструментов заранее, Tool Search Tool обнаруживает инструменты по требованию. Claude видит только те инструменты, которые ему действительно нужны для текущей задачи.

Traditional approach:

Традиционный подход:

Все определения инструментов загружаются заранее (~72K токенов для 50+ MCP-инструментов)История разговора и системный промпт конкурируют за оставшееся пространствоОбщее потребление контекста: ~77K токенов до начала какой-либо работы

With the Tool Search Tool:

С Tool Search Tool:

Заранее загружается только Tool Search Tool (~500 токенов)Инструменты обнаруживаются по требованию по мере необходимости (3–5 релевантных инструментов, ~3K токенов)Общее потребление контекста: ~8,7K токенов, сохраняя 95% контекстного окна

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.

Это означает сокращение использования токенов на 85% при сохранении доступа ко всей библиотеке инструментов. Внутреннее тестирование показало значительное улучшение точности на MCP-оценках при работе с большими библиотеками инструментов. Opus 4 улучшил результат с 49% до 74%, а Opus 4.5 — с 79,5% до 88,1% при включённом Tool Search Tool.

How the Tool Search Tool works

Как работает Tool Search Tool

The Tool Search Tool lets Claude dynamically discover tools instead of loading all definitions upfront. 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. Claude only sees the Tool Search Tool itself plus any tools with defer_loading: false (your most critical, frequently-used tools).

Tool Search Tool позволяет Claude динамически обнаруживать инструменты вместо загрузки всех определений заранее. Вы предоставляете все определения инструментов через API, но помечаете инструменты как defer_loading: true, чтобы сделать их доступными для обнаружения по требованию. Отложенные инструменты не загружаются в контекст Claude изначально. Claude видит только сам Tool Search Tool и инструменты с defer_loading: false (ваши самые важные, часто используемые инструменты).

When Claude needs specific capabilities, it searches for relevant tools. The Tool Search Tool returns references to matching tools, which get expanded into full definitions in Claude's context.

Когда Claude нужны определённые возможности, он ищет подходящие инструменты. Tool Search Tool возвращает ссылки на подходящие инструменты, которые разворачиваются в полные определения в контексте Claude.

For example, 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.

Например, если Claude нужно взаимодействовать с GitHub, он ищет «github», и загружаются только github.createPullRequest и github.listIssues — а не остальные 50+ инструментов из Slack, Jira и Google Drive.

This way, Claude has access to your full tool library while only paying the token cost for tools it actually needs.

Таким образом, Claude имеет доступ ко всей вашей библиотеке инструментов, расходуя токены только на те инструменты, которые ему действительно нужны.

Prompt caching note: Tool Search Tool doesn't break prompt caching because deferred tools are excluded from the initial prompt entirely. They're only added to context after Claude searches for them, so your system prompt and core tool definitions remain cacheable.

Примечание о кэшировании промптов: Tool Search Tool не нарушает кэширование промптов, поскольку отложенные инструменты полностью исключены из начального промпта. Они добавляются в контекст только после того, как Claude их найдёт, поэтому ваш системный промпт и основные определения инструментов остаются кэшируемыми.

Implementation:

Реализация:

{ "tools": [ // Include a tool search tool (regex, BM25, or custom) {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, // Mark tools for on-demand discovery { "name": "github.createPullRequest", "description": "Create a pull request", "input_schema": {...}, "defer_loading": true } // ... hundreds more deferred tools with defer_loading: true ] }

{ "tools": [ // Включите инструмент поиска (regex, BM25 или пользовательский) {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, // Пометьте инструменты для обнаружения по требованию { "name": "github.createPullRequest", "description": "Create a pull request", "input_schema": {...}, "defer_loading": true } // ... сотни других отложенных инструментов с defer_loading: true ] }

For MCP servers, you can defer loading entire servers while keeping specific high-use tools loaded:

Для MCP-серверов можно отложить загрузку целых серверов, сохраняя определённые часто используемые инструменты загруженными:

{ "type": "mcp_toolset", "mcp_server_name": "google-drive", "default_config": {"defer_loading": true}, # defer loading the entire server "configs": { "search_files": { "defer_loading": false } // Keep most used tool loaded } }

{ "type": "mcp_toolset", "mcp_server_name": "google-drive", "default_config": {"defer_loading": true}, # отложить загрузку всего сервера "configs": { "search_files": { "defer_loading": false } // Сохранить наиболее используемый инструмент загруженным } }

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.

Платформа разработчиков Claude предоставляет встроенные поисковые инструменты на основе regex и BM25, но вы также можете реализовать собственные поисковые инструменты с использованием эмбеддингов или других стратегий.

When to use the Tool Search Tool

Когда использовать Tool Search Tool

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.

Как и любое архитектурное решение, включение Tool Search Tool предполагает компромиссы. Функция добавляет шаг поиска перед вызовом инструмента, поэтому она приносит наибольший ROI, когда экономия контекста и улучшение точности перевешивают дополнительную задержку.

Use it when:

Используйте, когда:

Определения инструментов потребляют >10K токеновВозникают проблемы с точностью выбора инструментовВы строите MCP-системы с несколькими серверамиДоступно 10+ инструментов

Less beneficial when:

Менее полезно, когда:

Небольшая библиотека инструментов (<10 инструментов)Все инструменты используются часто в каждой сессииОпределения инструментов компактны

Programmatic Tool Calling

Programmatic Tool Calling

The challenge

Проблема

Traditional tool calling creates two fundamental problems as workflows become more complex:

Традиционный вызов инструментов создаёт две фундаментальные проблемы по мере усложнения рабочих процессов:

Загрязнение контекста промежуточными результатами: когда Claude анализирует лог-файл размером 10 МБ на предмет паттернов ошибок, весь файл попадает в контекстное окно, хотя Claude нужна лишь сводка частотности ошибок. При получении данных о клиентах из нескольких таблиц каждая запись накапливается в контексте вне зависимости от релевантности. Эти промежуточные результаты потребляют огромные бюджеты токенов и могут вытеснить важную информацию из контекстного окна.Накладные расходы на инференс и ручной синтез: каждый вызов инструмента требует полного прохода инференса модели. После получения результатов Claude должен «просмотреть» данные для извлечения релевантной информации, определить связи между частями и решить, что делать дальше — всё через обработку естественного языка. Рабочий процесс из пяти инструментов означает пять проходов инференса плюс парсинг каждого результата, сравнение значений и синтез выводов со стороны Claude. Это медленно и подвержено ошибкам.

Our solution

Наше решение

Programmatic Tool Calling enables Claude to orchestrate tools through code rather than through individual API round-trips. 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.

Programmatic Tool Calling позволяет Claude оркестрировать инструменты через код, а не через отдельные API-запросы. Вместо того чтобы Claude запрашивал инструменты по одному с возвратом каждого результата в контекст, Claude пишет код, который вызывает несколько инструментов, обрабатывает их выходные данные и контролирует, какая информация фактически попадает в контекстное окно.

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.

Claude отлично пишет код, и позволяя ему выражать логику оркестрации на Python, а не через вызовы инструментов на естественном языке, вы получаете более надёжное и точное управление потоком выполнения. Циклы, условия, преобразования данных и обработка ошибок — всё это явно выражено в коде, а не подразумевается в рассуждениях Claude.

Example: Budget compliance check

Пример: проверка соответствия бюджету

Consider a common business task: "Which team members exceeded their Q3 travel budget?"

Рассмотрим типичную бизнес-задачу: «Кто из членов команды превысил бюджет на командировки за Q3?»

You have three tools available:

У вас есть три инструмента:

get_team_members(department) — возвращает список членов команды с ID и уровнямиget_expenses(user_id, quarter) — возвращает статьи расходов пользователяget_budget_by_level(level) — возвращает лимиты бюджета для уровня сотрудника

Traditional approach:

Традиционный подход:

Получить список команды → 20 человекДля каждого получить расходы за Q3 → 20 вызовов инструментов, каждый возвращает 50–100 статей (перелёты, отели, питание, чеки)Получить лимиты бюджета по уровню сотрудникаВсё это попадает в контекст Claude: 2000+ статей расходов (50 КБ+)Claude вручную суммирует расходы каждого, находит бюджет, сравнивает расходы с лимитамиБольше обращений к модели, значительное потребление контекста

With Programmatic Tool Calling:

С Programmatic Tool Calling:

Instead of each tool result returning to Claude, Claude writes a Python script that orchestrates the entire workflow. 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, Claude пишет Python-скрипт, оркестрирующий весь рабочий процесс. Скрипт выполняется в среде Code Execution (изолированная песочница), приостанавливаясь, когда ему нужны результаты от ваших инструментов. Когда вы возвращаете результаты инструментов через API, они обрабатываются скриптом, а не потребляются моделью. Скрипт продолжает выполнение, и Claude видит только конечный результат.

Here's what Claude's orchestration code looks like for the budget compliance task:

Вот как выглядит код оркестрации Claude для задачи проверки бюджета:

team = await get_team_members("engineering") # Fetch budgets for each unique level levels = list(set(m["level"] for m in team)) budget_results = await asyncio.gather(*[ get_budget_by_level(level) for level in levels ]) # Create a lookup dictionary: {"junior": budget1, "senior": budget2, ...} budgets = {level: budget for level, budget in zip(levels, budget_results)} # Fetch all expenses in parallel expenses = await asyncio.gather(*[ get_expenses(m["id"], "Q3") for m in team ]) # Find employees who exceeded their travel budget exceeded = [] for member, exp in zip(team, expenses): budget = budgets[member["level"]] total = sum(e["amount"] for e in exp) if total > budget["travel_limit"]: exceeded.append({ "name": member["name"], "spent": total, "limit": budget["travel_limit"] }) print(json.dumps(exceeded))

team = await get_team_members("engineering") # Fetch budgets for each unique level levels = list(set(m["level"] for m in team)) budget_results = await asyncio.gather(*[ get_budget_by_level(level) for level in levels ]) # Create a lookup dictionary: {"junior": budget1, "senior": budget2, ...} budgets = {level: budget for level, budget in zip(levels, budget_results)} # Fetch all expenses in parallel expenses = await asyncio.gather(*[ get_expenses(m["id"], "Q3") for m in team ]) # Find employees who exceeded their travel budget exceeded = [] for member, exp in zip(team, expenses): budget = budgets[member["level"]] total = sum(e["amount"] for e in exp) if total > budget["travel_limit"]: exceeded.append({ "name": member["name"], "spent": total, "limit": budget["travel_limit"] }) print(json.dumps(exceeded))

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.

В контекст Claude попадает только конечный результат: два-три человека, превысивших бюджет. 2000+ статей расходов, промежуточные суммы и запросы бюджетов не влияют на контекст Claude, сокращая потребление с 200 КБ необработанных данных о расходах до всего 1 КБ результатов.

The efficiency gains are substantial:

Выигрыш в эффективности значителен:

Экономия токенов: благодаря тому, что промежуточные результаты не попадают в контекст Claude, PTC радикально сокращает потребление токенов. Среднее использование снизилось с 43 588 до 27 297 токенов — сокращение на 37% на сложных исследовательских задачах.Сниженная задержка: каждый API-запрос требует инференса модели (от сотен миллисекунд до секунд). Когда Claude оркестрирует 20+ вызовов инструментов в одном блоке кода, вы устраняете 19+ проходов инференса. API обрабатывает выполнение инструментов без возврата к модели каждый раз.Улучшенная точность: написание явной логики оркестрации снижает количество ошибок по сравнению с жонглированием множественными результатами на естественном языке. Внутренний поиск знаний улучшился с 25,6% до 28,5%; результаты по бенчмарку GIA — с 46,5% до 51,2%.

Production workflows involve messy data, conditional logic, and operations that need to scale. Programmatic Tool Calling lets Claude handle that complexity programmatically while keeping its focus on actionable results rather than raw data processing.

Производственные рабочие процессы включают грязные данные, условную логику и операции, требующие масштабирования. Programmatic Tool Calling позволяет Claude обрабатывать эту сложность программно, сосредоточившись на результатах, а не на обработке необработанных данных.

How Programmatic Tool Calling works

Как работает Programmatic Tool Calling

1. Mark tools as callable from code

1. Пометьте инструменты как вызываемые из кода

Add code_execution to tools, and set allowed_callers to opt-in tools for programmatic execution:

Добавьте code_execution к инструментам и задайте allowed_callers для включения инструментов в программное выполнение:

{ "tools": [ { "type": "code_execution_20250825", "name": "code_execution" }, { "name": "get_team_members", "description": "Get all members of a department...", "input_schema": {...}, "allowed_callers": ["code_execution_20250825"] # opt-in to programmatic tool calling }, { "name": "get_expenses", ... }, { "name": "get_budget_by_level", ... } ] }

{ "tools": [ { "type": "code_execution_20250825", "name": "code_execution" }, { "name": "get_team_members", "description": "Get all members of a department...", "input_schema": {...}, "allowed_callers": ["code_execution_20250825"] # включение программного вызова }, { "name": "get_expenses", ... }, { "name": "get_budget_by_level", ... } ] }

The API converts these tool definitions into Python functions that Claude can call.

API преобразует эти определения инструментов в Python-функции, которые Claude может вызывать.

2. Claude writes orchestration code

2. Claude пишет код оркестрации

Instead of requesting tools one at a time, Claude generates Python code:

Вместо запроса инструментов по одному Claude генерирует Python-код:

{ "type": "server_tool_use", "id": "srvtoolu_abc", "name": "code_execution", "input": { "code": "team = get_team_members('engineering')\n..." # the code example above } }

{ "type": "server_tool_use", "id": "srvtoolu_abc", "name": "code_execution", "input": { "code": "team = get_team_members('engineering')\n..." # приведённый выше пример кода } }

3. Tools execute without hitting Claude's context

3. Инструменты выполняются без попадания в контекст Claude

When the code calls get_expenses(), you receive a tool request with a caller field:

Когда код вызывает get_expenses(), вы получаете запрос инструмента с полем caller:

{ "type": "tool_use", "id": "toolu_xyz", "name": "get_expenses", "input": {"user_id": "emp_123", "quarter": "Q3"}, "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc" } }

{ "type": "tool_use", "id": "toolu_xyz", "name": "get_expenses", "input": {"user_id": "emp_123", "quarter": "Q3"}, "caller": { "type": "code_execution_20250825", "tool_id": "srvtoolu_abc" } }

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.

Вы предоставляете результат, который обрабатывается в среде Code Execution, а не в контексте Claude. Этот цикл запрос-ответ повторяется для каждого вызова инструмента в коде.

4. Only final output enters context

4. В контекст попадает только конечный результат

When the code finishes running, only the results of the code are returned to Claude:

Когда выполнение кода завершается, Claude получает только результаты работы кода:

{ "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_abc", "content": { "stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]" } }

{ "type": "code_execution_tool_result", "tool_use_id": "srvtoolu_abc", "content": { "stdout": "[{\"name\": \"Alice\", \"spent\": 12500, \"limit\": 10000}...]" } }

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

Это всё, что видит Claude — а не 2000+ статей расходов, обработанных в процессе.

When to use Programmatic Tool Calling

Когда использовать Programmatic Tool Calling

Programmatic Tool Calling adds a code execution step to your workflow. This extra overhead pays off when the token savings, latency improvements, and accuracy gains are substantial.

Programmatic Tool Calling добавляет шаг выполнения кода в ваш рабочий процесс. Эти дополнительные накладные расходы окупаются, когда экономия токенов, улучшение задержки и повышение точности существенны.

Most beneficial when:

Наиболее полезно, когда:

Обработка больших наборов данных, где нужны только агрегаты или сводкиВыполнение многоэтапных рабочих процессов с тремя и более зависимыми вызовами инструментовФильтрация, сортировка или преобразование результатов инструментов до того, как Claude их увидитЗадачи, где промежуточные данные не должны влиять на рассуждения ClaudeВыполнение параллельных операций над множеством элементов (например, проверка 50 эндпоинтов)

Less beneficial when:

Менее полезно, когда:

Простые вызовы одного инструментаЗадачи, где Claude должен видеть и анализировать все промежуточные результатыБыстрые запросы с небольшими ответами

Tool Use Examples

Tool Use Examples

The challenge

Проблема

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.

JSON Schema отлично определяет структуру — типы, обязательные поля, допустимые enum-значения — но не может выразить паттерны использования: когда включать опциональные параметры, какие комбинации имеют смысл или какие конвенции ожидает ваш API.

Consider a support ticket API:

Рассмотрим API тикетов поддержки:

{ "name": "create_ticket", "input_schema": { "properties": { "title": {"type": "string"}, "priority": {"enum": ["low", "medium", "high", "critical"]}, "labels": {"type": "array", "items": {"type": "string"}}, "reporter": { "type": "object", "properties": { "id": {"type": "string"}, "name": {"type": "string"}, "contact": { "type": "object", "properties": { "email": {"type": "string"}, "phone": {"type": "string"} } } } }, "due_date": {"type": "string"}, "escalation": { "type": "object", "properties": { "level": {"type": "integer"}, "notify_manager": {"type": "boolean"}, "sla_hours": {"type": "integer"} } } }, "required": ["title"] } }

{ "name": "create_ticket", "input_schema": { "properties": { "title": {"type": "string"}, "priority": {"enum": ["low", "medium", "high", "critical"]}, "labels": {"type": "array", "items": {"type": "string"}}, "reporter": { "type": "object", "properties": { "id": {"type": "string"}, "name": {"type": "string"}, "contact": { "type": "object", "properties": { "email": {"type": "string"}, "phone": {"type": "string"} } } } }, "due_date": {"type": "string"}, "escalation": { "type": "object", "properties": { "level": {"type": "integer"}, "notify_manager": {"type": "boolean"}, "sla_hours": {"type": "integer"} } } }, "required": ["title"] } }

The schema defines what's valid, but leaves critical questions unanswered:

Схема определяет, что допустимо, но оставляет критические вопросы без ответа:

Неоднозначность формата: должен ли due_date использовать «2024-11-06», «Nov 6, 2024» или «2024-11-06T00:00:00Z»?Конвенции идентификаторов: является ли reporter.id UUID, «USR-12345» или просто «12345»?Использование вложенных структур: когда Claude должен заполнять reporter.contact?Корреляции параметров: как escalation.level и escalation.sla_hours соотносятся с приоритетом?

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

Эти неоднозначности могут приводить к некорректным вызовам инструментов и непоследовательному использованию параметров.

Our solution

Наше решение

Tool Use Examples let you provide sample tool calls directly in your tool definitions. Instead of relying on schema alone, you show Claude concrete usage patterns:

Tool Use Examples позволяет предоставлять примеры вызовов инструментов непосредственно в определениях инструментов. Вместо того чтобы полагаться только на схему, вы показываете Claude конкретные паттерны использования:

{ "name": "create_ticket", "input_schema": { /* same schema as above */ }, "input_examples": [ { "title": "Login page returns 500 error", "priority": "critical", "labels": ["bug", "authentication", "production"], "reporter": { "id": "USR-12345", "name": "Jane Smith", "contact": { "email": "jane@acme.com", "phone": "+1-555-0123" } }, "due_date": "2024-11-06", "escalation": { "level": 2, "notify_manager": true, "sla_hours": 4 } }, { "title": "Add dark mode support", "labels": ["feature-request", "ui"], "reporter": { "id": "USR-67890", "name": "Alex Chen" } }, { "title": "Update API documentation" } ] }

{ "name": "create_ticket", "input_schema": { /* та же схема, что выше */ }, "input_examples": [ { "title": "Login page returns 500 error", "priority": "critical", "labels": ["bug", "authentication", "production"], "reporter": { "id": "USR-12345", "name": "Jane Smith", "contact": { "email": "jane@acme.com", "phone": "+1-555-0123" } }, "due_date": "2024-11-06", "escalation": { "level": 2, "notify_manager": true, "sla_hours": 4 } }, { "title": "Add dark mode support", "labels": ["feature-request", "ui"], "reporter": { "id": "USR-67890", "name": "Alex Chen" } }, { "title": "Update API documentation" } ] }

From these three examples, Claude learns:

Из этих трёх примеров Claude усваивает:

Конвенции форматов: даты используют YYYY-MM-DD, ID пользователей следуют шаблону USR-XXXXX, метки используют kebab-caseПаттерны вложенных структур: как конструировать объект reporter с вложенным объектом contactКорреляции опциональных параметров: критические баги содержат полную контактную информацию + эскалацию с жёсткими SLA; запросы на фичи имеют reporter, но без contact/escalation; внутренние задачи содержат только title

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

В наших внутренних тестах примеры использования инструментов улучшили точность с 72% до 90% при работе со сложными параметрами.

When to use Tool Use Examples

Когда использовать Tool Use Examples

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

Tool Use Examples добавляют токены к определениям ваших инструментов, поэтому они наиболее ценны, когда улучшение точности перевешивает дополнительные затраты.

Most beneficial when:

Наиболее полезно, когда:

Сложные вложенные структуры, где валидный JSON не означает корректное использованиеИнструменты с множеством опциональных параметров, где паттерны включения имеют значениеAPI с доменно-специфичными конвенциями, не зафиксированными в схемахПохожие инструменты, где примеры поясняют, какой использовать (например, create_ticket vs create_incident)

Less beneficial when:

Менее полезно, когда:

Простые инструменты с одним параметром и очевидным использованиемСтандартные форматы вроде URL или email, которые Claude уже понимаетТребования валидации лучше обрабатываются ограничениями JSON Schema

Best practices

Лучшие практики

Building agents that take real-world actions means handling scale, complexity, and precision simultaneously. These three features work together to solve different bottlenecks in tool use workflows. Here's how to combine them effectively.

Создание агентов, выполняющих реальные действия, означает одновременную работу с масштабом, сложностью и точностью. Эти три функции работают совместно для решения различных узких мест в рабочих процессах использования инструментов. Вот как их эффективно комбинировать.

Layer features strategically

Выстраивайте функции стратегически

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

Не каждому агенту нужно использовать все три функции для конкретной задачи. Начните с самого узкого места:

Раздувание контекста от определений инструментов → Tool Search ToolБольшие промежуточные результаты, загрязняющие контекст → Programmatic Tool CallingОшибки параметров и некорректные вызовы → Tool Use Examples

This focused approach lets you address the specific constraint limiting your agent's performance, rather than adding complexity upfront.

Такой целенаправленный подход позволяет устранить конкретное ограничение, сдерживающее производительность вашего агента, вместо добавления сложности заранее.

Then layer additional features as needed. 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 Tool обеспечивает нахождение нужных инструментов, Programmatic Tool Calling — эффективное выполнение, а Tool Use Examples — корректный вызов.

Set up Tool Search Tool for better discovery

Настройте Tool Search Tool для лучшего обнаружения

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

Поиск инструментов сопоставляет имена и описания, поэтому чёткие, описательные определения повышают точность обнаружения.

// Good { "name": "search_customer_orders", "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info." } // Bad { "name": "query_db_orders", "description": "Execute order query" }

// Хорошо { "name": "search_customer_orders", "description": "Search for customer orders by date range, status, or total amount. Returns order details including items, shipping, and payment info." } // Плохо { "name": "query_db_orders", "description": "Execute order query" }

Add system prompt guidance so Claude knows what's available:

Добавьте указания в системный промпт, чтобы Claude знал, что доступно:

You have access to tools for Slack messaging, Google Drive file management, Jira ticket tracking, and GitHub repository operations. Use the tool search to find specific capabilities.

You have access to tools for Slack messaging, Google Drive file management, Jira ticket tracking, and GitHub repository operations. Use the tool search to find specific capabilities.

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.

Держите три-пять наиболее используемых инструментов постоянно загруженными, остальные откладывайте. Это балансирует мгновенный доступ к частым операциям с обнаружением по требованию для всего остального.

Set up Programmatic Tool Calling for correct execution

Настройте Programmatic Tool Calling для корректного выполнения

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

Поскольку Claude пишет код для парсинга выходных данных инструментов, документируйте форматы возвращаемых значений чётко. Это помогает Claude писать корректную логику парсинга:

{ "name": "get_orders", "description": "Retrieve orders for a customer. Returns: List of order objects, each containing: - id (str): Order identifier - total (float): Order total in USD - status (str): One of 'pending', 'shipped', 'delivered' - items (list): Array of {sku, quantity, price} - created_at (str): ISO 8601 timestamp" }

{ "name": "get_orders", "description": "Retrieve orders for a customer. Returns: List of order objects, each containing: - id (str): Order identifier - total (float): Order total in USD - status (str): One of 'pending', 'shipped', 'delivered' - items (list): Array of {sku, quantity, price} - created_at (str): ISO 8601 timestamp" }

See below for opt-in tools that benefit from programmatic orchestration:

Ниже приведены инструменты для opt-in, которые выигрывают от программной оркестрации:

Инструменты, которые могут выполняться параллельно (независимые операции)Операции, безопасные для повторного вызова (идемпотентные)

Set up Tool Use Examples for parameter accuracy

Настройте Tool Use Examples для точности параметров

Craft examples for behavioral clarity:

Создавайте примеры для поведенческой ясности:

Используйте реалистичные данные (настоящие названия городов, правдоподобные цены, а не «string» или «value»)Покажите разнообразие: минимальная, частичная и полная спецификацияБудьте лаконичны: 1–5 примеров на инструментСосредоточьтесь на неоднозначностях (добавляйте примеры только там, где корректное использование неочевидно из схемы)

Getting started

Начало работы

These features are available in beta. To enable them, add the beta header and include the tools you need:

Эти функции доступны в бета-версии. Чтобы их включить, добавьте бета-заголовок и подключите нужные инструменты:

client.beta.messages.create( betas=["advanced-tool-use-2025-11-20"], model="claude-sonnet-4-5-20250929", max_tokens=4096, tools=[ {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, {"type": "code_execution_20250825", "name": "code_execution"}, # Your tools with defer_loading, allowed_callers, and input_examples ] )

client.beta.messages.create( betas=["advanced-tool-use-2025-11-20"], model="claude-sonnet-4-5-20250929", max_tokens=4096, tools=[ {"type": "tool_search_tool_regex_20251119", "name": "tool_search_tool_regex"}, {"type": "code_execution_20250825", "name": "code_execution"}, # Ваши инструменты с defer_loading, allowed_callers и input_examples ] )

For detailed API documentation and SDK examples, see our:

Подробную документацию API и примеры SDK смотрите в наших материалах:

Документация и cookbook для Tool Search ToolДокументация и cookbook для Programmatic Tool CallingДокументация для Tool Use Examples

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.

Эти функции переводят использование инструментов от простого вызова функций к интеллектуальной оркестрации. По мере того как агенты решают всё более сложные задачи, охватывающие десятки инструментов и большие наборы данных, динамическое обнаружение, эффективное выполнение и надёжный вызов становятся фундаментальными.

We're excited to see what you build.

Нам не терпится увидеть, что вы создадите.

Acknowledgements

Благодарности

Written by Bin Wu, with contributions from Adam Jones, Artur Renault, Henry Tay, Jake Noble, Noah Picard, Sam Jiang, and the Claude Developer Platform team. This work builds on foundational research by Chris Gorgolewski, Daniel Jiang, Jeremy Fox and Mike Lambert. We also drew inspiration from across the AI ecosystem, including Joel Pobar's LLMVM, Cloudflare's Code Mode and Code Execution as MCP. Special thanks to Andy Schumeister, Hamish Kerr, Keir Bradwell, Matt Bleifer and Molly Vorwerck for their support.

Автор — Bin Wu, при участии Adam Jones, Artur Renault, Henry Tay, Jake Noble, Noah Picard, Sam Jiang и команды Claude Developer Platform. Эта работа основана на фундаментальных исследованиях Chris Gorgolewski, Daniel Jiang, Jeremy Fox и Mike Lambert. Мы также черпали вдохновение из ИИ-экосистемы, включая LLMVM Джоэла Побара, Code Mode от Cloudflare и Code Execution as MCP. Особая благодарность Andy Schumeister, Hamish Kerr, Keir Bradwell, Matt Bleifer и Molly Vorwerck за поддержку.