Skip to main content

​
Prompt Engineering for Assistants

Writing effective agent instructions is both an art and a science. Good instructions result in agents that consistently perform well, handle edge cases gracefully, and delight users. This guide teaches you how to write instructions that work.

​
The Fundamentals

​
What Makes Good Instructions?

Good agent instructions are:

Specific

Clear, detailed, and unambiguous. Vague instructions produce inconsistent results.

Actionable

Tell the agent what to DO, not just what to BE. Focus on behaviors and actions.

Complete

Cover the main cases, edge cases, and failure modes your agent will encounter.

Examples-Rich

Show the agent how to handle specific scenarios with concrete examples.

​
Bad vs. Good Instructions

Problems:
  • Too vague (“help with questions”)
  • No specific guidelines
  • No tool usage instructions
  • No examples
  • No edge case handling

​
Instruction Structure

​
Section Breakdown

Define who the agent is and what they do.Good:
Bad:
Include:
  • Company name and what you do
  • Agent’s specific role
  • Primary function
  • Key context
List specific tasks the agent handles.Good:
Bad:
Be specific: Each item should be actionable and measurable.
Define how the agent should communicate.Good:
Bad:
Include:
  • Tone and personality
  • Length guidelines
  • Formatting preferences
  • Example opening and closing
Explain when and how to use each tool.Good:
Bad:
For each tool:
  • When to use it
  • Required inputs
  • Specific rules
  • Example usage
Define hard constraints and policies.Good:
Bad:
Include:
  • Qualification criteria
  • Disqualification rules
  • Escalation triggers
  • Things agent should never do
Show how to handle unusual situations.Good:
Bad:
Include:
  • 3-5 common edge cases
  • Exact response language
  • What to do, step by step
  • When to escalate
Provide full conversation examples.Good:
Why this works:
  • Shows complete flow
  • Demonstrates tool usage
  • Models good conversation
  • Handles objections
  • Clear next steps
Include 2-3 examples:
  • Qualified lead (success case)
  • Unqualified lead (rejection case)
  • Edge case (unusual scenario)

​
Advanced Techniques

​
Chain of Thought Prompting

Encourage step-by-step reasoning by asking agents to think through problems.

​
Few-Shot Examples

Provide multiple examples of desired behavior.

​
Constraint Specification

Clearly define what agents should and shouldn’t do.

​
Persona Consistency

Define personality traits with examples.

​
Common Patterns

​
Customer Service Agent

​
Lead Qualification Agent

​
Content Generation Agent

​
Testing & Iteration

​
Test Scenarios

Always test instructions with:
Standard, straightforward cases.
Unusual but possible scenarios.
Attempts to break or confuse the agent.
When tools fail or data is missing.

​
Iteration Process

1

Deploy Initial Instructions

Start with your best attempt at complete instructions
2

Test Thoroughly

Run through 10-20 test scenarios covering happy path and edge cases
3

Identify Gaps

Note where agent behavior doesn’t match expectations:
  • Wrong tool usage
  • Incorrect responses
  • Missing edge case handling
  • Tone issues
4

Update Instructions

Add specific guidance for identified gaps:
  • More explicit tool usage rules
  • Additional examples
  • Edge case handling
  • Clarified policies
5

Re-test

Verify improvements work and didn’t break existing behavior
6

Monitor Production

Watch real conversations for new edge cases
7

Continuous Improvement

Update instructions based on real-world performance

​
Common Mistakes

❌ Bad: “Be helpful” ✅ Good: “When customers ask questions, search the knowledge base first, then provide a clear 2-3 sentence answer with a link to the full article”Fix: Add specific actions and examples
❌ Bad: “Use the refund tool appropriately” ✅ Good: “Use the refund tool only when: 1) Customer explicitly requests refund, 2) Order is < 30 days old, 3) Amount is < $500”Fix: State all assumptions explicitly
❌ Bad: “Handle customer complaints professionally” ✅ Good: “Example: Customer says ‘This product is terrible!’ Response: ‘I’m sorry you’re having a bad experience. I want to help make this right. Can you tell me specifically what issue you’re encountering?’”Fix: Show don’t tell - provide concrete examples
❌ Bad: Only describing happy path scenarios ✅ Good: “If order is past 30-day policy: ‘I understand you’d like a refund. Our policy is 30 days, and your order is 35 days old. While I can’t process this automatically, let me escalate to our billing team to review your specific situation.’”Fix: Explicitly handle edge cases and exceptions
❌ Bad: “Be concise” + “Provide detailed explanations” ✅ Good: “Be concise: 2-3 paragraphs for most responses. Provide detailed explanations only when: 1) Customer asks for more detail, 2) Technical setup instructions, 3) Complex policies”Fix: Clarify when each instruction applies
❌ Bad: “You have access to these tools: [list]” ✅ Good: “Order Lookup: Use whenever customer mentions order number. Call it BEFORE answering order status questions. Example: Customer says ‘Order #12345’ → Look it up first, then respond”Fix: Explain when and how to use each tool with examples

​
Resources

Information Settings

Where to add agent instructions

Best Practices

Comprehensive agent optimization guide

Tools & Connectors

How to connect data sources and APIs

Creating First Agent

Step-by-step tutorial