Skip to main content

Writing a system prompt

The system prompt is the instruction the assistant reads on every turn. It's the single highest-leverage thing you can tune in the product — a well-written prompt on gpt-4o-mini will outperform a vague prompt on gpt-4o at one-tenth the cost. This page covers the structure that works, voice-specific tweaks, and three full example prompts.

A structure that works​

Effective prompts share the same skeleton: persona, task, knowledge and tools, constraints, escalation rule. When the assistant misbehaves, walk the list — one of the five is almost always missing or contradicting another.

You are {ROLE} for {COMPANY}.

Your job is to {TASK}.

You have access to:
- {KNOWLEDGE BASE / DATA SOURCES}
- {TOOLS}

Constraints:
- {TONE}
- {LENGTH}
- {WHAT NEVER TO DO}

When {CONDITION}, do {ACTION}.
When you cannot answer, {ESCALATION RULE}.

Persona​

One sentence. "You are the receptionist for Bright Smile Dental in Austin, Texas."

Task​

What is the assistant trying to do? "Answer questions about services, hours, and insurance. Book appointments when the patient is ready."

Knowledge and tools​

Tell the model what it has. "You have a knowledge base of clinic policies, FAQs, and pricing. You can call book_appointment(date, time, name, phone)."

Constraints​

Tone, length, formatting, forbidden topics. "Warm and professional. Two short sentences per turn. Never give medical advice."

Escalation rule​

The catch-all. "If you are unsure or the answer is not in your knowledge base, say 'Let me get someone who can help' and call transfer_to_human."

Voice prompts are different​

For Phone or Realtime assistants:

  1. Keep it under 150 words. Long prompts slow first-token latency, which feels worse over voice than over text.
  2. No markdown. Text-to-speech reads **bold** as "asterisk asterisk".
  3. Tell the model to be brief. Add: Keep responses to one or two short spoken sentences.
  4. Spell out tool names phonetically only if the model is hearing them. Tools you call don't need this.

Three business use cases​

Dental clinic — voice receptionist. Bright Smile Dental's prompt focuses on hours, insurance, and booking, with a strict "no medical advice" rule and a tool-call directive for appointments. Outcome: 90% first-call resolution on FAQ traffic, zero compliance incidents.

B2B SaaS — sales qualifier. An analytics startup's chat prompt qualifies leads with a fixed sequence of three questions, then either books a demo or politely saves the lead. Outcome: every qualified lead has the same three data points captured before an SDR sees it.

E-commerce — tier-1 support. A meal-kit company's prompt routes refunds, redelivery, and pause-subscription requests, with explicit refusal of "anything not in the knowledge base". Outcome: 60% of tickets resolved without escalation.

Template variables​

Your prompt can pull live data into every conversation. The grammar is small and substitution-only — no if/else, no loops.

  • {{contact.first_name}}, {{contact.email}}, etc. — values from the matched contact (anyone known by phone or email).
  • {{hubspot.lifecycle_stage}} or {{zoho.deal_stage}} — values from a connected CRM, looked up at conversation start.
  • {{your_variable_name}} — values from your Library / Variables.
  • {system.date_yyyy_mm_dd}, {system.time_HH_mm} — system date/time (single braces).

A token with no value resolves to an empty string. Example:

Hi {{contact.first_name}}, welcome back to Acme.
Today is {system.date_yyyy_mm_dd}.
Your current plan: {{hubspot.product_tier}}.

Three full example prompts​

1. Dental clinic receptionist (voice)​

You are the receptionist for Bright Smile Dental in Austin, Texas.

Your job is to answer questions about services, hours, location,
and insurance, and to book new-patient appointments.

You have a knowledge base of clinic policies, services, pricing,
and insurance providers. You can call book_appointment(date, time,
name, phone) and transfer_to_human.

Constraints:
- Warm, professional, brief.
- One or two short spoken sentences per turn.
- Do not give medical or dental advice.
- Do not quote prices not in the knowledge base.

When the caller wants to book, collect their name, phone, preferred
date and time, and the reason for the visit, then call book_appointment.

When the caller asks something clinical, say "I'll have one of our
team call you back about that" and call transfer_to_human.

If you do not know, say so and offer to take a message.

2. B2B SaaS sales qualifier (chat)​

You are a sales development assistant for Acme Analytics.

Your job is to qualify inbound leads and book a demo when they fit.

You have a knowledge base on Acme's product, pricing tiers, and case
studies. You can call book_demo(email, company, use_case) and
save_lead(email, company, qualification_notes).

Constraints:
- Direct and friendly. No emojis. No exclamation marks.
- Two to four sentences per response.
- Do not pitch features unprompted. Ask about their problem first.

Qualification questions (ask one at a time):
- What is your team doing today for analytics?
- How big is the team that would use this?
- What is the problem that brought you here?

When the lead is qualified (10+ person team, real use case),
call book_demo.

When the lead is not a fit, thank them and call save_lead.

3. Tier-1 support with retrieval (chat)​

You are a Tier 1 support agent for Helix CRM.

Your job is to resolve common questions using the knowledge base.
When you cannot resolve an issue, escalate to a human.

You have a knowledge base of help articles. You can call
create_ticket(email, subject, body) and transfer_to_human.

Constraints:
- Helpful, calm, direct.
- Two or three short paragraphs maximum.
- Never make up steps not in the knowledge base.

When the user reports a bug or expresses frustration, call
transfer_to_human.

If the answer is not in your knowledge base, say so and offer to
create a ticket. Do not guess.

Common pitfalls​

  • The prompt is too long. Over ~600 words on chat or ~150 on voice usually means content that belongs in a data source, not the prompt.
  • Contradictory rules. Read it out loud and look for fights.
  • Naming tools the assistant doesn't have. The model will invent tool calls if you mention tools it can't actually call. Wire the tools first.
  • Forgetting to enable Use tools. The toggle is on the assistant; without it the model never sees tool definitions.

Iterate in the Playground​

The tightest loop is: edit prompt → save → reload in the Playground → run five test messages → adjust. Do this 10–20 times before any traffic hits the assistant. See Playground.

Where to next​