Каталог инструментов для агентов: ошибки, мешающие выбору

Где ломается выбор инструмента

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

Если в каталоге два похожих инструмента, выбор быстро становится случайным. Один называется "Найти заказ", другой "Получить данные по заказу". В описании у обоих почти одно и то же: "работает с заказами клиента". Для человека разница иногда очевидна, потому что он помнит внутреннюю логику. Для агента это почти один и тот же инструмент.

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

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

Из-за этого слабый каталог бьет сразу по двум местам. Снаружи это выглядит как нестабильность LLM: то ответ хороший, то странный. Внутри система сама подталкивает агента к неверному выбору. Смена модели тут помогает меньше, чем обычно ждут. Если описания пересекаются, другая модель просто ошибется по-другому.

Проверка простая. Дайте карточку инструмента человеку, который не участвовал в разработке, и попросите за 10 секунд ответить на два вопроса: когда этот инструмент вызывать и что он может сломать. Если человек мнется, агент тоже будет путаться.

Что должно быть в карточке

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

Первое правило простое: один инструмент - одно понятное действие. Формулировка вроде "работает с заказами" почти бесполезна. Намного лучше написать "проверяет статус заказа по номеру" или "создает заявку на возврат". Чем уже действие, тем реже агент путается.

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

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

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

Результат тоже должен быть предсказуемым. Если один и тот же инструмент иногда возвращает JSON, иногда текст, а иногда пустое поле, агент начнет писать лишнюю логику или уйдет в другой вызов. Лучше держать один формат ответа и коротко описать его в карточке: статус, причина ошибки, код, следующий шаг.

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

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

Почему общие описания сбивают модель

Модель выбирает инструмент не по здравому смыслу, а по тексту в карточке. Если описание туманное, она начинает гадать. Обычно это заканчивается лишними вызовами, пропущенными шагами или выбором соседнего инструмента.

Фраза вроде "работа с документами" ничего не объясняет. Какие документы? Что именно нужно сделать: найти файл, извлечь поля, сравнить версии, проверить подпись или отправить на согласование? Для человека такой ярлык еще может сработать. Для агента он слишком широкий.

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

Путаница растет, когда в карточке нет примеров. Агенту мало знать общее назначение. Ему нужны формулировки, похожие на реальные сообщения пользователей. Например, описание "ищет договоры по номеру и дате" работает заметно лучше, чем "работа с договорными документами". Во втором случае модель может отправить запрос в поиск, в OCR или в систему согласования, и все три варианта будут выглядеть правдоподобно.

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

Сравнение простое. Плохо: "Инструмент для работы с документами". Лучше: "Извлекает ИНН, номер договора и дату из PDF. Используй, когда нужно достать поля из файла. Не используй, когда нужно найти документ в архиве или сравнить две версии".

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

Когда функции пересекаются

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

Частая ошибка в том, что поиск, чтение и изменение собирают в одном месте. Например, один инструмент принимает query и может и найти заказ, и вернуть карточку, и сразу поменять статус. Для человека это выглядит удобно. Для агента это ловушка: он хотел только проверить данные, а получил путь к изменению.

Гораздо лучше закладывать простую логику действия. Один инструмент ищет список. Другой читает один объект по id. Третий меняет объект по id. Тогда у модели меньше двусмысленности, а трассировка становится проще: видно, на каком шаге агент искал, читал или менял.

Плохо, когда двум инструментам дают одинаковый вход, но разный смысл. Если customer_id есть и у get_customer_profile, и у get_customer_status, модель часто выбирает наугад, особенно если описания похожи. Еще хуже, когда оба инструмента возвращают похожий JSON, но один нужен для показа пользователю, а второй - для внутренней проверки.

Нормально работает жесткое разделение:

• search_tickets(query) возвращает список.
• get_ticket(ticket_id) читает одну заявку.
• update_ticket(ticket_id, fields) меняет одну заявку.
• bulk_update_tickets(filter, fields) меняет набор заявок.

