Intelligence

Voice craft

What a caller can take in by ear, how to collect details over a noisy line, and how to recover.

What a caller can take in by ear, how to collect details over a noisy line, and how to recover when something goes wrong. Write these into the system prompt and its examples. A text agent follows the same rules for turn length and recovery.

Short turns

  1. One or two short sentences a turn. A caller forgets the first half of a long one.
  2. One question a turn. Ask for a name, a date and a reason at once and you get one answer and two guesses.
  3. Two options, then a choice. A spoken list of more than three items gets forgotten. Offer the top two and ask which way to go.
  4. Hand the turn back. When the caller needs to act, end on a question, a choice or a request to confirm.
  5. Plain punctuation. Commas, full stops and question marks pace the voice. No ellipses, dashes or markup in the agent's lines.
  6. Say when it doesn't know. "I don't have that in front of me" plus the nearest next step. A price, a time or a policy comes from a tool, a variable or the prompt, never a guess.

Spoken form

The agent's words are spoken exactly as written, so every agent line in an example is written the way it should be said. Australian English:

WrittenSpoken
$42.50"forty-two dollars fifty"
$1,200"twelve hundred dollars"
03/04/2026"the third of April" (the year only when it matters)
2:15 PM"quarter past two in the afternoon" or "two fifteen"
0412 345 678"oh four one two, three four five, six seven eight"
08 6289 3451"oh eight, six two eight nine, three four five one"
Unit 4/12"unit four, number twelve"
5%"five percent"
ABN"A B N"

Put names the voice says wrong into pronunciations (set_pronunciations), and names callers say that the agent mishears into keyterms (set_keyterms). A hint in the prompt is a weak second.

Collecting details

  1. Don't ask for what you already have. On a phone call the agent already has the caller's number. Confirm it: "Is the number you're calling from the best one to reach you on?"
  2. Spell back proper nouns. Names, streets and suburbs are what speech recognition gets wrong. When a word arrives garbled or unfamiliar, ask the caller to spell it, put the letters together, and read it back once. When it arrives clearly, read it back once before relying on it.
  3. Try other spellings before asking again. On a failed lookup try Kerry or Carrie, Sara or Sarah, Mc or Mac.
  4. Read back a number, code or email one character at a time, once, and wait for a yes. Don't read back a value the caller has already confirmed.
  5. Confirm a booking's details once, together. Collect them one at a time, then read the set back once: "So that's a pickup for Jane Smith from twelve Wattle Road at quarter past six. Is that right?"
  6. Correct only the wrong field. On a correction, update that one detail and carry on, without reading the whole set again.
  7. Don't read back soft details. A reason for calling or a preference gets acknowledged naturally. Reading it back turns the call into a form.
  8. Take what's volunteered. When the caller gives a detail before it's asked for, use it and don't ask for it again.

When something goes wrong

SituationWhat the agent does
It didn't catch the caller"Sorry, I didn't catch that. Could you say it again?" After a second miss, offer another way: spelling it, a transfer or a message
A lookup finds nothingSays it couldn't find it and offers a sensible next step
A tool failsSays there's a problem checking right now, and offers what the business has instead, such as taking a message or a transfer. The tool's error tells the agent what happened, so the prompt needs no retry rules
The request is outside what it handlesSays so plainly, then offers the nearest alternative
The caller is frustratedAcknowledges it once, then gives a clear next step
A lookup is slowSays a short lead-in before the tool runs, such as "Let me check that for you." Read-only lookups marked background-safe keep the conversation going, and the Background sound settings can play a working sound while a tool runs

Tone

  1. Match the caller's energy. A crisp caller gets fewer words and faster turns. A chatty caller gets one more beat of warmth. A confused caller gets shorter sentences and more confirming.
  2. Banter gets one beat. A joke, or "are you a robot?", gets one light sentence, then back to the task. A hard off-topic request (a recipe, the news, homework) gets one friendly redirect. If it keeps coming, offer to wrap up.
  3. Personal news gets a few words. When a caller mentions something personal, acknowledge it briefly before carrying on.
  4. Go easy on emotion. No laughter, exclamation marks or stretched words without a real reason, and never on two turns in a row.
  5. Keep the register plain. The starter prompt keeps an Australian register with no slang, and uses light words such as "yeah" or "okay" sparingly. More of them make every turn longer, so test any change.

Ending the call

  1. End when it's done. The task is finished and the caller has said goodbye, or confirmed there's nothing else.
  2. Give a trailing "okay, thanks" a moment. It's often the lead-in to another question.
  3. Don't end on an interruption. When the caller talks over the agent, it stops, listens and answers.
  4. Leave silence to the platform. When the caller goes quiet, the agent checks in on its own, and the call handling settings can end the call after a set time of silence. The prompt needs no silence rules.
  5. Clarify a fragment. "Ok" or "hmm" on its own gets one short question, never a goodbye.

Agents that handle several kinds of call

  1. A multi-step job can be numbered steps in the prompt. Put each check inside the step where it applies, not in a separate rule further down. Moving one check into step one is what made an agent follow it.
  2. Say how to tell the call types apart in the caller's words, and what to do when the first sentence doesn't decide it: ask one clarifying question.
  3. Order that must hold is a tool prerequisite (set_tool_requires), never a step number alone.

Mistakes to avoid

MistakeWhy it failsInstead
A chat prompt reused for the phoneLong, list-shaped repliesThe short-turn rules above, and examples in spoken form
No examplesThe model invents its own length and toneThree to five varied examples
Several questions in one turnThe caller answers oneOne question a turn
A monologueThe caller forgets the first halfTwo options, then a choice
A vague tool descriptionWrong tool, bad argumentsFix the description before the prompt
A hand-written guardrail blockRepeats the safety rules the platform already addsOnly the limits specific to this business
A long list of banned phrasesPuts those exact words in front of the model every turnOne short positive principle
A tool named in the promptThe name gets spokenDescribe what the tool does
Instructions inside tool resultsRead as prompt injectionFacts in results, behaviour in descriptions
The prompt as a security checkA caller can argue around a promptCheck identity with a tool and a prerequisite, so the check runs in code

On this page