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
General API access with prompt guardrails
Prototypes on synthetic data
Cost: The prompt is the only control; one edit widens authorityRead-only access, humans do all writes
Pure assistance
Cost: No drafts; limited valueA small catalogue of task-specific tools with enforced contracts
Agents that draft or act in systems of record
Cost: Tools to design, version and test04Decision
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
- Authority can be reviewed by reading the tool catalogue.
- Prompt changes cannot widen what the agent can do.
- Retries and duplicate requests are safe by construction.
- Adding a capability is a design decision with a contract, not a configuration change.
06Revisit when
The platform provides fine-grained, enforceable agent permissions natively.
The agent only reads and summarizes.
07Where this decision is applied
Cases that take this decision, and why it matters there.