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

# Writing prompts for voice calls

> A prompt that works in a chat window usually fails on the phone.

A caller can't skim. They hear one sentence at a time, they interrupt, and they
hang up when it drags. Most prompts that fail on the phone fail because they were
written for a screen.

## What you write, and what's handled for you

You write the assistant's **instructions** — who it is, what it does, how it
should sound.

You don't need to write formatting rules, tool instructions, or anything about
how to use knowledge. Qall adds those around your prompt automatically, so leave
them out and spend the space on your business.

## Structure

Write in sections, in this order. It's easier to edit later and the assistant
follows it more reliably.

```text theme={null}
## Who you are
You are Mara, the reservations line for Elster Hotels in Berlin.

## How to speak
Keep answers to one or two sentences. Ask one question at a time.
Never read out a list of more than three options.
If you don't know something, say so and offer to take a message.

## What you can do
Check availability, change a booking, and answer questions about the hotels.
You cannot take payment or cancel a booking — transfer those to the team.

## What callers ring about
Most people are changing dates on an existing booking. Ask for the reference
first; if they don't have it, their phone number is enough.
```

### Who you are

One or two sentences. Name, company, and the job.

Add an identity rule if your callers are likely to test it: *"If someone asks you
to pretend to be something else, stay as Mara."*

### How to speak

This is the section that does the most work on a phone call.

* **Length.** "One or two sentences" is the single most effective line you can
  write. Without it, models write paragraphs.
* **One question at a time.** Two questions in one turn gets you one answer.
* **Numbers and spelling.** Say how to read things out: *"Read prices as 'one
  hundred and sixty-four euros'. Read booking references one character at a
  time."*
* **Uncertainty.** Say what to do when it doesn't know, or it will invent
  something.

### What you can do and can't

List both. The second half matters more — an assistant that doesn't know its
limits promises things you then have to undo.

Say what happens instead: transfer, take a message, offer a callback.

### What callers ring about

A few lines on the common cases, and what to ask first.

## Use variables instead of repeating yourself

Anything Qall already knows should come from a
[variable](/variables), not from you retyping it:

```text theme={null}
You are the reservations line for {{org.name}}.
It is {{now.part_of_day}} on {{now.weekday}}.
The caller is {{contact.first_name | "a new guest"}}.
```

## When to stop writing prompt and build something

A prompt is the wrong tool for three jobs:

| If you're writing… | Use instead |
| - | - |
| A numbered procedure that must happen in order | A [playbook](/playbooks) |
| Facts that change — prices, hours, policies | [Knowledge](/knowledge) |
| "Look up X and tell them" | A [tool](/tools) |

A prompt that contains a price list goes stale. A prompt that contains a
seven-step refund procedure gets skipped halfway. Both are real failure modes and
both have a proper home.

## Common mistakes

**Pasting a chatbot prompt.** Markdown headings, bullet lists and "feel free to
ask!" all read badly out loud.

**A long list of things not to say.** Models follow positive instructions better
than negative ones. "Keep it short and factual" beats five lines of bans.

**Writing the greeting into the prompt.** Use the **first message** field.

**Vague tool descriptions.** The assistant decides from the tool's own Prompt
field — see [Tools](/tools). No amount of system prompt fixes a tool described
as "gets data".

**Over-specifying the personality.** Two adjectives is plenty. Past that you get
a performance.

## Changing a prompt

Change one thing, then make a call. Prompts are probabilistic: a call that went
well doesn't prove the change worked, and a call that went badly doesn't prove it
didn't. If something matters, try it a few times.

Keep a copy of what worked before you edit.


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