Your AI Agent doesn't need a manifesto. It needs a tight, unambiguous spec. Here's how to write one.

We recently rewrote our AI Receptionist's system prompt. The previous version was 450 lines long, beautifully structured, full of carefully reasoned policy - and it was eating so much of the context window that the agent had less room to actually listen to the caller! To help you avoid the same problems, this blog - Part 1 now and Part 2 to follow - tells you how to stop writing poetry and start writing instructions, so read on to learn more!

The Mistake Everyone Makes First

We're not the only ones making this mistake. Almost every 3CX client editing a system prompt for the first time makes the same one: they treat the prompt like a policy document, a legal contract, or — worse — a creative writing assignment.

Here's the trap: because prompts are written in English, people forget they're writing code. They write paragraphs. They add adjectives. They define terms the model already understands. They restate the same instruction five times because it feels important.

The model doesn't read prose the way humans do. Every word in your prompt costs context, attention, and — frequently — consistency. A long prompt is not a more careful prompt. It is usually a worse one.

This guide is what we learned while rewriting our own. If you're editing the system prompt of a 3CX AI Agent, read it before you save.

The English Trap

When prompt engineering meant writing for an API in raw JSON, people respected it as a technical discipline. Now that the instructions are in English, people write the way they write a Slack message to a new hire.

Look at this snippet from the old version of our own prompt:

"The caller's reason is required before handoff, but it must not be used to identify, narrow, rank, disambiguate, replace, or override the requested destination."

That sentence is grammatically correct, well-considered, and almost impossible for a model to follow consistently across a real call. Six near-synonyms. Two clauses. A negation wrapped around a requirement. By the third turn of the conversation, the model is interpreting it differently than it did on the first.

Here is what it became:

"Do not use information search to decide who should receive a call."

One sentence. One instruction. Zero ambiguity. Same behaviour.

Rule one of prompt engineering: English is the interface, not the genre. You are still writing instructions. Short, declarative, testable. If a sentence reads like something you'd find in a terms-of-service document, delete it and try again.

Stop Defining Things to the Model

The old prompt contained this gem:

"A handoff is any permitted next step executed via one of the actions listed below."

The model knows what a handoff is. It also knows what "transfer," "voicemail," and "email" mean. Defining everyday terms back to the model is a habit borrowed from technical writing for humans. In a prompt, it just burns tokens and creates surface area for the model to misinterpret.

The same applies to ceremonial section headers. The old prompt had:

  • Mandatory Enforcement
  • Priority Order
  • Base Schema
  • Action Selection Rules

These read like they came from an RFC. They add no behaviour. The new prompt uses headers like Style, Routing, Hostility — short labels that describe what the section is about, not how serious it sounds.

Rule two: if a line doesn't change what the model does, delete it.

Say It Once

One of the worst pathologies in long prompts is the same rule appearing in four places. In our old version, "do not hand off if the destination is ambiguous" appeared, with slight variations, in:

  • Destination Ambiguity Rule
  • Handoff Action Gate
  • Directory Rules
  • Confidential Output Contract

Each restatement was a little different. Each one used slightly different wording. A human reading them sees four versions of the same idea and understands the intent. A model reading them sees four rules — and when they don't perfectly agree, it has to pick. Sometimes it picks differently on the third call of the day than on the first.

Rule three: every rule belongs in exactly one place. If you find yourself reinforcing a rule by repeating it in a new section, you don't need a new section. You need a clearer first version.

Stop Stacking Do Nots

Look at this:

"Do not pick the first result, best result, available result, or most relevant result."

This is four negative instructions where one positive instruction would do. What the rule actually means is:

"If lookup returns multiple matches, ask the caller to clarify."

Positive instructions tell the model what to do. Negative instructions tell the model what to avoid, which leaves the open question of what to do instead — and the model will invent an answer.

Rule four: prefer positive instructions. Use "do not" only when there is no positive equivalent.

Watch for Contradictions

This one is the silent killer. The old prompt contained two sections that, read together, were inconsistent:

  • Routing by Reason: when the caller gives a reason, call the address book to resolve a destination.
  • Routing by Requested Destination: when the caller asks for a person or department, do not use the reason for routing.

Both true. Both reasonable. But sequenced in a long prompt with overlapping examples and reinforcing sub-rules, the model gets confused about which one applies — and that confusion shows up as inconsistent behaviour the customer never quite manages to reproduce on demand.

Use OpenAI Tokenizer to see how the model actually breaks your prompt into tokens. Then read the prompt back as if you knew nothing about your business, in order, with no context. If two rules could plausibly apply to the same situation and lead to different actions, you have a contradiction — even if you can explain why they don't conflict.

Rule five: a prompt is consistent when no two rules can both apply and disagree. Not when you can rationalise the difference.

In the next few days, we'll publish Part 2 of this series, where we'll take a closer look at what the model can and can't do, tips for first-time prompt engineers and more. Stay tuned!

Join the Discussion

Join the 3CX discussion in our dedicated Partner or Customer Forums. Follow us on X and LinkedIn to stay-up-to date on latest news and feature releases.