Отдельно стоит разводить массовые и точечные действия. Если агенту доступны close_ticket и close_tickets, он должен видеть разницу уже в названии, входе и описании. Иначе запрос "закрой старые заявки" легко превратится в закрытие одной случайной записи или, наоборот, пачки записей без нужной проверки.

Для каждой частой задачи оставляйте один явный путь. Если статус заказа можно поменять через update_order, patch_order_status и apply_order_action, агент будет метаться между ними. Один сценарий - один основной инструмент. Остальные лучше убрать, спрятать за внутренней логикой или оставить только для редких служебных случаев.

Чем меньше пересечений, тем спокойнее агент ведет себя в проде. Он реже делает лишние шаги, реже зовет не тот инструмент, и его проще отлаживать.

Почему широкие права опаснее плохого ответа

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

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

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

Удаление почти всегда стоит выносить в отдельный инструмент. Не смешивайте его с обновлением. Инструмент edit_customer не должен уметь и менять email, и стирать профиль. Ошибка в таком месте обходится слишком дорого.

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

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

Права стоит привязывать не только к инструменту, но и к роли, и к сценарию. Бот первой линии может читать заказ и добавлять внутренний комментарий. Он не должен делать возврат денег. Финансовый агент может оформлять возврат, но только в своем лимите.

Если команде важны журналирование и разбор спорных действий, это особенно заметно. Например, в RU LLM логи, бэкапы и аудит по запросам можно держать внутри РФ, что упрощает разбор ошибок в системах с требованиями по 152-ФЗ. Но еще лучше собрать каталог так, чтобы агент изначально не получал лишнюю власть над данными и деньгами.

Как выглядит хорошая карточка

Хорошая карточка снимает с модели лишние догадки. Агент не должен разбираться, что автор имел в виду под "работой с заказами" или "операциями с клиентом". Ему нужен короткий и узкий смысл.

Начните с названия. Оно должно описывать одно действие простым глаголом: find_order, create_refund, update_email. Плохие варианты обычно расплывчаты: order_helper, client_tool, support_actions. По ним непонятно, читать данные надо или менять их.

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

Фраза про момент вызова должна быть очень точной. Не "используй для работы с заказами", а "вызывай, когда пользователь просит найти заказ по номеру, телефону или email". Одной такой фразы часто хватает, чтобы агент перестал путать поиск заказа с возвратом денег.

Примеры лучше брать из реальных запросов, а не из документации. Например: "Где мой заказ 54821?", "Проверь статус доставки по телефону", "Найди заказ на почту ivan@example.com". Такие примеры задают границы лучше длинного общего описания.

Обязательные поля пишите сухо и без украшений. Если инструменту нужен order_id, phone или email, так и укажите. Если одного поля достаточно, скажите это прямо. Модель плохо переносит туманные формулировки вроде "по возможности передайте идентификаторы клиента".

Последняя строка часто спасает от ошибок: что инструмент не делает. Например: "Не оформляет возврат", "Не меняет адрес доставки", "Не создает новый заказ". Если инструмент только читает данные, лучше написать это отдельно.

Пример из службы поддержки

Клиент пишет в чат: он хочет вернуть заказ и заодно спрашивает, где сейчас посылка. Для агента это обычный запрос, но именно на таких сообщениях быстро видны слабые места каталога. Если карточки составлены небрежно, агент легко выберет не тот инструмент и либо полезет менять данные раньше времени, либо откроет возврат без нужных условий.

У агента есть три инструмента. Первый только читает статус заказа и доставки. Он показывает номер заказа, текущий этап, дату доставки и признак, доступен ли возврат. Второй создает заявку на возврат. Он меняет состояние заказа, поэтому требует номер заказа и явное подтверждение клиента. Третий меняет адрес доставки. Он тоже пишет в систему, но к возврату не относится.

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

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

Если клиент отвечает "да, оформляйте", агент передает номер заказа в инструмент возврата и создает заявку. Если клиент вместо этого пишет "лучше поменяйте адрес", агент не трогает возврат и вызывает другой инструмент. Именно для таких развилок и нужен аккуратный каталог: один запрос клиента, несколько похожих действий, но у каждого свой смысл и свой риск.

