Where your instructions go
A pathway has six places you write instructions, and each wants a different kind of writing. The map, and the two mistakes that cost the most.
A prompt-based agent has one box to write in. A pathway has six, and they are not six copies of the same box — each is read by something different, at a different moment, for a different decision. Writing them all in the same voice is the most common reason a pathway that looks right behaves oddly.
The six places
| Where | Read when | What belongs there |
|---|---|---|
| Global prompt | Every step, always | Who the agent is, business facts, rules it must never break, how to sound |
| Step prompt | While in that step | What this moment should achieve |
| Fixed wording | Instead of a step prompt | The exact words, when they must not vary |
| Branch label | Choosing where to go next | The condition, written in full |
| Variable description | Pulling a fact out of an answer | What counts as this thing |
| Tool description | Deciding whether to call a tool | When to reach for it, and when not to |
The three that get written badly are branch labels, variable descriptions and tool descriptions — because they don't look like prompts, so people write them as titles. They're instructions, and the agent reads them as such.
Global versus step
The split that matters most:
- The global prompt is context. It's silently available in every step, so the agent always knows who it is, what you sell, and what it must never say. It doesn't tell the agent what to do right now.
- A step prompt is direction. It says what this moment is for — "find out what kind of work they need and roughly where they are" — and nothing else. It doesn't need to restate the business name, the tone, or the rules. Those are already there.
If you find yourself pasting the same paragraph into several steps, that paragraph belongs in the global prompt. If a step prompt opens by re-introducing the business, delete that sentence — the agent already knows.
You have more room than you think
The global prompt is graded green up to 3,000 characters — around 450 words. Most are a fraction of that, and the agent is worse for it. See the global prompt.
Instructions, not a script
This is the same craft as writing agent instructions, and everything on that page applies here — including writing numbers as words, which matters just as much in a step prompt as in a prompt agent.
The short version: describe what to achieve, not the sentence to say. "Ask which day suits them, and mention we have Saturday availability" produces a different call every time and sounds like a person. The scripted version sounds like a recording, because it is one.
The mistake that costs the most
Never describe a capability the agent doesn't have.
It's tempting to write defensively — "if the booking tool is available, offer times; otherwise take a message." That doesn't work. Testing this directly: with the booking tools removed but the booking instructions left in place, the agent invented availability and offered appointment times that didn't exist. It did not notice the tool was missing and fall back; it filled the gap.
An agent will always try to do what its prompt describes. If the means aren't there, it improvises the result.
So when you turn a capability off, take its instructions out entirely — don't leave them behind a condition. And the reverse: when you attach a tool, say in the prompt when to use it. A tool that's merely available often goes uncalled, because nothing told the agent this was the moment.
Booking in a pathway has to be spelled out
On a prompt agent, switching on appointment setting adds the booking instructions for you — how to look up times, how to offer them, how to confirm. In a pathway, it doesn't. Attaching the booking tools to a step gives the agent the ability and none of the method, and the gap shows up as invented times.
Write it into the step's prompt: look up open times with the slots tool rather than guessing, offer two or three of the returned times out loud, then book the exact slot the caller picked and read the confirmation back.
Branch labels are read alone
The agent choosing which way to leave a step sees the labels and nothing else — not the step's prompt, not your other labels, not anything further up the map.
That has one practical consequence: the label has to be self-contained. "The option they picked" or "matches the second department listed above" has nothing to match against, and every call falls through to whichever branch happens to be first. Write out the condition: "Caller wants billing or has a question about an invoice."
Full guidance on getting these right is in branching.
Descriptions do the work
Two more places where a few extra words pay for themselves:
Variable descriptions. The name is for you; the description is for the agent. service_area tells it nothing — "the town, suburb or neighbourhood the caller says the work is in" tells it exactly what to look for, and what to ignore.
Tool descriptions. This is what the agent reads to decide whether this is the moment. Vague descriptions are the first thing to check when a tool never fires. See when it doesn't fire.
Where to check your work
Everything above is a hypothesis until a caller says something you didn't predict. Testing your pathway runs simulated callers against it, and an ambiguous answer will find a vague label or a missing instruction faster than reading it back ever does.