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.
• Запускає user-selected reusable interaction → 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 та valid 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 без trust у 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. Підписки й 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 decisions. Server перевіряє URI, authorization і resource permission на кожне read. Не вкладайте секрет у передбачуваний URI й не припускайте, що невідображений елемент неможливо прочитати прямим request.

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

• Stable browseable content → resource або resource template.
• Live parameterized fact → часто read-only tool.
• Subscription не замінює revision check перед важливим рішенням.
• URI visibility не дорівнює 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.

Versionуйте зміст 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 row як 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.

Перед реалізацією заповніть коротку картку: 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 починайте з capability combinations: 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.