Руководство по дизайну Tools

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

Стандарт Tool Contract

Каждый MCP-инструмент описывается по единой схеме. Схема включает не только типы входных и выходных данных, но и уровень риска, права доступа, побочные эффекты, Audit Events и возможные случаи сбоев. Только зная все поля, можно безопасно применять инструмент — будь то агент, веб-приложение или автоматизированный рабочий процесс.

Поля в обзоре:

• Name — уникальный машиночитаемый идентификатор в формате domain.verb
• Description — описание назначения на естественном языке для агентов и разработчиков
• Category — предметная классификация (например, communication, files, billing)
• Risk Level — классификация по модели рисков (от Low до Forbidden)
• Autonomous Execution — вправе ли агент вызывать инструмент без разрешения человека
• Confirmation — требуется ли явное подтверждение пользователя
• Step-up Auth — требуется ли дополнительная аутентификация и когда
• Input Schema — типизированные параметры включая опциональные поля
• Output Schema — типизированные возвращаемые значения включая коды статуса
• Permissions — какие права требует инструмент
• Side Effects — все изменения состояния за пределами возвращаемого значения
• Audit Event — какое событие записывается в журнал аудита
• Failure Modes — полный список всех возможных кодов ошибок

Следующий пример показывает полный контракт для emails.send_external — инструмента с Critical-риском, инициирующего внешнюю коммуникацию:

Каждое поле выполняет функцию в системе: permissions управляет Policy Engine, sideEffects информирует Confirmation UI, failureModes обрабатываются при обработке ошибок, auditEvent записывается в журнал аудита. Контракт — это не просто документация: он часть среды выполнения.

Модель рисков

MCP-first классифицирует каждый инструмент по одному из пяти уровней риска. Уровень определяет, вправе ли агент вызывать инструмент автономно, требуется ли подтверждение и требуется ли Step-up Auth. Классификация не опциональна — она часть контракта.

Low

Инструменты этого уровня только читают данные или не создают постоянных эффектов. Они могут выполняться агентами автономно, без подтверждения или Step-up Auth. Типичны запросы списков, поиски и справочные ресурсы.

Medium

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

High

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

Critical

Инструменты этого уровня инициируют внешнюю коммуникацию, платежи, удаление данных или изменение прав. Они всегда требуют явного подтверждения и часто Step-up Auth. Автономное выполнение не разрешено.

Forbidden for AI

Инструменты этого уровня не могут ни читаться, ни выполняться AI-агентом. Они полностью скрыты из Tool Discovery для агентов. Классификация — жёсткая граница, не решение политики.

Идемпотентность

Многие инструменты вызываются в агентных рабочих процессах несколько раз — из-за повторных попыток, параллельного выполнения или ошибочного планирования. MCP-first рекомендует по возможности делать Tools идемпотентными: одинаковые входные данные при многократном вызове дают тот же результат без нежелательных дубликатов или побочных эффектов.

create_download_link — хороший пример. Если для файла с тем же fileId и тем же expiresAt уже существует действующая ссылка, инструмент возвращает её, вместо того чтобы создавать вторую:

create_download_link(fileId: "f_abc123", expiresAt: "2025-12-31T23:59:00Z")

→ Первый вызов: создаёт новую ссылку, возвращает linkId + url
→ Второй вызов (те же параметры, ссылка ещё действительна): возвращает ту же ссылку
→ Третий вызов (ссылка истекла): создаёт новую ссылку

Идемпотентность должна реализовываться явно — она не возникает автоматически. Поле контракта Tool sideEffects должно описывать поведение при повторении, чтобы агенты и клиенты могли правильно это учитывать.

Dry Run

Рискованные инструменты, особенно с массовыми эффектами, должны предлагать режим Dry Run. Dry Run выполняет все валидации и проверки, но не создаёт реальных побочных эффектов. Результат показывает, что произошло бы — без того чтобы что-то фактически произошло.

emails.bulk_send с dryRun: true возвращает полный предварительный просмотр:

// Request
{
  "tool": "emails.bulk_send",
  "params": {
    "templateId": "tmpl_newsletter_q3",
    "segmentId": "seg_active_customers",
    "dryRun": true
  }
}

// Response
{
  "dryRun": true,
  "recipientCount": 4821,
  "sampleMessages": [
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Liebe Anna, im dritten Quartal haben wir…"
    },
    {
      "to": "[email protected]",
      "subject": "Ihr Q3-Update ist da",
      "previewText": "Lieber Max, im dritten Quartal haben wir…"
    }
  ],
  "warnings": [
    "43 Empfänger haben keinen Vornamen – Fallback 'Hallo' wird verwendet.",
    "12 E-Mail-Adressen sind als unzustellbar markiert und werden übersprungen."
  ],
  "missingPermissions": [],
  "expectedSideEffects": [
    "4821 externe E-Mails werden versendet.",
    "4821 Audit-Events vom Typ email.external.sent werden erzeugt.",
    "Kampagnen-Status wird auf 'sent' gesetzt."
  ],
  "estimatedDurationMs": 18400
}

Только после проверки результата Dry Run и явного подтверждения пользователем выполняется реальный вызов без dryRun. Агент не вправе пропускать Dry Run, если инструмент объявляет его обязательным.