Skip to main content

Writing good instructions

Power user & admin

Good instructions are the single biggest lever you have on agent quality. Write them like a job description for a brand-new hire.

Prerequisites​

  • An agent draft open at step 1, Instructions, of the creator.
  • A clear idea of who'll use the agent and what they'll ask.

The role + task + format pattern​

Strong instructions usually follow the same three-part shape. Cover each part explicitly:

  1. Role. Who is the agent? What's its expertise and tone?

    Example: "You are a procurement specialist for Acme. You answer questions about purchase orders, vendor onboarding, and supplier risk."

  2. Task. What is it expected to do? Be explicit about what's in scope and what isn't.

    Example: "When asked about a PO, look it up in the Procurement knowledge base and summarise status, amount, vendor, and approver. If the user asks about anything unrelated (HR, finance, IT), politely redirect them to the right agent."

  3. Format. How should the response look? Markdown? A list? A specific structure?

    Example: "Always reply in markdown. For PO lookups, use a bullet list with Status, Amount, Vendor, Approver. Cite every fact with the source document."

Use the rich-text formatting​

The instructions box accepts markdown: **bold**, *italic*, # heading, and - list. Use headings to separate sections of the prompt (Role, Examples, Rules) so the LLM can pick them up clearly.

The Improve button​

Once you've roughed out the instructions, click Improve in the top-right of the editor (it's greyed out until you've typed something). Ask rewrites your draft in place with cleaner structure and tighter wording. Expect a 15–25 second spinner. There's no accept/reject prompt: if you prefer your original, click the undo arrow next to the button.

Treat Improve as a copy-editor, not an author. Always re-read the result: it can over-formalize or drop a constraint you cared about.

Rules that consistently help​

  • Spell out refusals. Tell the agent what to do when a question is out of scope, not just what's in scope.
  • Show, don't tell. One or two worked examples beat a long abstract rule.
  • Pin down format. If you want bullet lists, ask for bullet lists. If you want citations, demand citations.
  • Constrain the source. If a knowledge base is attached, say "Only answer from the attached knowledge base. If unsure, say so."
  • Match the tone. "Formal", "casual", "friendly but precise": the LLM follows tone cues well.

Anti-patterns to avoid​

  • Walls of text. Long, unstructured instructions get partially ignored. Use headings.
  • Vague verbs. "Help users" tells the agent nothing. "Look up POs and summarise status" does.
  • Conflicting rules. "Be concise but always show your reasoning" pulls in two directions.
  • Hidden assumptions. If only finance users will chat with this agent, say so explicitly.

Iterate with Test​

Click Test in the top toolbar after every change. Ask the agent the questions it'll actually be asked, including the awkward ones. When the answers drift, the fix is almost always in the instructions, not the model.

Tips & gotchas​

tip

Keep instructions under ~500 words for routine agents. Long prompts cost more tokens per turn and are harder to maintain, so split the agent if scope is creeping.

note

Instructions are versioned with the rest of the agent. You can roll back if a rewrite hurts answers. See Versioning & drafts.

AgentsCreate your first agentFull walkthrough of the three-tab creator.AgentsPick a modelDifferent models follow instructions differently, so pick deliberately.AgentsGuardrailsBelt and braces for the rules you can't afford to break.