---
title: "Prompt style guide"
description: "How to write and edit a ThunderPhone voice agent's prompt: the guidelines prompt review checks, with the ids its findings cite."
---

{/*
  GENERATED FILE: do not edit by hand.
  Source: api/agents/prompt_style_guide.md
  Regenerate: python3 scripts/docs-freshness/generate_prompt_style_guide.py
  CI regenerates this page and fails on drift
  (scripts/docs-freshness/generators.d/50-prompt-style-guide.sh).
*/}

<Note>
  This is the guide [prompt review](/api-reference/agents#review-a-prompt) checks a prompt against, and
  its findings cite the ids below. Coding agents connected to the
  [MCP server](/guides/thunderphone-mcp-server) read the same text as the resource
  `thunderphone://guides/prompt-style`. For templates and examples, see the
  [prompting guide](/guides/prompting).
</Note>

This guide is for anyone who writes or edits a voice agent's prompt: a person in the builder, Copilot, or a coding
agent working through the API. The prompt review tool uses it as its rubric and cites its guideline ids (P1, W2,
and so on).

A caller hears the agent once, at speaking pace, and cannot scroll back. The agent reads the prompt on every
turn and copies its wording closely. Both facts shape everything below.

## Shape

**P1. Write it the way a person would brief a new receptionist.** A short opening says who the agent is and who
it works for. The call then follows in the order it happens: how it opens, what to find out, what to confirm,
how it ends. Each rule sits in the part of the call where it applies. A reader should be able to ask of every
paragraph, "could a person running this business have typed this?"

**P2. Plain headings, prose underneath.** Headings such as "Who you are", "The call", "Facts" and "Handing off"
help. Machine-style structure does not: numbered rule manuals, camelCase or code-like headings, long dash-bullet
lists of rules, a tools reference up front, and cross-references like "see section 4 below". Lists are fine for
data the agent looks things up in (hours, prices, an address).

**P3. Manner of speaking once, briefly.** How the agent talks across the whole call (short turns, warm, plain
words) fits in one short paragraph near the top. Everything specific to one step lives in that step.

**P4. Facts apart from behavior.** Hours, prices, locations, policies and other facts go in a facts part of the
prompt or in a knowledge base, not scattered through the call flow. Long catalogs and FAQs belong in a knowledge
base. The agent may say only facts it was given.

## Content

**C1. Principles and facts, not scripts.** Describe what the agent is trying to achieve and what it needs to
know. Leave out "if the caller says X, say Y" branches, scripted answers to anticipated questions and canned
lines. The configured opening greeting is the one scripted element.

**C2. A fix states the general principle.** When a prompt change responds to an observed failure, the change adds
a general principle or a missing fact, not a patch for that one case. The failing call's specifics (its names,
its numbers, its exact words) stay out of the prompt.

**C3. Prefer taking away to adding.** When a failure traces to an existing rule that is too specific, too broad
or badly placed, change or remove that rule rather than adding a counter-rule next to it.

**C4. Settings decide some things, not the prompt.** These are agent settings, and prompt text about them is
ignored or conflicts with them: what is said while a tool runs (tool start line, filler phrases), silence
check-ins and the final action after silence, how a read-back is paced, the language-switching style, the
recording notice, and whether the agent or the caller speaks first. Point the prompt at the outcome instead
("confirm the email address before you save it"), and set the setting. The opening greeting itself is written in
the prompt.

**C5. Examples are lines the agent will say.** The agent copies example wording almost word for word, so every
example is a full, natural spoken sentence, and a few varied examples beat one. Introduce them as examples ("For
example, you might say ..."), not as the required line. Clipped tags like "Still accurate?" sound terse once
spoken.

**C6. No examples from our own customers' calls.** Examples describe the kind of situation in general terms or
use an invented business.

## Wording

**W1. Say what to do, plainly, once.** State the wanted behavior as an instruction in ordinary words: "Read the
order number back digit by digit and ask the caller to confirm it." Say it once, where it applies.

**W2. No emphasis.** No IMPORTANT, NOTE or CRITICAL labels, no words in capitals for force, no exclamation
marks, no "Bad:" and "Good:" pairs, no blocks of what not to do. Words like "never", "always" and "must" used
for force belong here too. Emphasis pulls the model's attention to one rule and makes it worse at the rest of the
call. When the agent ignores an instruction, make the instruction clearer, more specific or better placed, not
louder.

**W3. Fix the structure that causes a behavior.** Before adding a rule against something the agent does, find
the wording or structure that leads it there: a template the model fills in literally, a term that means two
things, an if-else branch that a fast model reads loosely. Change that.

**W4. Specific beats general.** "Offer the two earliest open times, then ask which works" beats "help with
scheduling". Vague instructions give vague behavior.

## Speech

**S1. One question per turn, and the question ends the turn.** Anything said after a question talks over the
caller's answer. Put any explanation before the question.

**S2. Short turns.** One or two short sentences unless the caller asks for detail. Spoken options are limited to
a few.

**S3. Write for the ear.** In what the agent says, avoid markdown, symbols and notation the voice will read oddly
(slashes, ampersands, "@", ".com", thousands separators, unspaced phone numbers). Facts and values the agent passes
to a tool, such as an email address or an account number, stay in their exact written form; when one also has to be
said aloud, add how it is said next to it rather than rewriting it. Spell out how unusual names or acronyms are
said, and listen to new terms in the agent's voice before keeping them.

**S4. Confirm what would be costly to get wrong.** Names, numbers, emails, addresses and codes are confirmed back
in the form they were given. The prompt says what to confirm; the platform paces the read-back.

## Iterating

**I1. Test before you keep a change.** Replay the agent's dev set on the edited draft and compare it with the
current version: which examples a change fixed, which it broke. Read the replies the way a caller would hear them.
Anything a caller would notice is a problem, not a detail.

**I2. The hold-out set is checked once.** Tune on the dev set only. Run the test set when a change is ready, and
report its result as it is. A change made after seeing test results needs fresh test examples.

**I3. Refactor when patches pile up.** A prompt that has collected many small fixes drifts from P1: rules
repeat, conflict, or sit far from the step they govern. Then rewrite it into this shape, keeping every behavior
it asks for. List each behavior as kept, merged, reworded or dropped, and drop nothing silently. Replay the dev
set before and after; a refactor should change wording, not behavior.

**I4. Check the configuration before the prompt.** Some failures are not the prompt's: mishearing spelled
letters is an audio-understanding limit (try a higher audio tier or Storm), a slow reply may be the tier or the
endpointing setting. Rule out configuration before rewriting text.