Every Agent Prompt Is a Contract. Write It Like One.
You wrote a friendly instruction. The agent read a contract. The gap between those two things is where every surprise comes from.
Someone showed us their marketing agent prompt last month. It read: "You are a helpful marketing assistant. Write engaging content and post it on the right channels at the right time. Be professional."
Their next question was why the agent had just posted a customer testimonial in the wrong tone to the wrong audience on the wrong day.
You wrote a suggestion. The agent read that suggestion as a binding instruction, filled in every gap with its best guess, and shipped. That is what agents do.
#What a prompt actually is
Every time you write instructions for an agent, you are signing a contract. The agent will do what you asked, exactly, and everywhere you left a hole it will fill the hole with its own judgment. The prompt is the whole spec. There is no attached "you know what I meant" clause.
The friendly-instruction style leaves most of the spec unwritten. "Write engaging content" is not a spec. It is a vibe. When the agent runs, it has to turn that vibe into concrete choices about tone, length, channel, timing, and topic. It will make those choices. You will not know which ones it made until you see the output.
A prompt written like a contract closes the holes on purpose.
#The four parts that matter
A prompt that behaves predictably has four sections. Miss any one of them and you are back to guessing.
#1. Inputs the agent can use
Name the sources the agent is allowed to read. Not the sources it should probably use. The ones it is allowed to use. Everything else is off-limits.
Example: "Use the last 30 days of our blog posts and the current brand voice guide at /docs/voice.md. Do not use general internet content or older company material."
Without this, the agent pulls from wherever. Old drafts, deprecated pages, its own training data. You get output that is technically on-brand for a version of your brand you retired two years ago.
#2. Outputs the agent must produce
Name the shape, not just the content. Number of items, format, target length, required fields, forbidden phrases.
Example: "Output: three post drafts, 80 to 120 words each, plain markdown, no headings, one call-to-action per post."
"Write a good post" produces one thing. "Three drafts, 80 to 120 words, plain markdown" produces three predictable things you can compare.
#3. Failure modes named on purpose
List the things you do not want, by name, with why.
Example: "Do not use the phrase 'game-changing.' Do not fabricate metrics. Do not repeat a topic covered in the last 14 days."
This part feels defensive. It is worth writing anyway. Every constraint you name is a constraint the agent no longer has to guess at. The agent stops testing that boundary because the boundary is now in the contract.
#4. Escalation path
Say what the agent should do when it cannot meet the contract. Silence is the wrong default. So is bulldozing forward.
Example: "If the input is ambiguous or missing, stop and post a question in Slack channel #agent-questions instead of shipping. If the required tone conflicts with the brand voice guide, defer to the brand voice guide."
Without this, an agent that hits a gap either freezes or invents. Both are bad. A named escalation gives it a third option: ask.
#The rewrite of that marketing prompt
Here is the friendly-instruction version:
You are a helpful marketing assistant. Write engaging content and post it on the right channels at the right time. Be professional.
Here is the contract version:
Role. Draft social posts for our LinkedIn company page.
Inputs. Use only the brand voice guide at
/docs/voice.md, our last 30 days of published posts, and the current product changelog. No general internet content.Outputs. Three post drafts per day, weekdays only, 80 to 120 words each, plain text, one CTA per post. Include the target publish time in the post header.
Failure modes. Do not fabricate metrics or customer names. Do not repeat a topic covered in the last 14 days. Do not use "unlock", "leverage", "seamless", or "game-changing".
Escalation. If a topic has been covered recently or if the changelog is empty, ask in #marketing-drafts before drafting. If a source contradicts the brand voice guide, defer to the guide and flag the contradiction.
Same job, same agent, same underlying model. Wildly different behavior.
#Why this reads like extra work but is not
The contract version is longer. It also removes the entire class of problems where you review the output, spot something wrong, and go through a "no, not like that" cycle with the agent. That cycle is where most agent-owner time gets burned. Every clarification you write into the initial contract is one you do not have to send later.
Think of it like hiring. You would not tell a new employee "just be helpful and figure it out." You would tell them what to do, what tools to use, what to avoid, and who to ask when they are stuck. Agents need the same brief. Their advantage over a new hire is they will follow it exactly. Their disadvantage is they will follow only what is in it.
#Want us to look at your agent prompts?
If you are already running agents and getting inconsistent output, most of the time the fix is in the prompt, not the model. We can review your current instructions and rewrite them as contracts.
