Инструменты MCP

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

Имя	Что делает	Параметры	Метод API	Подтверждение
`lookup_company_by_inn`	Находит реквизиты юрлица по ИНН, чтобы заполнить счёт	`inn`	`GET /v3/filter/api/counterparty-detail`	—
`get_order`	Статус, сумма, дата оплаты и ссылка на оплату по счёту	`order_id`	`GET /v3/billing/api/order/order/{id}`	—
`find_orders`	Поиск счетов по номеру, статусу, датам и сумме	`merchant_order_id, status[], created_from, created_to, amount_min, amount_max, page, page_size`	`GET /v3/filter/api/order/order`	—
`find_refunds`	Поиск возвратов, в том числе по исходному счёту	`refund_id, parent_order_id, merchant_order_id, status, page, page_size`	`GET /v3/filter/api/order/refund-order`	—
`create_invoice` меняет данные	Выставляет счёт юрлицу и возвращает ссылку на оплату	`customer, description, amount, vat_amount, basket_items[], expiration_date, success_url, fail_url`	`POST /v3/billing/api/order/order`	да
`cancel_invoice` меняет данные	Отменяет неоплаченный счёт	`order_id, reason`	`DELETE /v3/billing/api/order/order/{id}`	да
`create_refund` меняет данные	Возвращает деньги по оплаченному счёту	`parent_order_id, amount, vat_amount, description, basket_items[], confirmation_token`	`POST /v3/billing/api/order/refund-order`	да, в два шага

Что сервер делает сам

Часть работы снята с модели намеренно: там, где ошибка стоит денег, полагаться на её внимательность нельзя.

Номер заказа. Уникальный merchantOrderId генерирует сервер и записывает в журнал — модель его не придумывает и не может повторить.
Сходимость сумм. Перед отправкой сумма счёта сверяется с составом, а НДС — с суммой налога по позициям. Расхождение возвращается моделью как ошибка ввода, а не уезжает в API.
Проверка статуса. Перед отменой и возвратом сервер сам читает текущее состояние счёта: отменить оплаченный или вернуть неоплаченный не выйдет.
Защита от дублей. Перед созданием возврата сервер ищет уже существующие по тому же счёту. Повтор после обрыва связи вернёт первый результат, а не спишет дважды.
Короткие ответы. Поиск возвращает несколько полей на запись, а не весь объект: длинный ответ вытесняет из контекста то, ради чего его запрашивали.

Чего в наборе нет

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

Соответствие API

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