Eight months after the insurer's assessment platform went live, a new architect joins the platform team. Her first ticket says: "Marketing wants their campaign agent to read roof ages. Add them to the MCP server." She opens the server's repository and finds the code. She opens the catalog and finds the tool entries. What she cannot find is why. Why does the underwriting agent call the assessment service directly while the claims agent goes through MCP? Why does the support desk get a summary tool instead of the full assessment? Why can no agent hold uw.decide? Every one of those choices was argued in a meeting. None of the arguments was written down.
So she does what most people do. She copies the claims team's setup for marketing, grants uw.read, and ships. Marketing's agent can now read every assessment in its business unit, including evidence ids that the analytics team was deliberately denied. Nothing in the code is wrong. The reasoning that protected the data was never in the code.
This page is the part of the design that is not code: the checklists that make a decision quickly, and the records that keep its reasons.
Why decisions need a record#
A decision playbook is a short, ordered list of questions that leads a team to a choice and tells it what to check before acting on it. An example: "Does more than one host application need this capability? If no, stop: use a function." A playbook is for the moment of deciding.
An architecture decision record (an ADR) is a short document that states one decision, its context, the options considered and the consequences, written when the decision is made and kept with the code. An example: "ADR-007: Analytics reads aggregates only. Context: per-submission data includes evidence ids. Decision: a separate stats tool. Consequence: analytics cannot debug one submission." An ADR is for the moment someone asks why.
Before AI. Backend teams have used both for years. A runbook is a playbook for an incident. An ADR in a docs/adr/ folder, numbered and never edited after acceptance (only superseded), is a common practice from service-oriented architecture. Nothing about agents changes the format. What changes is the number of decisions that look like plumbing ("add a tool") but are really access decisions.
The rest of this page gives the playbooks in the order the site taught the questions, then five ADRs for the insurance platform, written the way a team would write them.
Diagram: Playbook 1 as a path · stop at the first rung that works
Read left to right and stop at the first box whose question you answer yes. Each later box adds a party who must operate or approve something. Sensitive data adds identity and audit whichever interface you choose. Click a box for the question behind it.
- 1 · Same application?
- Direct function: If the code that needs the capability runs in the application that owns the data and its credentials, call the domain service directly.
- 2 · Non-agent callers?
- HTTP API: If batch jobs, web apps or other services need it, an HTTP API is the shared contract; agents may also call it as a tool.
- 3 · Several agent hosts?
- MCP adapter: If two or more different agent hosts must discover and call it without integration code each, an MCP server is justified, as an adapter.
- 4 · Sensitive data?
- Identity + audit: Whatever the interface, shared sensitive data needs central identity, scoped authorization at execution and audit events.
Playbook 1: function, HTTP API or MCP?#
Answer the questions in order. Stop at the first answer that settles it.
| # | Question | If yes | If no |
|---|---|---|---|
| 1 | Does the code that needs the capability run in the same application that owns the data and its credentials? | Use a direct typed function. Keep the application's transactions and authorization. Go to question 5 only if a model will request it | Go on |
| 2 | Do programs that are not agents need it too (batch jobs, web apps, other services)? | Offer or reuse an HTTP API. It is the shared contract. Go on to see whether agents also need MCP | Go on |
| 3 | Do two or more different agent hosts need to discover and call it, without integration code per host? | An MCP server is justified. Make it an adapter over the same domain service, never a copy of its rules | Stay with a function or the API; an agent can call an HTTP API as a tool |
| 4 | Does the capability touch sensitive or shared data? | Remote server with central identity, per-call authorization and audit. Read Enterprise authorization before building | A local server may be enough for one machine and one user |
| 5 | Will a model request it? | Treat every request as untrusted input: validate, authorize, execute in code. Function calling | It is ordinary code; no tool definition needed |
The table encodes the honest decision table from Start. Three things it deliberately does not ask. It does not ask whether MCP is modern; that is not a reason. It does not ask whether the capability touches a database; The database decision shows that MCP is never required for that. And it does not ask whether an SDK makes the server easy to write; writing the server is the cheap part.
Common confusion. "MCP or API" is often a false choice. In the example the assessment service has a direct caller (the underwriting agent's application), a REST endpoint (the support desk's ticketing system) and an MCP server (the other agents). Three adapters, one service, one set of rules. The question is which adapter each caller should use.
Playbook 2: the database decision#
When a capability reads or writes a database, decide where the database account lives before you decide anything else.
| Check | What to write down | Where it is taught |
|---|---|---|
| Who holds the database credentials? | One owning service. Never every consuming agent | The database decision |
| What is the database account allowed to do? | A grant per table and per operation; reads and writes in separate accounts | The database decision |
| Who owns the transaction? | The domain service. Not the MCP server, not the model | The database decision |
| Who owns the schema, and who must release when it changes? | The domain team; consumers depend on the contract, not on tables | Sharing across teams |
| Is a write idempotent? | The key, who chooses it, and how a retry finds the stored result | Resilience |
This site's recommendation: if the answer to the first row is "every agent that uses it", stop. That design gives the database's authorization model to whoever controls an agent's prompt.
Playbook 3: publishing a tool to other teams#
A tool another team can discover is a product with users. Before a tool reaches the state "discoverable" in the catalog, check:
| Check | Owner who signs it |
|---|---|
| Name, description and version follow the catalog's naming rules; no two tools mean the same thing | Server maintainer, platform team |
| Input and output schemas are versioned; the change policy is stated | Server maintainer |
| Scopes are defined and approved; write tools need a stronger scope than read tools | Identity and security governance |
| Risk tier is assigned (what data, read or write, reversible or not) | Domain data owner, security |
| Owner and on-call are named; an incident route exists | Domain data owner, platform team |
| Audit events are written for every allowed and refused call | Server maintainer, audit and compliance |
| Deprecation path for the previous version is published | Server maintainer, consumer application owners informed |
Governance has the lifecycle and the full RACI matrix behind this list.
Playbook 4: authorizing a new consumer#
The marketing request at the top of this page is this playbook. Answer before granting anything:
- Which principal will call: a person through an application, or an agent with its own workload identity?
- Which tools does it need, and which data inside them? If the answer is "the same as team X", ask why team X has what it has: read that team's ADR.
- What is the narrowest scope that works? Is there a summary or aggregate tool that would do?
- Which business units may it see? Is the tenant check enforced at execution, not only in the list?
- Who approves the scope, and who reviews it in six months?
- What audit query would show misuse, and who reads it?
This site's recommendation: a new consumer gets a new client id and its own rate limit and metrics, even if it shares scopes with another team. Shared identities make an incident impossible to scope.
Playbook 5: retiring a tool#
| Step | Done when |
|---|---|
| Mark the version deprecated in the catalog with a date | Discovery results carry the deprecation notice |
| Find every consumer | Audit events by client_id over the last 90 days (illustrative window) list them |
| Tell each consumer application owner | Each has a migration ticket |
| Watch calls to the old version fall | The per-version call count is zero for the agreed period |
| Retire | The tool is no longer offered; a call by name returns an error that names the replacement |
| Write the ADR that supersedes the old one | The reason survives the code |
This site's own case UW-M07 is what happens when step 3 is skipped: a client built against version 1 of get_roof_assessment still sends property_id, and the server answers with an invalid-arguments error.
Five decision records for the insurance platform#
The records below are written for the synthetic insurer. They are short on purpose: an ADR that takes an hour to read will not be read. Each one names the page that holds the reasoning in full.
Diagram: Where a decision lives · record, catalog, test
A decision becomes durable in three places. The record keeps the reasons, the catalog entry links the record to every tool it governs, and a fitness check in CI fails when someone changes the code against the decision. Click a box for an example from the insurance platform.
- 1 · Decide
- Decision review: Domain data owner, server maintainer, identity and security governance, and each consuming team agree on interface and access.
- 2 · Record
- ADR: Context, options, decision and consequences in a short numbered document kept with the code.
- 3 · Link
- Catalog entry: Each tool's entry names the records that govern it, so a reviewer finds the why from the what.
- 4 · Enforce
- Fitness check: A test that verifies the decision still holds after every change.
ADR-001: the underwriting agent calls the assessment service directly#
| Field | Content |
|---|---|
| Status | Accepted |
| Context | The underwriting agent and the assessment service are owned by the same team, deployed together, and share a database account with write grants on recommendations only |
| Options | Direct function call; the internal HTTP API; the remote MCP server |
| Decision | Direct function call through the service's typed interface |
| Consequences | No extra hop, the application's transactions apply. The agent does not appear in the MCP server's metrics; its audit events come from the service instead. If the agent moves to another team, revisit |
| Reasoning | The database decision, playbook 1 question 1 |
ADR-002: claims, support and analytics agents use the remote MCP server#
| Field | Content |
|---|---|
| Context | Three teams, three agent hosts, one in Java; none owns the data |
| Decision | One remote MCP server uw-assessment, run by the platform team, wrapping the assessment service |
| Consequences | One place for discovery filtering, per-call authorization, audit and per-team metrics. The platform team is on call for the server; the assessment domain stays on call for the service |
| Reasoning | Sharing across teams, Reference architecture |
ADR-003: no agent may record an underwriting decision#
| Field | Content |
|---|---|
| Context | The specification for the platform asked for a decision write tool. Agents read text from brokers; injected text has asked agents to approve (series case UW-005) |
| Decision | record_underwriter_decision is offered only to a person with the underwriter role, acting through the cockpit with a delegated token. The check is on the principal type, not only the scope |
| Consequences | A mistaken grant of uw.decide to an agent does not let it decide. The model recommends; a person decides |
| Reasoning | Who gets access, Threat model, case UW-M09 |
ADR-004: the server never forwards the caller's token#
| Field | Content |
|---|---|
| Context | The MCP server must call the assessment service on behalf of callers |
| Decision | The server validates the caller's token for its own audience, then obtains a separate downstream token for the service's audience. It never passes the received token on |
| Consequences | The service can tell the server's calls apart; a token stolen from one hop cannot be replayed at another. Requires a token exchange or a service credential |
| Reasoning | Enterprise authorization, case UW-M04. Normative (MCP specification 2026-07-28): the specification forbids token passthrough |
ADR-005: analytics reads aggregates only#
| Field | Content |
|---|---|
| Context | Analytics asked for per-submission assessments to compute regional statistics |
| Decision | A separate tool get_assessment_stats returns counts per business unit; get_roof_assessment is refused for analytics-jobs |
| Consequences | Analytics cannot inspect one submission. A request for that goes through the domain owner. Case UW-M12 tests it |
| Reasoning | Who gets access, Sharing across teams |
With these five records the new architect's ticket answers itself. Marketing is a new consumer (playbook 4). ADR-005 shows that per-submission access was refused to a team with a weaker need than underwriting. The right first offer is the aggregate tool, a new client id, and a scope review with the domain owner.
In a coding agent. The same records help a team that gives coding agents MCP servers. "ADR: coding agents may open pull requests but never merge" is the coding equivalent of ADR-003. "ADR: the repository server runs locally with the developer's rights; the deployment server is remote and needs a token with the environment as audience" is ADR-002 and ADR-004 together. Diff to Deploy follows those permissions through a real change.
What this is not. These playbooks decide interfaces and permissions for capabilities. How to judge whether an agent's answers are good enough to ship belongs to eval.sammuthu.com; how to recover a whole workflow after a failure belongs to https://reliable.sammuthu.com.
A fitness check you can automate#
A fitness check is a test that verifies an architecture decision still holds, run in continuous integration like any other test. An example: "No agent token in the test fixtures can call record_underwriter_decision." When someone changes the policy, the check fails before the change ships. Several ADRs above become fitness checks directly:
| ADR | Fitness check |
|---|---|
| ADR-003 | For every agent principal, record_underwriter_decision is refused even with uw.decide granted |
| ADR-004 | The server's outgoing request to the service never carries a token whose audience is the server |
| ADR-005 | analytics-jobs is refused get_roof_assessment for every submission in the fixtures |
| Playbook 3 | Every catalog entry in state "discoverable" has an owner, an on-call, a risk tier and an approved scope |
Testing shows the authorization matrix that turns rows like these into one test per cell.
Keeping ADRs aliveSupersede, never edit; link from the catalog; review on a schedule
An ADR that is edited after acceptance stops being evidence: nobody can tell what was decided when. The common practice is to write a new ADR that supersedes the old one and to mark the old one "superseded by ADR-012". The record of change is then the list of ADRs itself.
For a shared capability, store the ADR id in the catalog entry of each tool it governs. A reviewer who opens get_assessment_stats in the catalog sees ADR-005 one click away, and the platform team can find every tool affected when ADR-005 is superseded.
Review on a schedule, not only on change. This site's recommendation: every six months (illustrative), the domain data owner reviews the ADRs that grant access to their data and either reaffirms or supersedes them. Access decisions decay quietly: teams change purpose, agents gain tools, and nobody notices until an audit asks.
Signals that MCP was the wrong rungSymptoms that a team climbed too high, and how to step down
Some symptoms show that an MCP server was added where a lower rung would have done. Only one host ever connects to it. Its tools are called only by code that knows exactly which tool it needs, never chosen by a model. It holds business rules that also exist in the domain service. Its on-call rotation is the same people as the service's, and every incident touches both. Its catalog entry has no consumers outside its own team.
Stepping down is cheap if the server was a thin adapter: the host calls the service directly, the server is deprecated with playbook 5, and nothing about the domain changes. Stepping down is expensive if the server grew rules of its own. That asymmetry is the practical argument for keeping every MCP server an adapter.
The opposite symptom also exists: a team that refused MCP and now maintains five slightly different integrations of the same capability in five agent hosts, each with its own authorization code. That team climbed too slowly.
Running a decision review in practiceWho is in the room, what they bring, and how long it takes
For a new shared capability the review that produces ADRs like the five above needs four roles and about an hour (illustrative). The domain data owner brings the data classification and says which fields are sensitive. The server maintainer brings the draft catalog entry and the schemas. Identity and security governance bring the scope model and say which principals may hold which scopes. A representative of each consuming team brings the use case in one sentence and the narrowest data that would serve it.
The output is the ADRs, the approved scopes and a catalog entry in state "approved". The output is not code. If a review ends with "we will figure out permissions later", the capability is not ready to be shared.
Exercises#
- A finance team's batch job (no agent) needs roof ages nightly. Which rung? Answer below.
- A single developer wants their desktop assistant to read their own local notes. Local or remote MCP, or neither?
- A vendor offers a hosted MCP server that reads your claims data. Which playbooks apply before anyone connects to it?
AnswersOne line each
- The existing HTTP API (playbook 1, question 2): it is not an agent and needs no discovery.
- A local MCP server, or a built-in function of the assistant; a remote server adds an operator and a token for one user's own data.
- Playbooks 3 and 4 from the consumer side, plus the Threat model: who operates the server, which audience its tokens have, and what egress it is allowed.
In one breath#
Decide the rung with an ordered checklist: same application, function; non-agent callers, an API; several agent hosts, an MCP adapter over the same service; sensitive data, central identity and per-call authorization. Write each access decision down as a short record with its context and consequences, link it from the catalog, and turn the important ones into fitness checks that fail in CI. The reasoning that protects shared data is rarely in the code, so it has to live somewhere a newcomer will find it.
This is the last chapter. The Glossary holds every term in one place, and About lists the sources, the sister sites and the label convention. If you started here, Start shows the five rungs this checklist chooses between.