# Writing Agent Instructions that perform

Agent Instructions are the system prompt a ClearTalk agent runs on. They are the single highest-leverage text in the product: the same campaign with better instructions books more appointments. This is the craft.

## Structure that works

Order matters — the agent weights what comes first. Use this skeleton:

1. **Identity** — who the agent is, one sentence. Name, company, role. ("You are Sam, a scheduling assistant for Acme Solar.")
2. **Objective** — the ONE thing a successful call achieves, stated as an outcome. ("Your goal is to book a 15-minute consultation.") One objective per agent; an agent asked to qualify AND book AND survey does none well.
3. **What you know** — the 5–10 facts the agent may state: offer, price frame, service area, availability. If it isn't listed, the agent must say it doesn't know and offer to find out. Longer material belongs in a knowledge base, not the instructions.
4. **Conversation shape** — the beats in order: confirm who answered → reason for the call → one qualifying question at a time → the ask → close. Not a script; beats.
5. **Objection handling** — the 3–5 pushbacks that actually occur, each with the response strategy. "Too expensive" → acknowledge, reframe around the consult being free, offer the booking again once.
6. **Hard rules** — the nevers: never claim to be human if asked directly, never quote prices not listed above, never call back someone who said stop, always end politely.
7. **Voice and tone** — spoken register: short sentences, contractions, no lists, no jargon. Phone conversation, not email.

## Principles

- **Concrete beats abstract.** "Ask: would mornings or afternoons work better?" outperforms "try to schedule a time." Give exact wordings for the moments that matter most — the opener and the ask.
- **One question per turn.** People answer the last question they heard. Instructions that stack questions produce agents that interrogate.
- **Write for the ear.** The agent speaks this. Read every canned phrase aloud; if it sounds like an email, rewrite it.
- **Handle the exits.** Voicemail, wrong number, "take me off your list", hostile — each needs one line of policy or the agent improvises badly. ("If voicemail: leave a 15-second message with the callback number, then end.")
- **Don't fight the platform.** Calling hours, retries, and do-not-contact are enforced by campaigns and lists. Instructions saying "only call during business hours" are dead weight.
- **Shorter wins.** Every sentence competes for the agent's attention against the live conversation. If a sentence hasn't earned its place in a test transcript, cut it.

## Instructions vs Pathway vs knowledge base

- **Instructions**: personality, objective, tone, objection strategy — things true of every turn.
- **Pathway**: branching logic — "if qualified, go to booking; if not, polite exit." When you find yourself writing if/then chains in instructions, that logic wants to be a Pathway.
- **Knowledge base**: facts too numerous for the instructions — full pricing tables, FAQs, policy documents. The agent retrieves them when asked.

## The improvement loop

Never edit instructions on a hunch. Read the failed test transcript (`get_test_run`), find the exact turn where the conversation degraded, and change the one section that governs that turn. One change, re-run, compare scores. Bundled edits make scores move without telling you which edit did it.