ThunderPhone v3 is live.Self-serve, from 2¢/min.Read the announcement

Using the dashboard

Prompt style guide

How to write and edit a ThunderPhone voice agent

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?" What to find out covers what the business needs to act on the request, not only who is calling and how to reach them.

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 first-person turns, warm, plain words; see S2) 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.

C7. The prompt is for callers, not about the build. Callers hear whatever the prompt says once it is live, so it leaves out notes about building, testing or compliance status ("this version is for testing", "TEST" in a booking's name, "until the agreements are signed"). It also leaves out disclaimers, liability caveats and closing recaps the business didn't ask for, such as what accepting a plan doesn't establish or a summary of what is still unconfirmed. The agent answers what the caller asked and stops; the business adds a caveat when it wants one. A missing fact or a system limit is written as what the agent does ("for prices, offer a callback from the office"), not as a note that it wasn't supplied or about how requests are recorded, and nothing is left over from drafting, such as a stray name or heading.

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 so the caller can correct 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.

W5. Look it up before asking about it. When the caller names something a read-only lookup tool can check (a product, an order, an existing booking), the agent checks with the words the caller gave, then asks a follow-up only if the result needs one. "Check stock for the product the caller names and tell them what you find" beats "clarify the brand, size and variant, then check stock": an agent told to clarify first keeps asking and the check never runs. This covers lookups only. Before a tool that books, changes, cancels or saves something, the agent still confirms the details with the caller.

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, in full spoken sentences. One or two short sentences unless the caller asks for detail. Spoken options are limited to a few. Short means few words, not clipped ones: the agent talks the way a good receptionist does on the phone, in complete sentences in the first person, such as "I'll book that for you now" or "I've got you down for Monday at ten." Note-style fragments ("Booking that for you.", "Done.", "Noted.") sound curt once spoken, and email phrasing ("Please note that ...", "Kindly ...", "I hope this helps") sounds read out rather than said. The prompt's manner-of-speaking paragraph asks for this plainly, for example: "Keep each turn to a sentence or two, and talk in the first person, the way a receptionist would on the phone."

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. Numbers, emails, addresses and codes are read back in the form they were given, once, in the reply right after the caller gives them and before the next question, one value per read-back. By default a name is taken as said, with no read-back, and the agent asks for its spelling only when it is unusual or unclear, and asks once. When the business needs the name exact, such as to match its records or for a booking under that name, the prompt says so and the agent spells the name back. A read-back is the caller's chance to correct a value, not a gate: a caller who answers with the next detail or carries on without correcting it has accepted it, and an accepted value is not asked about again. A phone number the business will call or text back is the exception: its read-back ends the turn and waits for the caller's answer. A prompt that asks for digit-by-digit reading names only the values read that way (a phone number, a code); a house number, a price, a time or a date is said the way people say it. 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 a hearing limit (try Plus hearing), a slow reply may be the intelligence or hearing tier or the endpointing setting. Rule out configuration before rewriting text.