MCP tools vs resources vs prompts: что и когда использовать

MCP tool описывает операцию, которую модель может предложить вызвать с типизированными аргументами: найти заказ, рассчитать тариф или создать черновик. Resource предоставляет контекст, который host application может прочитать по URI и добавить в разговор: файл, schema, справочник или snapshot. Prompt — параметризованный шаблон сообщений, который пользователь сознательно выбирает для повторяемого workflow. Это три разных control planes, а не три способа опубликовать одну функцию.

Выбирайте primitive по тому, кто управляет следующим шагом. Для внешней операции или authoritative lookup с runtime parameters нужен tool. Если пользователь или application должны выбрать и прочитать материал как контекст — resource. Если продукту нужна видимая стартовая команда с аргументами и подготовленными messages — prompt. Один server может сочетать все три: prompt формирует task, resource добавляет policy, tool выполняет разрешенный lookup. Prompt или resource не должны скрывать side effect, а tool не стоит использовать только для передачи статического текста.

• Меняет или вычисляет состояние по runtime input → tool.
• Предоставляет адресуемый content для context → resource.
• Запускает выбранное пользователем повторяемое взаимодействие → prompt.
• Нужны две роли → композиция primitives с отдельными contracts.

Спецификация описывает tools как model-controlled: client может показать их модели и позволить ей выбрать вызов. Для sensitive operation client должен показать inputs и дать человеку возможность отказаться. Resources являются application-driven: host сам решает, нужен ли picker, поиск, automatic inclusion или другой интерфейс. Prompts являются user-controlled и задуманы как доступные пользователю команды или templates, хотя протокол не навязывает конкретный UI.

Эти labels не являются authorization. Выбор tool моделью не дает права на side effect; выбор resource не доказывает доступ ко всем URI; запуск prompt не разрешает все действия, описанные в его тексте. Client и server отдельно проверяют identity, scopes, tenant, target и текущее состояние. Для consequential action нужны preview, confirmation или policy gate в момент выполнения, а не доверие к тому, что пользователь раньше выбрал prompt.

Tool definition должен иметь стабильный name, понятный description и валидный JSON Schema для input. Optional outputSchema позволяет client проверять structuredContent; это полезно для downstream automation, но не доказывает истинность данных. Server валидирует schema и business constraints, проверяет permission на конкретный object и возвращает tool execution error для исправимых domain failures. Protocol error следует оставлять для malformed request или неизвестного tool.

Разделяйте read и write operations. `orders.get` может быть low-risk lookup, тогда как `orders.refund` должен требовать amount, currency, order version, reason, idempotency key и approval receipt. Не делайте универсальный `execute_api` с произвольными path и body: такая абстракция скрывает authority от модели, reviewer и audit log. Tool annotations полезны как hints для UX, но client не должен считать их доверенной security policy без доверия к server.

Tool result может содержать text, structured content, resource link или embedded resource. Это не превращает tool в resource: вызов остается операцией с inputs, timeout, error semantics и audit event. Если большой результат имеет стабильный URI или переиспользуется, возвращайте короткий structured summary и resource link вместо копирования всего corpus в каждый result.

• Input schema проверяет форму; policy проверяет право и намерение.
• Output schema проверяет структуру; authoritative system проверяет факт.
• Write tool → exact target, confirmation, idempotency и postcondition.
• Неопределенный timeout → reconcile перед retry.

Resource имеет уникальный URI и может содержать text или binary content с MIME type. Resource templates публикуют параметризованные URI, а optional completion помогает подобрать argument. Client сначала вызывает resources/list или templates/list, затем resources/read. Subscriptions и listChanged — отдельные optional capabilities; поддержка resources не означает automatic refresh.

Для production фиксируйте source owner, data classification, revision или lastModified, allowed audience, size budget и cache policy. Annotations `audience`, `priority` и `lastModified` — hints для client, а не решения access control. Server проверяет URI, authorization и resource permission при каждом read. Не помещайте секрет в предсказуемый URI и не считайте, что неотображаемый элемент невозможно прочитать прямым request.

