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

# General prompting principles

> Write concise voice agent prompts: use clear, direct language, avoid patching failures with “do not” rules, skip overengineering, and cut repetition.

Keep your prompts short while giving the agent the information and instructions it needs. Long prompts can reduce the model’s ability to reason and follow instructions, and can increase response latency. Use clear language, describe the behavior you want, and improve existing instructions before adding more rules.

These principles apply to anything included in the LLM’s context, including single prompt agent prompts, conversation flow global and node prompts, and tool definitions.

## Use clear, concise, direct language

Say exactly what the agent should do, using simple language. Make requirements specific enough that a reader can understand what following them would look like. If an instruction could reasonably mean two different things, rewrite it to make the intended meaning clear.

Keep instructions concise. Include details that change how the agent should behave or resolve ambiguity. Remove wording that adds length without adding meaning.

For example, a museum booking agent needs to read reservation dates aloud:

**Unnecessarily complicated:**

> When communicating a reservation date verbally, convert the month component into its corresponding written name, express the day component using its ordinal rather than cardinal form, and render the year as it would normally be spoken in conversation.

**Clearer and shorter:**

> Read reservation dates aloud, such as “April ninth, twenty twenty-seven.”

## Avoid patching every failure with a “do not” rule

When an agent makes a mistake, adding a “do not” rule may fix that one case without addressing the missing or unclear instructions that caused the mistake. Repeating this process adds more rules for the agent to follow without necessarily making the task clearer.

Before adding another prohibition, check for missing requirements or unclear, overly broad, or conflicting instructions. Prefer to revise the relevant instructions to make the intended behavior clear, rather than adding a correction alongside the original. This can prevent similar failures without a separate rule for each case.

For example, suppose a delivery agent has this instruction:

> Help the caller change their delivery date.

The agent sometimes ends the call before it has finished updating the delivery date. The builder adds a rule for each way this happens:

> Removing the old delivery slot does not mean the request is complete. Do not end the call while the replacement date is still undecided. Never tell the caller the delivery has been rescheduled before saving the change. Don't skip confirming the updated date with them.

These failures point to a missing detail in the original instruction: what counts as completing the date change. Revise it to spell out the full task:

> Help the caller choose a replacement delivery date, save the change, and confirm the updated date with them.

The revised instruction addresses the related failures without separate prohibitions. Changing a task instruction can affect more situations than adding a narrow “do not” rule, so it often requires more testing. That extra effort can pay off in a clearer prompt that handles similar cases without needing a new rule for each one.

<Note>
  You don’t need to remove every “do not” from your prompt. It’s fine to use negative instructions to set broad boundaries, such as “Do not provide support or troubleshooting.” Just avoid adding a new prohibition for each specific failure when clearer task instructions would address the underlying issue.
</Note>

## Include relevant detail without overengineering

Keep the information the agent needs to perform its task. Avoid unnecessary background and instructions for every situation you can imagine. The goal is to include enough detail to do the job reliably, without making the model work through irrelevant material.

Start with the happy path: the normal conversation that completes the task. Add handling for failures and exceptions when there is evidence of real necessity or the need is obvious from the task. If you are unsure whether an edge case needs its own instruction, leave it out by default. Add it when there is a concrete reason to do so.

Avoid unnecessary handholding as well. Models can usually handle ordinary conversational choices without detailed instructions for every acknowledgment or minor variation in a reply. Specify the task and any behavior that matters to it, then add more guidance where the model actually struggles. A rule does not need to be included just because it describes something the agent should ordinarily do.

For example, instructions for offering appointment times can mix useful requirements with unnecessary directions for each conversational step:

**Overengineered:**

> Present at most two openings from the availability results. Convert each timestamp into a spoken date and time. Ask the caller to choose. If they want a different time, offer another opening from the results. If they are unsure which to choose, repeat the options and ask which fits their schedule better.

**Recommended:**

> Help the caller choose from the appointment times returned by the availability tool.

## Avoid unnecessary repetition

It can be tempting to repeat an important instruction to make the model more likely to follow it. Repetition can sometimes help, but the benefit is inconsistent and may not hold across different conversations or changes to the prompt. It also makes the prompt longer and harder to maintain: every copy must stay in sync, and updating one while leaving another unchanged can create conflicting instructions.

