Design the Boundary Before the Prompt

Most agent projects start with a prompt and end with an incident review. The prompt absorbs the attention because it is the visible part, but it is the least durable component in the system. It changes weekly, it is model-specific, and it has no enforcement power whatsoever. What survives a model upgrade is the boundary: the set of things the agent can reach, the shape in which it reaches them, and what happens between a decision and its effect.

An agent is a control loop with credentials

Strip away the language and an agent is a loop — observe, decide, act, observe again — wrapped around a model that holds your service credentials. Every engineering discipline that applies to control loops applies here. What is the input space? What is the actuator range? What is the failure mode when the controller is confidently wrong? A PID loop with an unbounded actuator is a hazard regardless of how well it is tuned, and the same is true of an agent with an unbounded tool surface, regardless of how well it is prompted.

This reframing changes the order of work. You do not tune first. You bound first.

Tools are an API surface, so design them like one

The most common mistake is exposing internal functions directly as tools because they already exist. Internal functions assume a caller who has read the codebase. A tool has a caller who has read a paragraph.

Useful tools share a few properties. They are typed, with schemas narrow enough that the invalid states are unrepresentable rather than merely discouraged — an enum instead of a free string, an identifier instead of a natural-language description of an entity. They are idempotent where the underlying operation allows it, because retries will happen. They return errors that describe what to do differently, not stack traces. And they are coarse enough that one call accomplishes something meaningful; a surface of forty micro-tools produces long, brittle chains where a surface of six produces short ones.

The strongest constraint is the simplest: separate reads from writes and give them different permissions. A read-only agent is a research assistant with a bad day at worst. A write-capable agent is an operator.

Checkpoints belong where the effect is irreversible

The reflex is to ask a human to approve everything, which produces approval fatigue within a week and rubber-stamping within two. The alternative reflex — approve nothing — produces the incident review.

The useful question is reversibility. Drafting a document is reversible. Sending it is not. Updating a record with full history retained is reversible. Deleting the history is not. Place the checkpoint at the irreversible step, make it show the concrete diff rather than a summary of intent, and let everything upstream run unattended. This keeps the number of approvals proportional to the number of consequential actions instead of the number of steps.

Rate and budget limits are the other half of this. An agent that can call a tool a hundred times in a loop will eventually do so. Caps on tool calls per task, spend per task, and total wall-clock time turn a runaway loop into a failed task, which is a support ticket instead of an incident.

State should be inspectable, not just persisted

When an agent behaves strangely, the question is always the same: what did it see? If the answer requires reconstructing a conversation from logs, debugging is guesswork.

Persist the trajectory as structured data — each observation, each tool call with its arguments, each result, each decision point — keyed to a task identifier. Two things become possible. First, an engineer can replay a failure exactly. Second, the trajectory becomes the input to evaluation, because a graded set of past trajectories is the only honest way to know whether a prompt change helped or simply moved the failures somewhere less visible.

The uncomfortable question

Ask early, and answer honestly: does this need to be an agent?

Agents earn their complexity when the sequence of steps genuinely cannot be known in advance — open-ended investigation, recovery from unpredictable failures, work where the next action depends on what the last one revealed. When the sequence is known, a workflow with a model at the two or three genuinely ambiguous steps is cheaper to build, far cheaper to debug, and dramatically easier to explain to the person who has to sign off on it.

A good deal of what is shipped as an agent is a workflow that was never written down. Writing it down is usually the whole project.