Resource подходит для context, но не гарантирует, что модель использовала или процитировала его корректно. Eval должен проверять current revision, passage support, conflict disclosure, no-answer behavior и cross-scope canary. Для часто меняющегося business fact иногда лучше read-only tool с authoritative lookup в момент запроса; для browseable документации со стабильными identifiers resource дает лучший discovery и cache contract.

• Стабильный browseable content → resource или resource template.
• Live parameterized fact → часто read-only tool.
• Subscription не заменяет revision check перед важным решением.
• Видимость URI не равна permission.

Prompt definition имеет name, optional title и description и список arguments. prompts/get возвращает description и messages, куда server подставляет проверенные arguments. Messages могут содержать text, image, audio или embedded resource. Хороший prompt объясняет outcome и ожидаемые inputs: `review_incident` с incident ID и review depth полезнее, чем нечеткий `analyze`.

Prompt удобен для discoverable slash-command, onboarding или стандартизированной последовательности анализа. Он не является server-side automation и не гарантирует выполнение инструкций моделью. Не прячьте hidden approval, credential или необратимое действие в template. Если workflow требует tool, prompt может подготовить messages и запросить анализ, но client все равно применяет tool policy, а server повторно авторизует call.

Версионируйте содержание template или хотя бы сохраняйте hash в evaluation evidence. listChanged сообщает, что каталог изменился, но активный разговор мог уже включить старые messages. Regression set должен проверять argument escaping, prompt injection в user-provided field, отсутствующие arguments, locale, embedded-resource permissions и поведение после изменения template.

Представим support server. `support://policies/refunds/2026-09` — resource, потому что это versioned policy content для чтения. `draft_refund_review` — prompt, потому что пользователь выбирает повторяемый review template с ticket ID. `tickets.get` и `refunds.create_draft` — tools, потому что выполняют runtime lookup и создают контролируемый draft. Финальный `refunds.submit` стоит отделить более сильным scope и confirmation. Такая композиция делает source, reasoning workflow и authority отдельными видимыми границами.

Типичные ошибки: публиковать каждую строку database как tool; прятать write request в resource URI; возвращать stale policy через tool без revision; использовать prompt как system policy; дублировать одинаковый content в prompt, resource и tool description; объявлять один mega-tool для всех API. Это ухудшает discovery, увеличивает context, размывает permissions и мешает eval локализовать failure.

Перед реализацией заполните короткую contract card: user outcome, controller, data owner, freshness, input/output shape, side effects, permission check, audit event, failure semantics, context cost и rollback. Если у двух сущностей разные authority или lifecycle, дайте им разные primitives, даже если backend endpoint общий.

• Context failure → проверьте resource revision и selection.
• Instruction failure → проверьте prompt version и argument handling.
• Execution failure → проверьте tool schema, policy, effect и reconciliation.
• Смешанный failure → храните отдельные receipts для каждой границы.

Начинайте contract suite с комбинаций capabilities: server с каждым primitive отдельно, всеми тремя вместе и изменениями catalog. Проверьте pagination, unknown names или URI, invalid arguments, MIME handling, structured output, listChanged и resource subscription только там, где capability объявлена. Negative security cases подменяют tenant, target, URI, prompt argument и tool result, добавляют indirect injection в resource и повторяют write после ambiguous timeout.

Проведите end-to-end eval на synthetic support case: пользователь выбирает prompt, client читает конкретную policy revision, model предлагает read tool, а write draft проходит отдельную confirmation. Evidence pack содержит protocol version, capability manifest, catalog hashes, resource revision, rendered prompt, tool inputs/results, approval receipt, final state и reviewer verdict. Это позволяет определить, какая граница сломалась, не полагаясь на fluent final answer.

Rollout начните с одного read-only resource, одного prompt и одного read-only tool. После проверки scope и audit добавьте reversible draft write; irreversible action оставляйте вне model authority до отдельного approval contract. Rollback отключает affected capability или tool, отзывает scope, pin-ит последнюю проверенную resource/prompt revision и сохраняет read-only diagnostics. Повторная активация требует regression для измененного primitive и всей композиции, которую он питает.

• Hard gate → cross-tenant read, hidden side effect или unauthorized write.
• Quality gate → stale revision, unsupported claim или ambiguous prompt outcome.
• Compatibility gate → advertised capability не соответствует method behavior.
• Recovery gate → retry не дублирует effect и не ломает audit chain.