Самая частая ошибка здесь простая. Команда дает всем трем инструментам описания в духе "операции с заказом", а потом удивляется, почему агент то меняет адрес, то пытается открыть возврат без подтверждения. Проблема не в модели. Каталог просто не объяснил ей границы.

Что чаще всего ломают при ревизии каталога

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

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

Похожая проблема возникает, когда ограничения прячут в длинный абзац. В начале карточки написано, что инструмент "работает с заказами", а ниже мелко уточняется, что он не умеет отмену, не видит архив и доступен только для B2B-клиентов. Модель чаще цепляется за первую общую формулировку, чем за поздние оговорки.

Еще одна ошибка - склеивать несколько действий в один инструмент. Команде так удобнее поддерживать один API-метод, но агенту нужна ясность. Если один и тот же инструмент умеет искать клиента, менять тариф, создавать заявку и отправлять письмо, у модели нет простого правила выбора. Она начинает вызывать его слишком часто.

После запуска новой версии команды нередко оставляют старые дубли. В каталоге появляются get_customer, find_customer_v2 и customer_lookup с почти одинаковым смыслом. Для человека разница может быть очевидной по памяти. Для модели это лишняя развилка.

Есть несколько тревожных сигналов. Два инструмента отвечают на один и тот же запрос. Описание говорит "для работы с данными" вместо точного действия. Ограничения стоят в конце длинного текста. Один инструмент делает больше одного шага. И никто не проверял спорные формулировки на тестовых запросах.

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

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

Быстрая проверка перед запуском

Перед запуском полезно пройтись по каталогу за 15 минут и убрать то, что агент почти наверняка поймет неверно. Обычно ломается не модель, а сама карточка: слишком широкое название, туманное описание или права, выданные "на всякий случай".

Проверка короткая:

1. У карточки должна быть одна цель. Не "работа с заказами", а "прочитать статус заказа" или "изменить адрес доставки".
2. По названию должно быть ясно, инструмент читает данные или меняет их. Глаголы хорошо дисциплинируют: get_, list_, check_ для чтения и create_, update_, cancel_ для записи.
3. В описании нужен пример и антипример. Например: "Используй для проверки остатка на складе" и "Не используй для расчета срока доставки".
4. Права нужно выдавать под задачу, а не с запасом. Если агенту нужно читать баланс, не давайте доступ к переводу средств.
5. Ответ инструмента должен легко проверяться кодом. Четкая схема и понятные поля лучше строки вроде "все прошло успешно".

Если сомневаетесь, устройте маленький прогон на пяти сценариях. Пусть агент выберет инструмент для запроса клиента, а вы посмотрите на две вещи: не вызвал ли он лишнее и можно ли автоматически проверить результат. Для команд, которые работают через RU LLM, такой прогон особенно полезен: gateway можно оставить прежним, но слабая карточка останется слабой для любой модели.

Если хотя бы один пункт не проходит, не запускайте каталог в прод. Одна короткая правка в карточке почти всегда дешевле недели разбора странных действий агента.

Что делать после первой правки

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

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

Рабочий порядок простой: переписать 10 самых частых инструментов, собрать набор спорных запросов, прогонять этот набор после каждой правки и отмечать случаи, где агент выбрал похожий, но неверный инструмент.

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

Смотрите не только на явные ошибки, но и на тихие подмены. Например, агент должен вызвать инструмент возврата, а вместо этого уходит в проверку статуса заказа. Пользователь может даже получить внятный ответ, но процесс уже сломан: нужное действие не произошло.

Если команда работает через RU LLM, удобно держать правила вызова, логи и аудит в одном контуре внутри РФ. Это упрощает разбор инцидентов: видно, какой запрос пришел, какой инструмент выбрал агент и где он отклонился от правила. Для команд с требованиями по 152-ФЗ это еще и снижает лишний риск при разборе спорных случаев.

На этом ревизия не заканчивается. Каждый новый сценарий стоит сразу добавлять в набор спорных запросов и снова прогонять. Иначе каталог быстро расползется: на бумаге карточки останутся аккуратными, а в живых диалогах агент снова начнет путать соседние действия.