Best practices when writing instructions

A practical guide to creating effective AI voice agents that stay on track and don't make things up.

========================================

The 5 Critical Elements

Every agent instruction needs these five components in this order:

1. Agent Setup - Identity and objective
2. Constraints - What the agent can and cannot say (MOST IMPORTANT)
3. Tools - External data sources and actions
4. Conversation Flow - Pseudo-code logic
5. Objection Handling - How to handle "no"

========================================

1. Agent Setup

AGENT_NAME: Sarah CALL_TYPE: Outbound sales OBJECTIVE: Schedule product demos TONE: Friendly, professional, not pushy

========================================

2. Constraints (CRITICAL - Spend Time Here)

This prevents your agent from making things up. Place this prominently at the top.

CRITICAL CONSTRAINTS

Agent CAN share:

• Product: CloudSync CRM
• Pricing: $49/user/month (annual), $59/month (monthly)
• Free trial: 14 days, no credit card required
• Features: Contact management, email integration, reporting

Agent CANNOT invent:

• Discounts or custom pricing
• Feature release dates or promises
• Competitor comparisons
• Guarantees of results

When agent doesn't know something:

• Say: "Let me connect you with our specialist who can answer that."
• NEVER guess or say "I think" or "probably"

Why this matters: Without constraints, agents confidently make up prices, features, or promises that create legal problems.

========================================

3. Tools (If Needed)

Declare tools at the top, use them during conversation.

AVAILABLE TOOLS

1. lookup_customer(phone_number) Returns: name, purchase_history Use when: Need customer data to personalize

2. check_availability(date, service_type) Returns: available_time_slots Use when: Scheduling appointments

3. create_appointment(date, time, customer_info) Returns: confirmation_number Use when: Customer confirms time

Tool Usage Rules

Use for: customer-specific data, real-time availability, creating records Don't use for: static info already in instructions Always handle errors: IF tool.status == "error"

Example:

CALL_TOOL: check_availability(date=date) STORE result AS slots

IF slots.status == "error": SAY "I'm having trouble with our system. Let me transfer you."

========================================

4. Conversation Flow (Pseudo-Code)

Write conversations as clear decision trees using pseudo-code.

Tip: Use AI to convert your natural language instructions into pseudo-code format. Prompt: "Convert this conversation script into pseudo-code with SAY, WAIT_FOR_RESPONSE, IF/ELSE, and CALL STEP syntax."

Example:

BEGIN_CALL SAY "Hi, this is Sarah from CloudSync. Do you have a minute?" WAIT_FOR_RESPONSE

IF response CONTAINS "interested" OR "yes":    CALL STEP: Qualify_Needs ELSE IF response CONTAINS "busy" OR "not now":    CALL STEP: Timing_Objection ELSE:    CALL STEP: Probe_Interest

STEP Qualify_Needs: SAY "Are you currently using any CRM?" WAIT_FOR_RESPONSE

IF response CONTAINS "yes":    CALL STEP: Competitive_Position ELSE:    CALL STEP: New_CRM_Pitch

Key Syntax

• SAY - Agent speaks
• WAIT_FOR_RESPONSE - Agent stops and listens (critical!)
• IF/ELSE - Routes based on customer response
• CALL STEP - Jump to another section
• EXTRACT - Pull data from response
• STORE - Save data for later use

Intent Routing

Include 4-6 keyword variations per intent:

IF response CONTAINS "price" OR "cost" OR "how much" OR "expensive": CALL STEP: Discuss_Pricing

ELSE IF response CONTAINS "trial" OR "demo" OR "try it": CALL STEP: Schedule_Demo

========================================

5. Objection Handling

Use: Acknowledge → Probe → Reframe → Ask

STEP Price_Objection: SAY "I understand budget is important." SAY "Is it the monthly cost that's the concern?" WAIT_FOR_RESPONSE

SAY "Most teams save 10 hours weekly - about $500 in productivity." SAY "Would a free trial help you see the ROI?" WAIT_FOR_RESPONSE 
IF still resistant:    SAY "That's fair. Can I check back in a few months?"

Rules:

• Give 2-3 recovery attempts
• Never argue or get defensive
• Exit gracefully if still no

========================================

Writing Tips

Sound Conversational

DON'T: "I am contacting you to discuss our enterprise solution." DO: "Hi! I'm calling from CloudSync. Got a minute?"

Test: Read it aloud. Robotic? Rewrite it.

Progressive Disclosure

Don't dump all info at once. Share based on customer interest:

SAY "We help you track customer interactions. What's most important - keeping your team organized or pipeline visibility?" WAIT_FOR_RESPONSE

IF mentions "organized": SAY "Our task features make that easy. Want to see a demo?"

Data Collection Timing

EARLY: Team size, current solution, general needs LATE (after commitment): Email, full name, company details

Don't ask for contact info too early - feels invasive.

========================================

Quick Reference Template

AGENT_NAME: [Name] OBJECTIVE: [One clear goal] TONE: [Specific description]

CRITICAL CONSTRAINTS Agent CAN share: [List facts] Agent CANNOT invent: [List prohibitions] When unsure: [Fallback phrase]

TOOLS

1. tool_name(params) - Returns X, Use when Y

FLOW BEGIN_CALL SAY "[Opening]" WAIT_FOR_RESPONSE IF [condition]: CALL STEP: [Name]

STEP [Name]: SAY "[Response]" WAIT_FOR_RESPONSE [Logic]

========================================

Pre-Launch Checklist

• Constraints section exists and is comprehensive
• All facts verified and current
• Tool error handling for every tool call
• "I don't know" fallbacks defined
• WAIT_FOR_RESPONSE after every question
• 2-3 objection recovery attempts before exit
• Dialog sounds natural when read aloud
• Every path tested (happy path + objections)

========================================

Common Mistakes and Fixes

Agent makes up info → Stronger constraints section Sounds robotic → Use contractions, casual language Interrupts customer → Add WAIT_FOR_RESPONSE markers Can't handle "no" → Add objection handling steps Tools fail silently → Add error handling everywhere Info dump → Progressive disclosure based on interest

========================================

The One Thing to Remember

Constraints prevent 90% of problems. Spend time on section 2.

Without explicit constraints, AI agents will:

• Invent prices
• Promise features that don't exist
• Make up delivery dates
• Quote wrong information confidently

Everything else can be fixed later. Bad constraints create legal and customer service disasters.

========================================

Converting to Pseudo-Code

Don't write pseudo-code manually. Use AI to convert your natural language instructions:

Prompt:

"Convert this conversation script into pseudo-code format using:

• SAY for agent speech
• WAIT_FOR_RESPONSE for pauses
• IF/ELSE for routing logic
• CALL STEP for navigation
• EXTRACT and STORE for data handling

[Paste your natural language instructions here]"

The AI will structure your instructions into the proper format automatically.

========================================

Start simple. Test thoroughly. Add complexity only when needed.