Introducing advanced tool use on the Claude Developer Platform

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

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

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

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

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

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

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

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

Tool Search Tool

Проблема

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

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

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

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

Наше решение

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

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

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

С Tool Search Tool:

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

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

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

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

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

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

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

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

Реализация:

{ "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 ] }

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

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

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

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

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

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

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

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

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

Programmatic Tool Calling

Проблема

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

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

Наше решение

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

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

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

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

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

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

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

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

С Programmatic Tool Calling:

Вместо возврата каждого результата инструмента в Claude, Claude пишет Python-скрипт, оркестрирующий весь рабочий процесс. Скрипт выполняется в среде Code Execution (изолированная песочница), приостанавливаясь, когда ему нужны результаты от ваших инструментов. Когда вы возвращаете результаты инструментов через API, они обрабатываются скриптом, а не потребляются моделью. Скрипт продолжает выполнение, и Claude видит только конечный результат.

Вот как выглядит код оркестрации 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))

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

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

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

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

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

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

Добавьте 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"] # включение программного вызова }, { "name": "get_expenses", ... }, { "name": "get_budget_by_level", ... } ] }

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

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

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

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

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

Когда код вызывает 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" } }

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

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

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

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

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

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

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

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

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

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

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

Tool Use Examples

Проблема

JSON Schema отлично определяет структуру — типы, обязательные поля, допустимые enum-значения — но не может выразить паттерны использования: когда включать опциональные параметры, какие комбинации имеют смысл или какие конвенции ожидает ваш 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"] } }

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

Неоднозначность формата: должен ли 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 соотносятся с приоритетом?

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

Наше решение

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

{ "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" } ] }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

// Хорошо { "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" }

Добавьте указания в системный промпт, чтобы 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.

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

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

Поскольку 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" }

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

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

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

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

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

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

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

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 ] )

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

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

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

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

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

Автор — 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 за поддержку.