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

# Writing a good prompt

> Practical guidelines for writing a Hebrew voice agent that sounds natural on the phone and behaves the way you expect.

## Know where each instruction goes

* **[Single prompt agent](/guides/single-prompt-agents):** everything lives in the agent prompt. It applies for the whole call.
* **Flow agent, [global prompt](/guides/flow-agents):** added to the start of **every** node's prompt. Put the persona, identity, language style, tone and rules that apply everywhere here.
* **Flow agent, node prompt:** only the task for this step, for example "Ask whether the caller wants to book or cancel." Don't repeat the persona in every node, because the global prompt already supplies it.

<Tip>
  If a rule must hold in every step (never promise refunds, always use formal address), put it in the global prompt, not in one node.
</Tip>

## Define the persona and tone

Say who the agent is, which business it represents and how it should sound. For example: "You are Noa, the phone representative of a parking company. Speak warmly and to the point." Say whether it uses formal or casual Hebrew and how it handles callers it can't help.

## Write for the ear, not the eye

* Ask for **short spoken sentences**, one idea at a time. Long paragraphs that read well on a page sound robotic on a call.
* Ask **one question per turn**. A caller can't scroll back to see what you asked.
* Forbid lists, bullet points, emojis and headings in replies. None of them work in speech.
* For numbers, codes and IDs, use the speech modifiers in your text: `[order_id:digits]` reads digit by digit, and `[amount:spoken]` reads as Hebrew words. See [Variables](/guides/variables).

## Write fixed text without gender

Hebrew addresses a man and a woman differently. Replies the agent writes itself adapt automatically: they avoid gendered forms until the caller's gender is detected, then address the caller correctly.

Fixed text is different. The **Welcome Message**, [Announcement](/guides/flow-nodes#announcement) nodes and [SMS](/guides/sms) text are said or sent word for word, and the welcome message plays before the caller has spoken, so the agent can't know their gender yet. Phrase these without gendered forms.

| Instead of | Write |
| - | - |
| <span dir="rtl">שלום, איך אוכל לעזור לך?</span> | <span dir="rtl">שלום, במה אפשר לעזור?</span> |
| <span dir="rtl">תודה שפנית אלינו</span> | <span dir="rtl">תודה על הפנייה</span> |
| <span dir="rtl">אתה מוזמן לחזור אלינו</span> | <span dir="rtl">אפשר לחזור אלינו בכל עת</span> |

## Be explicit about goals and limits

* State the goal of the call and what counts as "done".
* List what the agent should **not** do, such as quoting prices that aren't in its information or giving legal advice.
* Tell it what to say when it doesn't know. An honest "I don't have that information" beats a guess.

## Don't hide rules in the knowledge base

A [knowledge base](/guides/knowledge-base#markdown-file) holds facts: hours, branches, prices, policies. Every instruction goes in the prompt, such as when to transfer, what never to say and how to confirm details.

## In flow agents, let the structure do the work

* Write transition conditions as plain descriptions of what the caller did, like "The caller asked to speak with a person."
* Use a **Collection** node to gather details rather than asking in a Conversation prompt. It validates answers and stores them.
* Use an **Announcement** node for text that must be said word for word, such as a legal notice.

## Test and iterate

Make test calls in the simulator and read the transcript. When the agent misbehaves, fix the one instruction that caused it rather than piling on new rules. Deploy when the draft behaves well.


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