> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Prompt writing
> Structure, tighten, and iterate on the instructions your assistant follows on every call
Whether your assistant runs on a single system prompt or a [flow](/flow-builder/overview) built from agent nodes, the same craft applies: the model only knows what you tell it. A clear, well-structured prompt is one of the biggest levers you have over call quality — often more than which model or voice you pick.
This page is about *writing* good instructions. For where the system prompt lives, and when to reach for a flow instead of a single prompt, see [System prompt vs. flow builder](/assistants/overview).
## Structure your prompt in named sections
Don't write one long paragraph. Break the prompt into labeled sections, each with a single job. It's easier to write, easier to update later without breaking something else, and easier for the model to follow:
```text theme={null}
## Identity
Who the assistant is, which company it represents, what it specializes in.
## Style
Tone, formality, sentence length, how it handles humor or empathy.
## Knowledge
The facts it needs on hand — products, prices, policies, hours.
## Guidelines
Rules it must always follow (verify identity before sharing account
details, never promise a delivery date, one question at a time).
## Response patterns
Step-by-step handling for specific situations — pricing questions,
objections, what to say while a tool call is running.
## Limits
What it must never do, and what to say instead.
```
Sections can be reused across assistants and edited independently without touching the rest of the prompt.
## Be specific, not vague
"Be helpful and professional" gives the model nothing to act on. Pair every rule with a concrete example:
| Vague | Specific |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| "Help customers with billing questions." | "When a caller mentions a billing question, ask for their invoice number (format INV-XXXXX), then look up their account." |
| "Be friendly." | "Acknowledge what the caller said before answering — don't jump straight to the next question." |
| "Handle objections." | "If the caller says they're not interested, ask what would need to change for it to make sense — don't repeat the pitch." |
Avoid the opposite failure, too. Scripting every possible sentence removes the natural flow that makes a voice assistant pleasant to talk to — give rules and examples, not a transcript to recite.
## Handling what you didn't anticipate
Every prompt eventually meets a question it doesn't cover. Decide in advance how the assistant should react — pick one pattern (or combine them):
* **Default, then transfer.** "If you don't know the answer, say so plainly and offer to connect the caller with someone who does," then rely on [call transfer](/assistants/built-in-tools#transfers).
* **Ask a clarifying question.** "If the request is unclear, ask one short follow-up before deciding how to route it."
* **Check the knowledge base first.** If you've connected one, instruct the assistant to search it before falling back to a transfer — see [Knowledge bases](/assistants/knowledge-base).
## Writing clear conditions for tools and transfers
Every [built-in tool](/assistants/built-in-tools) and every [flow](/flow-builder/nodes) edge is only as reliable as the condition text describing when it should fire. Vague conditions produce vague behavior.
Two valid levels of detail for an end-call condition, depending on how much control you want:
* **Simple:** "End the call once all questions are answered and the caller no longer needs help."
* **Detailed:** "Also end the call after a successful booking, an explicit goodbye, or when the conversation is clearly finished — but never while the caller is still speaking."
The same precision applies to a transfer condition: describe exactly what the caller says or needs, not just "when appropriate."
Then say the same thing again in the prompt itself. A short section naming each tool and the moment it applies gives the assistant one ordered reference — worth the few extra lines whenever more than one tool could plausibly fire:
```text theme={null}
## Tools
- check_availability — before offering any appointment time.
- book_appointment — only once the caller confirms a slot, with their
name and email.
- Transfer to Sales — when the caller asks for a quote or pricing.
```
[Milian](/assistants/milian-copilot) can help draft and tighten this kind of condition text from a plain description of your process — describe what should happen, and ask for a short, checklist-style instruction you can paste straight into the field.
## How long should it be?
* **Short (roughly 50–200 words)** — simple, single-purpose assistants.
* **Medium (roughly 200–500 words)** — several scenarios, each with a clear rule.
* **Long (500+ words)** — slows the model down and raises the odds it loses track of an earlier instruction.
If you find yourself pasting in a product catalog, a long FAQ, or detailed policies, move it to a [knowledge base](/assistants/knowledge-base) instead. Knowledge bases are searchable, don't add to every call's prompt length, and can be updated without touching the assistant.
## Common mistakes
| Mistake | Fix |
| -------------------------------- | ---------------------------------------------------------------------------- |
| Too vague ("be helpful") | Add concrete rules and example phrasing |
| Too rigid — every line scripted | Give guidelines and examples, not a transcript |
| Information overload | Move reference material to a knowledge base |
| Contradictory instructions | Re-read the prompt in order — a later rule should never fight an earlier one |
| No rule for unexpected questions | Add one of the fallback patterns above |
| Vague tool or transfer triggers | Name the exact situation, not "when appropriate" |
## Rolling out and iterating
No prompt is finished at launch — treat it as a living document.
Write clear instructions for your most frequent scenarios before chasing every edge case. A prompt that handles the majority of real calls well beats one that half-handles everything.
Use the editor's **Test** button for a quick voice or chat check, or set up [Simulations](/assistants/simulations) to run common scenarios, edge cases, and a difficult caller or two automatically before the prompt meets a real one.
Review new call transcripts closely right after launch — they show exactly where the assistant hesitated, guessed, or handled something the wrong way.
Add the specific example, rule, or fallback that would have fixed each miss. Small, targeted edits beat rewriting the whole prompt.
A few common symptoms and their usual fix:
| Symptom | Likely fix |
| ----------------------------------------- | -------------------------------------------------------------- |
| Generic, one-size-fits-all answers | Add specific examples and named scenarios |
| Required information keeps getting missed | List exactly what to collect, and in what order |
| Transfers happen too early or too late | Tighten the transfer condition's wording |
| States something that isn't true | Add an explicit "say you don't know rather than guessing" rule |
Full coverage of every possible call isn't a realistic target — language is too varied for that. Aim to shrink the gap steadily, and lean on [guardrails and a transfer to a person](/assistants/conversation-quality#guardrails) as the safety net for whatever's left.
See [Prompting for speech](/assistants/prompting-for-speech) for getting phone numbers, dates, and other spoken details to come out right, and [Example prompts](/assistants/example-prompts/overview) for ready-to-adapt starting points.