ADR / 014

Expose agent capabilities as bounded tool contracts, not raw system APIs

Each tool states purpose, input, output, permissions, preconditions, side effect, failure and reversibility—and enforces them in code, so the prompt is not the last line of defence.

Reference pattern

Independently created. Contains no employer or client implementation detail, internal names or figures.

01Context

A pilot agent used an integration user with general API access to the CRM. It could read and write any object the integration could. Guardrails lived in the system prompt. A prompt change during testing let it update opportunity stages it was only meant to read.

02Decision drivers

  1. D01

    Least privilege for an actor that reasons probabilistically

  2. D02

    Rules enforced where they cannot be talked around

  3. D03

    Idempotency across retries and duplicate requests

  4. D04

    Reviewable, testable capabilities

03Options considered

Options considered: when each would be the right choice, what it costs, and the verdict under these premises
OptionRight whenCost / trade-offVerdict
General API access with prompt guardrailsPrototypes on synthetic dataThe prompt is the only control; one edit widens authorityRejected
Read-only access, humans do all writesThe agent only assists and never drafts into a systemNo drafts; limited valueSituational
A small catalogue of task-specific tools with enforced contractsAgents that draft or act in systems of recordTools to design, version and testSelected

Every option is right under some premises. The verdict applies to the context above.

04Decision

Expose only task-specific tools. Each has a contract—purpose, typed input and output, permissions, preconditions, side effect, failure behaviour and reversibility—enforced in the tool: drafts cannot become records, messages cannot be sent without an approval reference, duplicate request IDs return the existing result. Consequential capabilities (discount approval, ERP customer creation, account merge) are not tools. Tools run with the requesting user’s visibility, and every call is recorded in the trace.

05Consequences

What this choice changes elsewhere in the system.

  1. Authority

    Authority can be reviewed by reading the tool catalogue.

  2. Security

    Prompt changes cannot widen what the agent can do.

  3. Idempotency

    Retries and duplicate requests are safe by construction.

  4. Change & release

    Adding a capability is a design decision with a contract, not a configuration change.

06Revisit when

The decision holds while its context holds. Challenge it when:

01

The platform provides fine-grained, enforceable agent permissions natively.

02

The agent only reads and summarizes.

07Where this decision is applied

The decision says why this path was chosen; each case shows how it takes part in a larger architecture.

  1. AI case / 01Designing evidence-grounded AI preparation for commercial decisionsOne architecture used before a customer visit and before an account review: governed context assembled deterministically, a context contract per source, every statement typed and cited, bounded read-only tools, explicit behaviour when context is stale, conflicting or missing—and the decision left with a person.AI & Agentic WorkflowsRevenue OperationsData & IntegrationsArchitecture case · 12 min
  2. AI case / 02Designing AI-assisted intake for unstructured commercial workA shared commercial entry point turned into structured, owned work: a taxonomy written before the model, mixed intent decomposed into work items that share one source reference, entities offered as evidence-backed candidates, owners and clocks assigned by deterministic rules, review placed where ambiguity becomes consequential—and no external commitment without a person.AI & Agentic WorkflowsProcess ArchitectureAutomationArchitecture case · 11 min
  3. AI case / 03Designing AI-assisted data stewardship without moving master-data authorityAI that makes stewards faster without becoming the steward: candidates found, ranked by impact and explained with evidence and differences; a governed steward queue; identity, merge and consequential classification decided by accountable people; accepted decisions executed by the system’s own processes; and outcomes that improve evaluation and rules—never the model’s permissions.AI & Agentic WorkflowsData & IntegrationsSystems & CRM ArchitectureArchitecture case · 10 min
  4. AI case / 08Redesigning RFQ processing around AI without moving commercial authority to the agentAn operating-model redesign of RFQ processing: which work needs reasoning, which is a deterministic rule and which carries business authority—then an agent that prepares requests with evidence and never commits them.AI & Agentic WorkflowsProcess ArchitectureSystems & CRM ArchitectureArchitecture case · 9 min

Decisions this one depends on, or constrains.

  1. ADR / 013Grant agent authority per action and consequence, never by confidenceClassify every action an agent could take—read, recommend, draft, execute, human approval or forbidden—by its consequence and reversibility. Confidence changes how work is presented, not who may commit it.Proposed patternAI · Authority · Governance