A prompt tells an agent what you want. A spec tells it what to do when things go wrong. That second part is where most agent builds quietly fall apart.
If you have ever handed an agent a long, careful prompt and still got strange results, the prompt was probably fine. What was missing was everything around it: what the agent is allowed to touch, what finished looks like, and when it should stop and ask for help.
A prompt is a wish. A spec is a job description.
Think about hiring a new team member. You would not hand them one paragraph and walk away. You would tell them the goal, what they can use, what good work looks like, and who to call when something does not fit. You would also tell them what is not their call to make.
An agent needs the same thing, and it needs it written down, because it will not read your mind and it will not pick up on hints. When an agent is unsure, it does not feel awkward and ask a colleague. It guesses, and it sounds confident while doing it.
That is why we write a spec for every agent we build, even small ones. A spec is just a short document with a fixed shape. The shape matters more than the length.
The parts of a spec
1. The goal, in one sentence. If you cannot say it in one sentence, the agent is probably doing two jobs. Split it into two agents.
2. The inputs. List exactly what the agent receives and where it comes from. A form entry, a row in a sheet, a forwarded email. Say what to do if an input is empty or looks wrong.
3. The tools it may use. Name them. Say what each one is allowed to do. "Read the CRM" and "edit the CRM" are very different permissions, and the spec should make that clear.
4. The output. Describe the exact shape of what comes back. Fields, length, format, where it gets saved. If a person or another agent reads the output next, write the spec with that reader in mind.
5. What done means. Agents will happily keep going or stop early if you do not define the finish line. A good definition is something you can check, like "the summary, the rating and the draft are saved to the record."
6. Escalation rules. This is the part people skip, and it is the most important one. We cover it in detail below.
7. A few examples. Show one clean case and one messy case. Examples teach tone and edge cases faster than extra rules do.
Escalation rules are the difference
An escalation rule says: in this situation, stop, do not guess, and hand it to a person. Without these rules, an agent treats every situation as something it can solve. Most of the time that works. The few times it does not are the ones that cost you a customer, a deadline or a bad email that cannot be unsent.
We find it helps to think in three kinds of triggers.
- Missing information. A required input is empty, the company cannot be found, or two sources disagree.
- Low confidence. The agent cannot explain its decision in one plain sentence. This is a handy test. If it cannot explain the choice, it should not make it alone.
- High stakes. The task touches money, legal topics, a complaint, a deletion, or anything that cannot be undone.
Just as important is how to escalate. Tell the agent to stop, write one sentence on what blocked it, say what it needs, and tag the right person. Without that, you get a pile of vague flags nobody wants to read.
A simple template
Here is the skeleton we start from. Change the words, keep the shape.
GOAL Review new inbound leads and draft a first reply for a person to approve. INPUTS The lead form entry, the company website, our pricing page. If any of these are missing, escalate. TOOLS YOU MAY USE Read the CRM. Create a draft in the email tool. Nothing else. OUTPUT A two sentence summary, a fit rating of high, medium or low, and a draft reply under 120 words. Save all three to the lead record. DONE MEANS The summary, rating and draft are saved. You have not sent anything. ESCALATE TO A PERSON WHEN The lead mentions legal, refunds or a complaint. The company cannot be found. You cannot explain the fit rating in one sentence. The request is outside what we sell. Anything would require sending, deleting or changing existing data. HOW TO ESCALATE Stop. Write one sentence on what blocked you and what you need. Tag the owner. Do not guess. EXAMPLES One clean lead with the ideal output. One messy lead with the correct escalation.
Notice how much of this is about limits. That is on purpose. The more room an agent has, the more a spec has to say about where the edges are.
Mistakes we see most
- Soft words. "Appropriate," "relevant" and "if needed" all invite guessing. Replace them with something the agent can check.
- Mixing tone with rules. Keep voice guidance in its own section so it does not blur into hard limits.
- No owner for escalations. A flag that goes to nobody is the same as no flag.
- Only testing the happy path. Agents look great on clean inputs. The spec earns its keep on the bad ones.
- Treating the spec as finished. Every escalation you see in real use teaches you a rule you did not know you needed.
How to test a spec
Before an agent goes live, run it on a handful of ugly inputs on purpose. An empty field. A rude message. Something outside the job. A request that sounds urgent but is not. Then read what it did and, more importantly, what it chose to escalate.
If it never escalates, your rules are too loose. If it escalates everything, they are too tight. You are looking for an agent that handles the routine work quietly and speaks up at the right moments.
Where to start
If you already have an agent running on a prompt, do not rewrite everything. Add one section: escalate to a person when. Write five situations where you would want to be called. That alone will change how the agent behaves, and it will show you how much of the rest of the spec is missing.