The instruction block that has to survive forty turns

Why agent prompts are a different craft

In a chat, the system prompt sits close to the only user message and its influence is obvious. In an agent it sits at the top of a transcript that grows by a tool result every few seconds. It is re-sent on every call (it does not fall out of the window, it is the last thing anyone drops) but by turn eighteen it is one paragraph among forty thousand tokens of recent, vivid, specific evidence about the task at hand.

This is the mechanism behind the most common complaint in agent development: it followed the rule at the start and stopped following it later. Nothing was forgotten. The rule was outvoted.

Two consequences follow, and they shape everything below. Instructions that must hold late in a run should be restated where the decision happens: in the tool description, or in the tool result itself. And anything you need guaranteed does not belong in a prompt at all.

A structure that holds up

Order matters less than completeness, but this order works:

1. Role and goal in two sentences. What this agent is for, and what “done” looks like.
2. The environment. What exists in the world it can touch: repository, inbox, database, the fact that today’s date is supplied in the last message.
3. Tool policy. Which tool to reach for first, and what to do when one fails. Two or three short worked traces beat a paragraph of description: ”Ticket about billing → call lookup_account, then recent_charges, then answer. Never answer billing questions from memory.”
4. Hard constraints, stated positively. “Only email addresses returned by lookup_contact” is enforceable and checkable. “Never email anyone you shouldn’t” is a mood.
5. The stopping condition. When to stop, and what to produce when it stops without succeeding. Agents that will not admit failure loop until the budget runs out.
6. Output format for the final answer.

Tool descriptions are part of the prompt

This is the single highest-leverage place to write, and most teams leave it as an afterthought. Every tool’s description is sent on every turn and sits directly beside the choice it governs. So the sentence “use this only after search_orders has returned an order id” belongs in the description of the tool it constrains, not in a bullet forty messages up. Same words, far more effect, because it arrives at the moment of the decision rather than at the start of the day.

Negative instructions are weak

“Never delete anything” is a request. The control is a database role with no DELETE grant. “Do not spend more than five pounds” is a request; the control is a counter in your loop that raises when the total is exceeded. This is worth internalising early, because a great deal of agent writing consists of adding more forceful phrasing to a channel that was never going to carry a guarantee. Capital letters do not change the category of the thing.

Use the prompt for what only the prompt can do, telling the model what good work looks like here, and put the boundaries in code.

Version it like code

The prompt is a deployed artefact. Keep it in a file in the repository, give the file a version identifier, and log that identifier with every run alongside the pinned model id. A prompt edited in a vendor’s web console at six in the evening is an untracked production deployment with no rollback, and when the failure rate moves next week nobody will be able to say what changed.

The cost you did not budget for

A two-thousand-token system prompt on a twenty-turn run is forty thousand input tokens before the task contributes anything. Prompt caching changes this substantially (providers cache a prefix and charge a fraction for cache hits) but only when that prefix is byte-identical between calls. Which gives a concrete rule: never put anything volatile at the top. The current time, a request id, a random session token in the system prompt turns every call into a cache miss. Put volatile values in the last message.

Knowing which sentence did the work

You will not know by reading. The honest method is ablation: remove one paragraph, run your fixed set of tasks, compare. Most teams who do this discover that a third of the prompt is inherited superstition: instructions added after a bad run months ago, which never did anything measurable and now cost tokens on every call. Deleting them is one of the few changes in this field that is both cheaper and better.