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.
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
- D01
Least privilege for an actor that reasons probabilistically
- D02
Rules enforced where they cannot be talked around
- D03
Idempotency across retries and duplicate requests
- D04
Reviewable, testable capabilities
03Options considered
| Option | Right when | Cost / trade-off | Verdict |
|---|---|---|---|
| General API access with prompt guardrails | Prototypes on synthetic data | The prompt is the only control; one edit widens authority | Rejected |
| Read-only access, humans do all writes | The agent only assists and never drafts into a system | No drafts; limited value | Situational |
| A small catalogue of task-specific tools with enforced contracts | Agents that draft or act in systems of record | Tools to design, version and test | Selected |
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.
- Authority
Authority can be reviewed by reading the tool catalogue.
- Security
Prompt changes cannot widen what the agent can do.
- Idempotency
Retries and duplicate requests are safe by construction.
- 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:
The platform provides fine-grained, enforceable agent permissions natively.
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.
- 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 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 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 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.
08Related decisions
Decisions this one depends on, or constrains.