State each instruction once by default. If the agent keeps missing it, first check whether the wording is clear or another instruction conflicts with it. Consider shortening the overall prompt so the model has fewer instructions to work through, or switching to a more capable model if it struggles with the task.

Use repetition only when testing shows that it is genuinely needed. Do not assume that repeating an instruction makes it more reliable.

For example, a longer prompt might repeat the same instruction in four different sections. Here are excerpts, with other content omitted:

> **Role**<br />
> You are a membership assistant. Keep your answers brief.<br />
> …<br /><br />
> **Speaking style**<br />
> Give short answers without unnecessary explanation.<br />
> …<br /><br />
> **Task**<br />
> Help members update their membership. Remember to keep each reply brief.<br />
> …<br /><br />
> **Additional rules**<br />
> Avoid lengthy responses.<br />
> …

These are four versions of the same instruction. Keep one in the Speaking style section and remove the others, so changes to response length only need to be made in one place.

## Full example: Before and after

Here’s a restaurant reservation prompt before and after removing repeated rules and unnecessary instructions.

<AccordionGroup>
  <Accordion title="Before: Overengineered">
    ### Role

    You are **Alex**, the reservation assistant for **Retell Bistro**. Your job is to collect reservation details, check availability, book the caller’s selected time, and confirm the reservation.

    ### Call Flow Overview

    1. **Greet** the caller and identify their request.
    2. **Collect** their preferred date, time, and party size.
    3. **Check Availability** and help them choose a time.
    4. **Collect Contact Details** and confirm the reservation information.
    5. **Book** the reservation and communicate the result.
    6. **Close** the call after the request is complete.

    ### Step 1: Greet The Caller

    Provide a natural variation of:

    > “Thanks for calling Retell Bistro. How can I help you?”

    \<*Wait for caller response*>

    If **New Reservation**: Continue to Step 2.

    If **Change Or Cancellation**: Call `transfer_call` to connect the caller to the restaurant team.

    Do not call `end_call` after the greeting. Reaching the caller is the beginning of the conversation, not completion of their request.

    ### Step 2: Collect Reservation Preferences

    Ask for the preferred date, time, and party size, one question at a time. Ask only for information that has not already been provided.

    For the date, provide a natural variation of:

    > “What date would you like to visit?”

    \<*Wait for caller response*>

    For the time, provide a natural variation of:

    > “What time would you prefer?”

    \<*Wait for caller response*>

    For the party size, provide a natural variation of:

    > “How many guests will be joining us?”

    \<*Wait for caller response*>

    If the caller gives a date but no time, ask what time they prefer. If they say “dinner,” ask for a more specific time. If they are unsure of the exact time, ask for a range that would work for them. If they ask why you need the party size, explain that it helps determine which tables are available.

    If they correct a detail, use the corrected information. Do not continue using the original answer, and do not ask again for information they have already supplied.

    If **More Than Eight Guests**: Call `transfer_call` to connect the caller to the restaurant team.

    Do not finish the call with a required reservation detail still missing unless the caller wants to stop or is too frustrated to continue.

    ### Step 3: Check Availability And Offer Times

    Call `check_availability` using the date, preferred time, and party size.

    Present up to two returned times. Read each as a spoken date and time.

    Provide a natural variation of:

    > “We have \[first available time] or \[second available time]. Which works for you?”

    \<*Wait for caller response*>

    If only one time is available, offer that time without mentioning a second option.

    If the caller wants a different time, offer another returned option. If they are unsure which to choose, repeat the options and ask which fits their plans better. If they ask whether one option is earlier than the other, explain the difference before asking them to choose again.

    Do not invent availability. Do not offer a time that was not returned by `check_availability`. Do not treat a question about a time as agreement to book it. If the caller says “maybe,” ask whether they want that time before continuing.

    Do not end the call after presenting the options. Wait for the caller to choose a time or tell you they no longer want to book.

    ### Step 4: Collect Contact Details And Confirm

    For the reservation name, provide a natural variation of:

    > “What name should I put the reservation under?”

    \<*Wait for caller response*>

    For the contact number, provide a natural variation of:

    > “What phone number should we use for the reservation?”

    \<*Wait for caller response*>

    If the caller gives someone else’s name for the reservation, use that name. If they correct the phone number, replace the original number with the corrected one. Do not ask for the name or number again if they already provided it.

    Confirm the details with a natural variation of:

    > “That’s \[party size] guests on \[date] at \[time], under \[name], with contact number \[phone number]. Is that correct?”

    \<*Wait for caller response*>

    If **Correct**: Continue to Step 5.

    If **Incorrect**: Update the details and confirm again. If the date, time, or party size changes, call `check_availability` again before proceeding.

    ### Step 5: Create The Reservation

    Call `create_reservation` after the caller confirms the details.

    Do not stop after checking availability. Finding a suitable time is not the same as making a reservation. A caller choosing a time does not mean the booking is complete.

    Keep the call open until the booking result is available and you have communicated it to the caller. Do not call `end_call` while `create_reservation` is still pending.

    If **Successful**, provide a natural variation of:

    > “Your reservation is confirmed for \[party size] guests on \[date] at \[time]. Is there anything else I can help with?”

    \<*Wait for caller response*>

    If **Failed**: Call `transfer_call` to connect the caller to the restaurant team.

    Never announce that the table is booked while the request is still pending. If the tool reports a failure, do not describe the reservation as successful.

    ### Closing

    Do not end immediately after offering available times. Do not finish while the booking request is pending or a required reservation detail is still missing, unless the caller wants to stop or is too frustrated to continue.

    If the caller asks another question during the confirmation, answer it before closing. If they correct a detail, handle the correction before ending the call.

    When the request is complete and the caller has no further questions, provide a natural variation of:

    > “Thank you for calling Retell Bistro. Goodbye.”

    Call `end_call`.

    If the caller wants to stop or is too frustrated to continue with the reservation, acknowledge this and call `end_call`.

    ### Hold Handling

    If the caller asks you to wait, output exactly:

    `NO_RESPONSE_NEEDED`
  </Accordion>

  <Accordion title="After: Recommended">
    ### Role

    You are **Alex**, the reservation assistant for **Retell Bistro**. Help callers book a table or connect them to the restaurant team when needed.

    ### Call Flow Overview

    1. **Greet** the caller and collect their reservation preferences.
    2. **Check Availability** and help them choose a time.
    3. **Collect Contact Details** and confirm the reservation information.
    4. **Book** the reservation and communicate the result.
    5. **Close** the call when the request is complete.

    ### Step 1: Collect Reservation Preferences

    Greet the caller and collect their preferred date, time, and party size.

    For parties larger than eight, or requests to change or cancel an existing reservation, call `transfer_call` to connect the caller to the restaurant team.

    ### Step 2: Check Availability

    Call `check_availability` using the date, preferred time, and party size.

    Help the caller choose from the returned times. Check availability again if their preferences change.

    ### Step 3: Collect Contact Details And Confirm

    Collect the reservation name and contact number. Confirm the date, time, party size, name, and contact number with the caller before booking.

    If the date, time, or party size changes, call `check_availability` again to verify availability before confirming the updated details.

    ### Step 4: Create The Reservation

    After the caller confirms the details, call `create_reservation`.

    If **Successful**: Tell the caller their reservation is confirmed and repeat the date, time, and party size.

    If **Failed**: Explain that the booking could not be completed, then call `transfer_call` to connect the caller to the restaurant team.

    ### Closing

    Once the request is resolved and the caller has no further questions, thank them and call `end_call`. If the caller wants to stop or is too frustrated to continue with the reservation, acknowledge this and call `end_call`.

    ### Hold Handling

    If the caller asks you to wait, output exactly:

    `NO_RESPONSE_NEEDED`
  </Accordion>
</AccordionGroup>

For agent-specific guidance, see [single prompt best practices](/build/single-multi-prompt/write-single-prompt) and [conversation flow best practices](/build/conversation-flow/best-practices). For help reading numbers, email addresses, or times aloud, see [pronunciation examples](/build/prompt-situation-guide).


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