Writing Instructions That Work

Why Instructions Are The Most Important Thing You Write

Instructions are the single most important part of agent configuration. The model is doing what you told it to do — if it is doing the wrong thing, the instructions are almost always the culprit. Below are the patterns that consistently produce reliable agents, and the anti-patterns that quietly break them.

A useful frame: think of instructions as a job description for someone joining the team on day one. They have not seen your codebase, your customer history, your team's tone — everything they need to do their job has to be in writing.

Lead With Identity, Not Tasks

Open with one or two sentences that establish who the agent is and what it cares about, before listing what it does.

Weak opening:

"You handle support tickets."

Strong opening:

"You are a Tier 1 support agent for Acme Corp. You care about resolving customer issues quickly while keeping the team's tone consistent. You work closely with the human support team and escalate anything you are unsure about."

Identity shapes every downstream decision. The model carries that framing into how it chooses tools, how it phrases replies, when it escalates. "Tier 1 support agent" produces meaningfully different behavior than just "you handle tickets."

Use Numbered Steps For Workflows

If the agent should follow a process, number it. Models follow numbered lists more reliably than prose — the numbers create explicit sequencing, and the agent treats each step as a checkpoint rather than a suggestion.

"When a new ticket arrives:
1. Read the ticket and any prior conversation using zendesk_get_ticket.
2. Look up the customer's order history with shopify_search_orders.
3. Draft a reply addressing their issue.
4. If the issue requires escalation, tag the ticket as needs-escalation and add an internal note.
5. Otherwise, post the reply via zendesk_add_public_reply."

This is far more reliable than the same workflow written as a paragraph. The model treats step 4 as a real branch instead of a hint.

Reference Tools By Their Exact Name

Mention tools by their actual identifier — zendesk_get_ticket, zendesk_add_internal_note, shopify_search_orders. The model uses these names to map your instruction to its available toolset. Vague phrasing like "look up the order" without naming the tool leads to skipped or wrong tool calls.

If you have multi-instance connectors (e.g., two Zendesk accounts), the tool names get suffixed automatically (zendesk_get_ticket__production). Be explicit about which instance the agent should use, especially in routing scenarios.

Set Boundaries Explicitly

Tell the agent what not to do as clearly as you tell it what to do. Negative rules prevent the most common failure modes.

• "Never promise a refund without confirmation from the billing team."
• "Do not paste internal notes into public replies."
• "If a customer asks about pricing, point them to the website rather than quoting a figure."
• "Never close a ticket. Mark it solved if the issue is resolved — closed tickets cannot be reopened or updated."
• "Do not respond to customers in a language other than the one they wrote in."

The cost of writing five negative rules is low. The cost of an agent confidently doing the wrong thing because the rule was implicit is high.

Describe Edge Cases And Escape Hatches

Spell out what to do when things are ambiguous. Without an escape hatch, the agent will improvise — and improvisation is where things go wrong.

"If the ticket is in a language you do not understand, add an internal note tagging the multilingual team and stop."

"If the customer's account cannot be found, do not reply. Add an internal note saying 'customer not found in CRM — needs human follow-up' and stop."

"If the ticket conversation suggests the customer is in distress (mentions of crisis, self-harm, or urgent emergency), do not reply. Add an internal note flagging the ticket for the on-call human."

Each escape hatch is one fewer place the agent can go badly wrong. Agents that say "I do not know" or "this needs a human" are nearly always preferable to agents that confabulate.

Define The Persona

Set the tone and style explicitly. Should the agent be formal or casual? Brief or detailed? Cite policy or paraphrase it?

"Respond in a friendly, professional tone. Keep replies concise — no more than 2-3 paragraphs unless the customer's question requires a detailed explanation. Address the customer by their first name if it appears in the ticket. Sign off as 'The Acme Support Team' rather than using a personal name."

Tone consistency is one of the things customers notice when an AI starts replying — sudden shifts in formality or voice are jarring. Bake the tone into the instructions so every reply has the same character.

A Full Example

Here is what a complete, well-formed instruction set looks like for a customer reply agent in Zendesk. Note how identity, persona, workflow, tools, boundaries, and escape hatches all fit together.

You are a Tier 1 customer support agent for Acme Corp, a B2B SaaS company. You handle incoming Zendesk tickets where customers ask about product usage, billing, or general account questions. You work alongside the human support team — your job is to draft accurate, helpful, on-brand replies, not to replace human judgment on hard cases.

Tone and style: Friendly and professional. Concise — 2-3 paragraphs unless a detailed explanation is genuinely required. Address the customer by first name if it appears in the ticket. Sign off as "The Acme Support Team."

Workflow for every ticket:
1. Read the full ticket conversation with zendesk_get_ticket.
2. Search the help centre with zendesk_search_articles for any article relevant to the question.
3. If the customer mentioned an order, look it up with shopify_search_orders.
4. Draft a reply that directly addresses the customer's question, citing help centre articles where relevant.
5. Post the reply with zendesk_add_public_reply.

Boundaries:
- Never promise a refund. Refunds require human approval — escalate by tagging needs-billing-review and adding an internal note.
- Never quote pricing. Refer customers to acme.com/pricing.
- Never close tickets. Mark them solved when the issue is resolved.
- Do not paste internal notes into public replies.

Escape hatches:
- If the ticket is in a language other than English, add an internal note tagging the multilingual team and stop.
- If the customer's question cannot be answered from the help centre, add an internal note saying "no relevant article found — needs human" and stop.
- If the customer is reporting a critical bug or security issue, do not reply. Tag urgent-engineering and add an internal note.

Anti-Patterns To Avoid

• Wishful instructions. "Be helpful and accurate." The model already wants to be helpful and accurate. Tell it how.
• Missing tool references. Listing tools in the agent config but not mentioning them in instructions. The model has access to the tool but does not know when to reach for it.
• Conflicting rules. "Always reply within one minute" and "Always check three sources before replying." Pick one and prioritise it explicitly.
• Open-ended scope. "Help with anything related to support." This becomes a generalist agent by default. Narrow it.
• Implicit assumptions. "Use the right tone." What is the right tone? Spell it out.
• Examples without rules. Showing the agent two example replies is helpful, but does not generalise. Pair examples with the underlying rules they illustrate.

Length: Detailed Beats Concise

A common worry is that long instructions waste tokens or confuse the model. In practice, the opposite tends to be true. Detailed instructions reduce variance and stop the agent improvising into trouble. We routinely see production agents with 500-800 word instruction sets perform better than the same agent with a tight one-paragraph version.

The token cost of long instructions is real but small — usually under 1% of the per-conversation cost on a tool-using agent. The cost of an agent making a wrong decision because the rule was implicit is much larger. Default to writing more, not less.