Расширенное использование инструментов на платформе Claude Developer Platform

Будущее AI-агентов — это модели, которые бесшовно работают с сотнями и тысячами инструментов. Ассистент в 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": [ // 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 ] }

Для 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 } }

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

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

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

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

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

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

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

Programmatic Tool Calling

Проблема

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

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

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

Решение

Programmatic Tool Calling позволяет Claude оркестрировать инструменты через код, а не через отдельные API-запросы. Вместо того чтобы запрашивать инструменты по одному с возвратом каждого результата в контекст, 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, Programmatic Tool Calling (PTC) резко снижает потребление токенов. Среднее использование упало с 43 588 до 27 297 токенов — снижение на 37% на сложных исследовательских задачах.

• Снижение задержки: Каждый API-запрос требует инференса модели (от сотен миллисекунд до секунд). Когда Claude оркестрирует 20+ вызовов инструментов в одном блоке кода, вы устраняете 19+ проходов инференса. API обрабатывает выполнение инструментов без возврата к модели каждый раз.

• Улучшение точности: Записывая явную логику оркестрации, Claude делает меньше ошибок, чем при жонглировании несколькими результатами инструментов на естественном языке. Внутреннее извлечение знаний улучшилось с 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"] # opt-in to programmatic tool calling }, { "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..." # the code example above } }

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 отлично справляется с определением структуры — типов, обязательных полей, допустимых перечислений — но не может выразить паттерны использования: когда включать опциональные параметры, какие комбинации имеют смысл или каких соглашений ожидает ваш 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"?
• Соглашения об ID: Является ли reporter.id UUID, "USR-12345" или просто "12345"?
• Использование вложенных структур: Когда Claude должен заполнять reporter.contact?
• Корреляции параметров: Как escalation.level и escalation.sla_hours соотносятся с priority?

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

Решение

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

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

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

В нашем внутреннем тестировании Tool Use Examples улучшили точность с 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 для лучшего обнаружения

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

// 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" }

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

См. ниже инструменты, которые выигрывают от программной оркестрации:

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

Настройте 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"}, # Your tools with defer_loading, allowed_callers, and 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. Мы также черпали вдохновение из экосистемы AI, включая LLMVM от Joel Pobar, Code Mode и Code Execution as MCP от Cloudflare. Отдельная благодарность Andy Schumeister, Hamish Kerr, Keir Bradwell, Matt Bleifer и Molly Vorwerck за поддержку.