> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talking-avatar.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Write a good prompt

> How to write the prompt and first message for a spoken conversation.

The prompt tells the agent who it is, how it speaks and what it knows. It's the most important setting: a clear prompt makes a natural, reliable agent.

## Keep the sections

The [templates](https://docs.talking-avatar.dev/voice-agents/templates.md) use four sections. Keep them, and write rules as short bullet points.

```markdown theme={null}
# Role & Objective
Who the agent is, who it's talking to, and what a good call achieves.

# Personality & Tone
How it sounds: warm, concise, formal, upbeat…

# Rules
What it must and mustn't do, one bullet per rule.

# Context
The facts it needs: your products, hours, policies, questions to ask.
```

Add other sections when they help, such as **Conversation flow** for a fixed sequence of steps, or **Questions** for an interview.

## Write for speech, not text

The agent's words are spoken aloud, so:

* **Keep replies short.** One or two sentences, then let the caller talk.
* **Ask one question at a time.**
* **Never read out** lists, markdown, symbols or URLs. Spell out what should be said instead.
* **Confirm details** by repeating back names, dates, times and phone numbers.
* **Handle unclear audio:** tell it to ask the caller to repeat.

## Ground it in facts

* Put everything the agent should know in **Context**.
* Tell it to answer **only** from the context, and to say so when it doesn't know.
* Tell it never to invent prices, policies, order details or discounts.
* Say what to do when it can't help: offer to connect the caller with your team, or take a message.

## Languages

The agent understands callers in their own language. Add *Reply in the language they speak* (it's in every template) to have it answer in that language, and pick a **Multilingual** voice. **English** voices speak English only. See [Avatar and voice](https://docs.talking-avatar.dev/voice-agents/avatar-and-voice.md#voices).

## Tools and ending the call

* If the agent has [tools](https://docs.talking-avatar.dev/voice-agents/tools.md), say in the prompt when to use them, for example *Look up the order with get\_order\_status before answering delivery questions*.
* With **End call** on, the agent hangs up once it has said goodbye, or when the caller asks. Add a goodbye step to your flow, such as *Thank them and say goodbye*.

## The first message

The **First message** is what the agent says as soon as the avatar appears. Make it short, and end with a question or an invitation to talk:

> Hi, I'm Maya. What can I help you with today?

Leave it empty if the caller should speak first.

## Placeholders

Text in `[square brackets]` is a placeholder. The editor counts the ones left above the prompt. Replace them all before sharing your agent, or it may say them out loud.

## Test and iterate

Make a [test call](https://docs.talking-avatar.dev/voice-agents/create-an-agent.md#create-the-agent) after each change, then read the transcript on the **Calls** tab to see exactly what was said. If replies feel slow or rushed, adjust [turn-taking](https://docs.talking-avatar.dev/voice-agents/conversation-settings.md#turn-taking). If answers are too shallow, raise [reasoning](https://docs.talking-avatar.dev/voice-agents/conversation-settings.md#reasoning).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.