Writing instructions for a voice agent
The prompt your agent follows on every call. A structure that works, the paragraph most people miss, and how to fix an agent that invents facts or wanders off topic.
10 min readUpdated 26 August 2026
The Instructions card is described on the page as the agent's job, tone, and what it should and should not do. It is one text field, and it changes call quality more than every other setting on the page put together.
Most agents that behave badly are not badly modelled. They are badly briefed. This page is about the briefing.
A structure that works
There is no required format. This order works because each part answers a question the agent will otherwise answer for itself.
- Who you are and what this agent handles.
- What to do with anything outside that.
- The facts it will need on nearly every call.
- What it must never do.
- How it should sound, in one line.
You answer the phone for [business], a [what you do] in [where].
You handle: [the two or three things this agent is for].
Anything else:
- Billing questions: take a name and number and say someone will call back.
- Complaints: apologise once, take the details, transfer to [who].
- Anything you are unsure about: say you will have someone confirm, and take a number.
Never guess.
Facts you will need often:
- Open [hours]. Closed [days].
- We are at [address].
- We do not offer [the thing people ask for that you do not do].
Never:
- Quote a price that is not in your knowledge base.
- Promise a date, a refund, or an outcome.
- Guess someone's name. If you do not know it, greet generically.
- Claim to be a human if asked directly.
Tone: [warm and brief / formal and precise]. Keep answers to two or three
sentences. Do not read lists aloud; say them as a sentence.Lead with the job, not the personality
The common mistake is opening with tone. Friendly, professional, warm, helpful. None of that tells the agent what to do when a caller asks about a refund on a booking line.
Open with what this agent is for and who it serves. Tone is worth one line, and it belongs near the end where it modifies everything above it rather than standing in for it.
Why does my agent go off topic?
Almost always because nothing told it where anything else should go. An agent briefed to book appointments will keep trying to book an appointment for a caller who rang about a refund, because booking is the only destination it knows.
The paragraph covering everything out of scope is the single highest value part of most prompts, and it is the part most people skip. Name the cases you already know come up, and say where each one goes.
- Requests this agent does not handle, and who they should be transferred to.
- Angry or distressed callers, and the point at which it should stop trying and hand over.
- Questions it does not know the answer to, and what to do instead of guessing.
- Callers who ask to speak to a person.
Why does my agent make things up?
Because it was asked something it did not have and nothing told it that inventing an answer was worse than not having one.
Two things fix this together, and neither works alone. A prohibition, stated plainly. And somewhere real to get the answer, which is what a knowledge base is for.
Prohibitions work better than encouragement because they are checkable. A caller cannot tell whether the agent was suitably warm. They can absolutely tell that it quoted a price that does not exist.
Careful
If an agent invents facts, do not reach for tone. Add the prohibition, attach a knowledge base, and tell it what to say when the answer is not there.
Give it the facts it needs constantly
Opening hours, the address, what you actually sell, what you deliberately do not sell, the name it should use for itself. Anything needed on most calls belongs in the prompt.
Anything needed occasionally belongs in a knowledge base instead. The distinction matters more than it looks, because of what comes next.
Length is not free
The instructions are read on every turn of every call, not once at the start. A long prompt is therefore a recurring cost across the whole call, and across every call the agent ever takes.
This is not an argument for a bad prompt. It is an argument for cutting the decorative parts and keeping the load bearing ones. A paragraph explaining your company values costs money on every exchange and changes nothing the caller experiences.
Write for speech, not for the page
This text becomes talking. Instructions that produce good writing routinely produce bad speech.
Lists are the clearest example. Ask for a list and the agent will read one out, numbers and all, which nobody wants on a phone call. If you want three options mentioned, say to mention them in a sentence.
- Say how long answers should be. Two or three sentences is a common instruction and it works.
- Say not to enumerate. "Say them as a sentence, not as a numbered list."
- Say what to do when there is a lot to cover. Usually: ask which part they want first.
What Improve with AI is for
Next to the Instructions label there is an Improve with AI button. It rewrites what is already there, which makes it a second pass rather than a way to start.
It is at its best on a prompt you wrote quickly and know is untidy. It tightens structure and fills obvious gaps.
Read every line of what comes back before you keep it. A rewrite can smooth away a restriction you put in deliberately, and a prohibition that quietly disappears is exactly the kind of change you find out about from a call that has already gone wrong.
Tip
Keep your own copy of a prompt you are happy with before rewriting it, here or anywhere else.
Then listen to real calls
No prompt survives contact with callers. Use Talk to your agent after every meaningful edit, and read transcripts of real calls afterwards.
Nearly every improvement you will make comes from hearing the agent do something you did not anticipate. That is not a failure of the prompt. It is the only way anyone finds the cases they did not think of.
Common questions
- How long should my agent's instructions be?
- Long enough to cover the job, the out of scope cases and the prohibitions. Length costs something on every turn of every call, so cut what is decorative and keep what is load bearing.
- Why does my agent keep going off topic?
- It has not been told where anything outside its job should go. Add a paragraph naming the cases you know come up and where each one is sent.
- Why does my agent invent prices or details?
- It was asked for something it did not have. Add an explicit prohibition against quoting anything not in its knowledge base, attach a knowledge base, and tell it what to say when the answer is not there.
- Why does my agent read out lists on the phone?
- Because nothing told it not to. Say explicitly that options should be spoken as a sentence rather than enumerated.
- Should I put my prices in the instructions or a knowledge base?
- A knowledge base, if there are more than a handful or they change. Instructions are read on every turn, so a price list there costs money continuously and goes stale in a place that is easy to forget.
- Does Improve with AI overwrite what I wrote?
- It rewrites what is in the field, so keep your own copy first. Read the result before accepting it, particularly the restrictions.
- Do instructions change the agent's voice?
- No. They change what it says and how it phrases things. The voice itself is on the Voice & model card.
Was this helpful?