Prompting

The system prompt is the central instruction that controls the entire behavior of your AI agent. It defines who the agent is, how it speaks, how it reacts to different situations, and where its boundaries lie. A well-structured prompt is the single most important factor for the quality of your conversations.

Technical Constraints

Character limit: Maximum 100,000 characters — but shorter is better, as every token increases latency
Formatting: Use Markdown (headings with #, bullet points with -). No HTML, no code
Task focus: Prefer fewer, clearly defined tasks per agent rather than packing everything into one prompt

Rule of Thumb for Length

As short as possible, as long as necessary. Every additional token increases latency. If something can be moved to the knowledge base — do it.

The Basic Framework

Every good system prompt follows a clear structure with Markdown headings. The order matters — the language model gives more weight to instructions mentioned earlier.

# General Information
Who is the agent? Name, role, company, tone of voice.

---

# Conversation Flow
## Step 1: Greet
## Step 2: Identify the concern
### If [Scenario A]: ...
### If [Scenario B]: ...
### Other: ...
## Step 3: Collect required data
## Step 4: Farewell

---

# Behavior Rules
What the agent should always do. What it should never do.

---

# Sensitive Topics
Which topics the agent must decline.

---

# Knowledge Base
Reference to the knowledge base.

Why Sections Matter

Sections make behavior reproducible and easy to modify. You can adjust one section specifically without affecting the rest.

Identity and Personality

In the first section, give your agent a clear identity. Use a simple list — no prose.

# General Information

- Your name: Lisa
- Your role: Phone assistant / Appointment manager
- The company: MusterFirma GmbH (Electrical engineering, Leipzig)
- Form of address: Address callers formally
- Speaking style: Professional, friendly, natural – not stiff
- Behavior: Helpful, solution-oriented, efficient
- Call duration: Keep it brief, get to the point

Defining Tone Correctly

Define the speaking style with 2-3 clear adjectives and a contrast:

Do This	Not This
"Friendly, casual, with local charm — but always professional"	"Be nice" (too vague)
"Warm, welcoming, empathetic about problems"	"Behave like a good customer advisor" (not specific)
"Factual, competent, to the point"	"Speak professionally" (no contrast)

The contrast is crucial: "Professional, but not stiff" gives the model two anchor points — what it should be and what it shouldn't.

Dynamic Variables

ScaleTalk provides system variables that are automatically replaced with current values at runtime.

Variable	Description	Example
`{{fromNumber}}`	Phone number of the caller	+491701234567
`{{toNumber}}`	Called phone number	+49309876543
`{{callId}}`	Unique ID of the current call	abc123-def456

Usage example:

The current caller's number is {{fromNumber}}.
The called number is {{toNumber}}.

Date and Time

The agent automatically knows the current date, time, and day of the week — based on the timezone you configured in settings. No variables are needed for this.

Pre-Call Variables

Via Caller Lookup, you can load custom variables that are populated before the conversation starts — e.g., customer data from an API or CSV file. Which variables are available depends on what you configured in Caller Lookup.

Prerequisite

Check out the Caller Lookup guide first to learn how to set up custom variables.

Example: If you load customer data via Caller Lookup, you could use variables like these in the prompt:

# Available Variables

Before the conversation starts, the following variables
are populated if the caller number is recognized:

- {{CompanyName}} – Caller's company
- {{CustomerNumber}} – Customer number
- {{Salutation}} – Mr./Ms.
- {{CustomerLastName}} – Last name

If all variables are empty, the caller is unknown.

Conversation Logic — Decision Trees

At the start of a call, the agent doesn't yet know what it's about. Your prompt must provide clear instructions for every possible direction.

Defining Steps

Divide the conversation into numbered steps:

# Conversation Flow

## Step 1: Greet
After the start message: Listen carefully to the caller.
Respond to what the caller says.

## Step 2: Identify the concern
(If-then rules go here)

## Step 3: Collect required data
(Details below)

## Step 4: Farewell
(Details below)

Important: Listen First

Step 1 is always listening. The agent should NOT immediately ask for data, but first respond to what the caller says.

Writing If-Then Rules

Each scenario gets its own ### header with "If." Inside, use numbered steps or bullet points:

## Step 2: Identify the concern

### If the customer wants to book an appointment:
1. Ask which service is desired.
2. Search for the next available slot via the Calendar Tools.
3. Offer the slot and mention the price.
4. If customer says YES: Ask for name and phone number.
5. If customer says NO: Offer the next available slot.

### If the customer has general questions:
- Answer from the knowledge base.
- Do NOT transfer.

### If the customer wants to speak with a team member:
- "I'd be happy to take down your concern and arrange
  a callback, or I can transfer you directly."
- If transfer desired: Execute call transfer.

### Other:
- "Could you briefly describe what this is about?"

Rules for decision trees:

Maximum 2 levels of nesting — deeper becomes confusing
Always include a catch-all scenario at the end ("Other")
Literal example sentences in quotes for specific phrasings
Branches within a scenario with "If YES / If NO"

Collecting Required Data

Define exactly which data the agent must collect:

## Step 3: Collect required data

Make sure the following data has been collected:
- Caller's name
- Company (for B2B callers)
- Concern (at least 1 sentence)
- Callback number: "What's the best number to reach you?"
- Preferred time window for callback

Important: ALWAYS ask questions one at a time, never as a block.

Why Ask One at a Time?

Asking one question at a time feels like a natural conversation. Question blocks sound like an interrogation and overwhelm callers.

Farewell

Follow the three-step approach: Summarize, offer addition, say goodbye.

## Step 4: Farewell

Briefly summarize what you've noted down.
Ask if the caller wants to add anything.
Then say goodbye:

"Thank you for your call. I've noted everything down –
you'll receive a response shortly.
Have a great day!"

Controlling Tools in the Prompt

ScaleTalk offers built-in tools (Calendar Tools, Call Transfer, API Request) that your agent can invoke during the conversation. Without explicit instructions in the prompt, the model will ignore tools or invoke them at the wrong time.

Important: Always mention the exact tool name in the prompt so the agent triggers the right tool. A detailed guide for configuring individual tools can be found under Capabilities.

Calendar Tools

Mention the Calendar Tools explicitly in the prompt so the agent knows which tool to use for searching and booking appointments.

### If the customer wants to book an appointment:
1. Ask which service is desired.
2. IMPORTANT: Do NOT ask "When would you like to come?"
   Instead, immediately search for the next available slot
   via the Calendar Tools.
3. Offer the slot AND mention the price:
   "The next available slot for a men's haircut
   would be Thursday at 10:30 AM. That would be 35 euros.
   Does that work for you?"
4. If customer says YES:
   - Ask for first name, last name, phone number.
   - Book the appointment via the Calendar Tools.
5. If customer says NO:
   - Search for the next available slot after that.

Pro Tip

Don't ask for a preferred time — offer the next available slot right away. Faster, better, more professional.

Call Transfer

Mention the exact name of the transfer (as you configured it under Capabilities) and the target number in the prompt. This way the agent knows exactly which transfer to use in which situation.

### If urgent emergency:
- Transfer immediately via the "Emergency" transfer
  to +491601234567.
- Say beforehand: "That sounds urgent, I'll connect you right away."

### If the caller wants to speak with a specific team member:
- First offer: "I'd be happy to take down your concern
  and arrange a callback. Or shall I connect you directly?"
- If transfer desired: Transfer via the "Mr. Mueller"
  transfer to +491709876543.

### If the transfer fails:
- Apologize: "Unfortunately, I can't reach [Name] right now."
- Collect required data instead.
- Offer a callback.

Define a Fallback

ALWAYS define what happens if the transfer fails. Without a fallback, the agent gets stuck.

API Request

Via API Requests, your agent can query external systems during the conversation — e.g., order status, customer data, or inventory levels. In the prompt, you control: when the tool is called, what's needed, and how the result is used.

### If an existing customer wants to know their order status:
1. Ask for the order number.
2. Call the API Request "OrderStatus."
3. If the API Request returns a status:
   Say e.g.: "Your order with number [X] is currently
   being processed. Estimated completion is [date]."
4. If the API Request returns no match:
   "Unfortunately, I can't find anything for that number.
   Would you like a team member to look into it?"

Writing for Voice

A phone agent is not a chatbot. Everything is heard, not read. This requires special techniques.

Response Length

The attention span for spoken information is about 8-10 seconds.

Rule of thumb: Maximum 2-3 sentences per conversation turn (about 20-30 words). Better one more follow-up question than one piece of information too many.

Naturalness and Filler Words

People don't speak perfectly. Strategic filler words increase naturalness:

# Behavior Rules

- Occasionally use natural transitions like
  "I see", "Got it", "So" or "Exactly".
- Maximum 1-2 per conversation turn.
- Use them after a caller statement:
  "I see, I'll be happy to look that up for you."

Phonetic Hints

Provide phonetic hints for brand names, technical terms, or abbreviations:

# General Information

- Company: DGUV (pronounce: "De-Gu-Fau")
- Product: DREI-Schein (pronounce: "Dry-Shine")
- Contact person: Mr. Szymanowski (pronounce: "Shi-ma-noff-ski")

Email Addresses and Websites

ScaleTalk has built-in middleware that automatically pronounces email addresses and websites correctly. Simply write them in the prompt as they are written — e.g., contact@samplecompany.com or www.samplecompany.com. Phonetic transcriptions are not needed for these.

Also define how numbers should be spoken:

- Spell out customer numbers individually:
  "324124" -> "three, two, four, one, two, four"
- State prices as spoken numbers:
  "52.00 EUR" -> "fifty-two euros"

Forcing Variety

Without a "variety" rule, the model often repeats the same phrasings:

# Behavior Rules

- Do NOT always use the same phrasings.
- Alternate between different transitions.
  Instead of always "I understand" also use:
  "Got it", "I can relate to that",
  "Good that you're calling".
- Do NOT repeat the caller's statement verbatim.

Setting Guardrails

Preventing Hallucinations

The biggest risk: The agent makes up answers. For prices, business hours, or legal questions, this can have serious consequences.

# Behavior Rules

- NEVER make up answers, prices, or facts.
- Answer questions ONLY if the answer is clearly
  found in the knowledge base.
- If you don't know something, say:
  "That's a great question. To give you the best
  possible information, I'll have [Name] get back
  to you personally."

Sensitive Topics

Explicitly define which topics your agent should decline:

# Sensitive Topics

If the customer brings up the following topics,
say that you cannot help with this:
- Legal questions
- Medical information
- Political topics
- Discounts or individual price negotiations

Limiting Call Duration

# Behavior Rules

- End the call ONLY when the caller has explicitly
  agreed and doesn't need anything else.
- If the caller has been silent for 5 seconds:
  "Are you still there? Can I help you with anything else?"
- If the caller is silent again:
  "I'm afraid I can no longer hear you. Thank you for
  your call and goodbye!"

Advanced Techniques

Capital Letters as a Control Mechanism

Use CAPITAL LETTERS for especially important rules — the model gives them more weight:

- NEVER make up answers.
- Do NOT transfer.
- ALWAYS mention the price.
- Ask questions ONE AT A TIME, never as a block.

Use capital letters sparingly — if everything is capitalized, it loses its effect.

Known vs. Unknown Caller

If you use pre-call variables, you always need two paths:

## Step 2: Identify the caller

- If {{CustomerLastName}} is populated:
  Say e.g.: "I have on file that you are
  {{Salutation}} {{CustomerLastName}} from {{CompanyName}}
  — is that correct?"

- If {{CustomerLastName}} is empty:
  1. "May I ask who I'm speaking with?"
  2. "And which company are you calling from?"

Gatekeeper Logic

If your agent should filter unwanted calls:

### If someone wants to sell something (marketing, SEO, cold calls):
- Decline politely but firmly.
- Say: "That's kind of you, but we don't have any need
  for that at the moment. You're welcome to send us an email
  at info@samplecompany.com."
- End the conversation politely.

Reducing Latency

General rule of thumb: As short as possible, as long as necessary. Every additional token in the prompt increases response time.

Trim the prompt to the essentials
Move FAQ and detailed knowledge to the knowledge base
Avoid redundant phrasings — each piece of information only once
Test response speed after every change

Handling Interruptions

# Behavior Rules

- If the caller interrupts you, stop immediately.
- Address the new point before continuing your
  previous thought.
- Do NOT try to finish your previous sentence.

Formatting Rules

Correct	Incorrect
`# Main Heading`	`Heading`
`## Step 1: Greet`	`Step 1 – Greeting`
`### If customer wants appointment:`	`In case the customer would like...`
`1. Ask for name.`	`First you should ask...`
`---` between blocks	No visual separator
`Say: "Phrasing"`	`You could for example say...`

Avoid prose and long explanations. The model needs clear instructions, not essays.

Common Mistakes

Mistake	Problem	Solution
Question block	Sounds like an interrogation	Always one question at a time
No catch-all	Agent gets stuck on unexpected topics	"Other" scenario at end of every decision tree
No anti-hallucination	Agent makes up prices and facts	Explicit rule: ONLY from knowledge base
Prose instead of instructions	Model interprets imprecisely	Clear steps and bullet points
Reading out lists	Sounds robotic	Rephrase into natural sentences
Redundancy	Increases latency and causes confusion	Each piece of information only once
No transfer fallback	Agent hangs on error	Always define an alternative path
Too many tasks	Agent loses focus	Better 2 specialized agents than 1 overloaded one

Complete Example: Appointment Booking (Hair Salon)

# General Information

- Your name: Lisa
- Your role: Phone assistant / Appointment manager
- The company: Salon Schneidekunst (Hair salon, Graz)
- Owner: Maria Hoffmann
- Form of address: Address customers formally
- Speaking style: Friendly, warm, welcoming, professional
- Behavior: Helpful, solution-oriented, efficient
- Call duration: Keep it brief, get to the point

---

# Conversation Flow

## Step 1: Greet
Listen carefully to the caller.

## Step 2: Identify the concern

### If appointment booking:
1. Ask which service.
2. Search next available slot via Calendar Tools.
3. Offer WITH price:
   "Next available slot for a women's haircut:
   Thursday, 10:30 AM. 52 euros. Does that work?"
4. YES: Ask for name + phone number. Book the appointment.
5. NO: Offer the next slot.

### If cancellation/rescheduling:
- Ask for name and appointment.
- "Cancellation is free up to 24 hours before."

### If general questions:
- Answer from knowledge base.

### Other:
- "Could you briefly describe what this is about?"

---

# Appointment Booking – Rules
- 30-minute intervals
- Slots: 09:00 to 17:30
- Saturday: until 13:30
- Mon + Sun: Closed

---

# Behavior Rules
- NEVER make up answers or prices.
- With every appointment suggestion ALWAYS mention the price.
- Ask questions ONE AT A TIME.
- Do NOT repeat the caller's statement.

---

# Knowledge Base
Answer questions ONLY if the answer is clearly found there.

Pre-Launch Checklist

Agent's goal clearly described
All sections have headings
If-then logic complete, catch-all present
Required data defined and asked during the flow
Tools correctly referenced (Calendar, Transfer)
Fallback for failed transfer defined
Anti-hallucination rule in the behavior rules
Sensitive topics defined
Phonetic hints for difficult terms
Prompt checked for brevity — nothing redundant
Tone matches the company

Testing

A prompt is never perfect — it gets better through testing and refinement. Plan from the start to revise your prompt regularly.

Quick test: 3-5 test calls with typical concerns. Does it sound natural? Is data captured? Do the tools work?
Edge cases: Unclear concern, unwanted calls, interruptions, multiple concerns at once, silence.
Test the limits: Try to get the agent to do things it shouldn't — price negotiation, making up facts, going outside its scope.
Fine-tuning: Read transcripts. Shorten phrasings. Add missing paths.

Tip

Prompt engineering is an ongoing process. Even after launch, you'll keep making adjustments based on real calls. Regularly read transcripts to identify weaknesses and improve your prompt.

Prompting

On this page