Writing agent instructions that work

The difference between an agent that converts and one that rambles is usually a few paragraphs of instructions.

Agent Instructions — the Agent prompt field you get when an agent's Input Type is set to Prompt — are where you tell the agent who it is and what it's trying to achieve. They're the highest-leverage thing you'll write in ClearTalk, and the easiest to write badly, because it's tempting to write them as if briefing a person who already knows your business.

Everything here applies just as much to the prompt on an individual pathway step. A pathway is a set of small prompts wired together, so the craft is the same at either scale — though a pathway spreads its instructions across six different places, which is its own subject: where your instructions go.

A shape that works

Four parts, in this order:

Who the agent is. Name, business, role. "You are Alex, a scheduling coordinator at Northside Dental." One sentence.

What a good call looks like. The single outcome you want, plus the acceptable second-best. "Your goal is to book the caller for a consultation. If they aren't ready, get permission to follow up and note when." An agent with one clear goal is dramatically more focused than one given five.

How to behave. Tone, pace, and the rules of engagement. "Be warm and brief. Ask one question at a time and wait for the answer. If the caller asks something you don't know, say so and offer to have someone call back."

What never to happen. The guardrails. "Never quote a price. Never promise a specific dentist. Never continue if the caller says they're not interested — thank them and end the call."

That last section is the one people skip and then wish they hadn't. It's how you stop an agent inventing prices or arguing with someone who wants to go.

Write for speech, not for reading

Instructions get spoken. A sentence that reads well can sound stilted or take too long out loud.

Short sentences. The agent mirrors your rhythm.
One question at a time. Stacked questions ("Can I get your name, number, and what day works?") get partial answers and the agent loses track.
Give the exact wording only where it matters — the greeting, a disclosure, a compliance line. Everywhere else, describe the intent and let the agent phrase it.

Describe the intent

“Ask which day suits them, and mention we have Saturday appointments.”
“Confirm the address we have on file, warmly.”
“If they sound rushed, offer to call back rather than pushing on.”

Don't dictate the line

“Say: What day works best for you? We also have Saturdays available.”
“Say: Can I please confirm the address we have on file for you today?”
“Say: I understand you're busy, but this will only take two minutes.”

The right-hand versions are repeated word for word on every single call. That's what people are hearing when they say an agent sounds like a robot.

Write numbers the way you'd say them

This is the single most common cause of an agent sounding wrong that people never think to check.

The voice reads words more reliably than digits. Given a long run of digits it can rush them, slur them together, or drop the last few entirely — a phone number that comes out one digit short, a price heard as the wrong number. Writing the words out is not a style preference; it's the difference between a caller getting your number right and not.

Write it as speech

“We're open nine A M to five P M.”
“The inspection is one hundred twenty dollars.”
“Call us on five five five <|0.3|> two two four <|0.3|> six six eight eight.”
“It's usually one hundred fifty dollars to three hundred dollars.”

Don't leave it as digits

“We're open 9am-5pm.”
“The inspection is $120.”
“Call us on 555-224-6688.”
“It's usually $150-$300.”

The rules worth knowing:

Times — spell the hour and say the meridiem as two letters: nine A M, twelve P M. Minutes under ten need "oh" in front, or they're heard as a separate number: eight oh five A M, not eight five.
Money — one hundred twenty dollars, fifty nine dollars and ninety nine cents.
Ranges — join them with the word "to", never a dash. A dash is silent, so nine A M - five P M is heard as two times with nothing between them.
Phone numbers — one digit at a time, in three groups, with a pause between groups. <|0.3|> inserts a three-tenths-of-a-second pause, which is what stops the voice racing the whole number. End the sentence with a full stop — a number at the very end of a line is where digits get dropped.

Leave these alone

Street numbers, suite numbers, dates and percentages read fine as digits — "45 Oak Avenue", "Suite 210", "12/25", "50% off". Converting them to words makes things worse, not better. The problem is specifically long digit runs and things that need a spoken convention, like the meridiem on a time.

Nothing rewrites this for you

If you build an agent from a template, the times, prices and phone numbers you type into the setup form are converted to speech automatically before they reach the agent. That's the only place it happens. Anything you write yourself — in Agent Instructions, in a pathway step, in a follow-up message — is spoken exactly as you typed it.

Handle the objections you actually get

Don't guess these. Pull ten real transcripts and write down the pushbacks that appear. Then give the agent a line for each:

If the caller says it's a bad time, ask when would be better and offer to call back then.

If the caller asks how much it costs, say pricing depends on the treatment and offer a free consultation where they'll get an exact quote.

If the caller says they're already with another practice, ask whether they're happy there, and if so, thank them and end the call politely.

Three to five of these will cover most of what happens. More than that and you're better off moving to a pathway, where branches are explicit.

Say when to stop

Two of the most valuable instructions you can write:

When to hand off to a person. "If the caller is upset, or asks a clinical question, transfer to the front desk." Agents that try to handle everything produce the worst calls in the system. See Transferring to a human.

When to let go. An agent that won't take no for an answer damages your brand and generates complaints — which, incidentally, is also how phone numbers get flagged as spam. Give it explicit permission to end the call gracefully.

Voicemail deserves its own decision

On outbound calls, a good share of what your agent reaches will be voicemail. Decide deliberately: leave a message, or hang up and try again later. If you leave one, write it — short, one reason to call back, one number, and say the number slowly. A rambling AI voicemail is worse than none. ClearTalk detects voicemail separately from a live answer, so you can treat the two differently.

Improve from transcripts, not from imagination

The loop that actually works:

Ship instructions that are decent, not perfect.
Read ten real transcripts. Not summaries — transcripts.
Find the single worst recurring moment.
Write one instruction that fixes it.
Repeat.

You'll fix more in five rounds of this than in a week of writing up front, because real callers say things you would never have predicted.

Common mistakes

Too many goals. Book the appointment and upsell and collect an email and survey them. Pick one.
Writing a script instead of instructions — then wondering why it sounds like one. If you truly need a fixed sequence, that's a pathway, not a wall of text.
No guardrails, so the agent invents prices, availability, or policies.
Never reading a transcript. By far the biggest one.

When to graduate to a pathway

When your instructions have grown past a page, or contain the words "if… then" more than a few times, the conversation has real structure and you'll get better results drawing it. See instructions or a pathway.

Writing agent instructions that work

On this page