General tips & tricks for writing Instructions

This article provides practical guidance for writing clear and effective Instructions for your AI Agent in Watermelon. These tips apply to both Instructions and Domain Knowledge and help you steer the behavior of your AI Agent with precision.

A language model like GPT generates text based on input. An “Instruction” (also called a prompt) is a command you give to the model. Through this Instruction, you define how the model should behave and how it should respond to user questions.

Why good instructions are essential

Your AI Agent may already have access to a lot of knowledge, but without clear Instructions, the model doesn’t know how to apply that information. Instructions define the framework within which the AI Agent operates. They are essential to guide the model’s behavior, align it with your brand, and ensure appropriate user responses.

Best practices for effective instructions

1. Write as if instructing a colleague

• Use the second person (“you”).
• This perspective helps the AI Agent better understand and follow the Instructions.

2. Be extremely clear and specific

• Clearly define what you expect from the AI Agent: goal, context, tone, length, output format, persona.
• Avoid vague terms like “keep it short.” Instead, say “respond in a maximum of 3 sentences” or “use a list of 3 bullet points.”

3. Add example interactions

Don’t let the AI Agent guess—show it what you expect:

Example:

User: What are your opening hours?

Assistant: Our customer service is available Monday to Friday from 9:00 AM to 5:00 PM.

4. Provide context and break down complex tasks

• Share relevant background information.
• Split complex tasks into steps (e.g., first ask for information, then provide advice or a response).

5. Keep Instructions concise and relevant

• Avoid unnecessary details.
• Prevent repetition or conflicting instructions (“overprompting”), as this can confuse the AI Agent and reduce effectiveness.

6. Consider multilingual usage

• If your AI Agent supports multiple languages, provide language-specific Instructions.
• Refer to this article for more information on multilingual AI Agent behavior.

7. Be friendly and empathetic

• Include Instructions that encourage empathy and customer friendliness.
• Ensure the AI Agent shows understanding and supportive responses.
• Apply this in both Instructions and Domain Knowledge.

8. Use positive language

• Formulate Instructions constructively.
• For example: say “You may do X” instead of “You must not do X.”
• Or “You say A when asked B” instead of “You don’t respond to B.”

Optimization & Evaluation

Test systematically

• Use multiple test questions to evaluate consistency.
• Adjust Instructions based on user interactions and results.

Use Evals to test

Evals are evaluations that test whether your AI Agent behaves as expected. You check if the output matches what you want—factually correct, correct tone, or specific format.

An Eval consists of a user input (a question), the expected output (the desired answer), and the AI Agent’s actual response. Comparing these helps you spot errors, inconsistencies, or areas for improvement. This allows you to refine Instructions in a focused way.

You can use Evals to optimize your AI Agent’s performance. Test various scenarios, analyze deviations, and refine your Instructions to ensure more consistent, high-quality responses.

Example Eval:

"question": "What is the capital of the Netherlands?",

"expected_answer": "Amsterdam",

"given_answer": "Amsterdam"

Keep improving

• Regularly review and update your Instructions to reflect new company information or developments.
• Monitor user questions and identify areas for improvement.
• Analyze AI Agent interactions to uncover patterns and FAQs.
• Use these insights to fine-tune your Instructions and enhance AI Agent performance.
• Watch for regression: an improvement in one area may cause issues elsewhere, so always test with multiple examples.

FAQ

What if my Instruction doesn’t work as expected?

Test with multiple examples and ensure your Instruction is clear and specific enough.

Why does the AI Agent sometimes respond differently than intended?

The model follows your Instruction literally. Vague or incomplete prompts can lead to undesired behavior.

Do I always need to include examples?

Not mandatory, but adding examples significantly improves Instruction effectiveness.

 

By applying these guidelines, you’ll create Instructions that are not only clear and purposeful but also help deliver consistent, high-quality responses from your AI Agent.