Skip to main content
Clear instructions are the foundation of a reliable AI Agent. Well-structured instructions make your agent:
  • Predictable
  • Consistent
  • Accurate
  • Easier to optimize
  • Less likely to hallucinate
This guide explains how to structure AI Agent instructions so they behave exactly as intended — using real Watermelon product examples.

​
The simple way to think about instructions

You don’t need a complicated framework. Most good instructions follow one simple idea: 
When a user says X, always respond with Y.
That’s it. For example:
  • “If someone asks about pricing, mention the Free plan and share the signup link.”
  • “If a user wants to delete their account, tell them to create a support ticket.”
  • “If someone says the answer isn’t helpful, ask if they want a human agent.”
You don’t have to literally write “If → Then.”
But thinking this way makes instructions clearer and more reliable. Clear situation + clear response = better results.

​
What instructions can (and can’t) do

Instructions guide the Agent’s behavior — they do not enforce it. AI models (LLMs) generate responses probabilistically.
Words like “always” or “never” signal strong intent, but they are not hard technical guarantees. Instructions also compete with other context, such as:
  • The latest user message
  • Conversation history
  • Added sources
Because all of this shares the model’s attention, rule compliance can weaken — especially in longer conversations. Instructions work best when they are:
  • Clear
  • Short
  • Focused
The simpler and more specific the rule, the more reliable the outcome.

​
Keep instructions short

Long instructions are harder to follow consistently. Instead of writing:
“When someone asks about pricing, explain the Free plan, compare all features, mention onboarding, include discounts, and explain Enterprise.”
Break it into smaller instructions:
  • Instruction 1 → Mention Free plan + signup link
  • Instruction 2 → Explain plan differences
  • Instruction 3 → State that Enterprise pricing is custom
Smaller rules are easier for the Agent to follow than long paragraphs.

​
Use clear triggers

Start your instruction by describing the situation clearly. Good examples:
  • When someone asks about pricing…
  • If a user mentions cancelling…
  • When someone reports a bug…
Avoid vague phrasing like:
  • “Talk about pricing.”
  • “Help with cancellations.”
Be specific about:
  • What the user says
  • What topic is being discussed
The clearer the trigger, the more consistent the behavior.

​
Be specific about the response

Avoid general instructions like:
  • “Explain pricing clearly.”
  • “Handle complaints properly.”
  • “Do not send urls that don’t exist”
Instead, describe what the agent should actually do.

​
Example: pricing

When someone asks about pricing:
  • Mention that we have a Free plan.
  • Share https://signup.watermelon.ai/
  • Explain the differences between Starter, Advanced, and Business.
  • State that Enterprise pricing is custom only.
  • Do not invent custom pricing.
This prevents:
  • Hallucinated discounts
  • Fake pricing
  • Incomplete answers
If the Agent should send users to a specific page, add the exact link in the instruction. This improves accuracy and reduces the chance of incorrect or invented URLs.

​
Add guardrails when necessary

If your product cannot do something, say it clearly in the instruction. Example:
If someone wants their account deleted, tell them to create a support ticket via the Help menu. You cannot delete accounts yourself.
Or:
You cannot start a conversation from the inbox. The customer must initiate it.
Clear limitations prevent overpromising. Read this article for more guardrails examples.

​
Rewrite vague instructions (practical examples)

Here’s how to improve unclear instructions. Example: tone of voice
“Be friendly and helpful.”
When greeting a user, use a short and friendly tone. Keep responses under 5 sentences.
Example: handling negativity
“Handle complaints properly.”
If a user expresses frustration:
  • Acknowledge it
  • Apologize once
  • Offer a next step
  • Ask if they want human support
Example: referring to links
“Explain pricing clearly.”
When someone asks about pricing:
Concrete instructions work better than general advice.

​
Test your instructions

After adding or editing an instruction:
  1. Open the Playground
  2. Trigger the situation on purpose
  3. Try different wording
  4. Test edge cases
  5. Check escalation behavior
If it doesn’t behave as expected:
  • Simplify the instruction
  • Break it into smaller parts
  • Check for overlapping rules