Writing Effective Agent Instructions (the Macha Way)

The good news is that writing instructions is a learnable skill, not a dark art. In Macha, an agent is four things working together — instructions, a model, tools, and knowledge — and the instructions are the part you control with plain English. This guide is the practical version of what we tell teams building their first agents: a repeatable template, the handful of principles that move the needle, and an honest list of the mistakes that make agents misbehave. It's grounded in how Macha actually works and in Anthropic's "Building Effective Agents", whose core advice — keep it simple, make the agent transparent, and treat the agent's interface with real care — runs underneath everything below.

What "instructions" actually do

In Macha, the instructions field is the agent's standing brief — its system prompt, policy manual, and job description in one box. It's the text the model reads on every single conversation before it sees the customer's message. Everything else hangs off it: the instructions decide when to reach for a tool, which knowledge matters, and how to talk.

It helps to be clear about what instructions are not. They are not where facts live — your return policy, SKU list, or shipping timelines belong in a knowledge source, not pasted into the prompt where they'll go stale. They are not code — you describe intent and let the model reason. And they are not a place to cram five jobs into one agent. Hold those three ideas and you're already ahead of most first drafts.

A 7-part template for agent instructions

Almost every strong instruction set we've seen — and the public guides from OpenAI, Microsoft, and Dust converge on roughly the same shape — covers seven things. Use this as a skeleton and delete what you don't need:

1. Role & scope — who the agent is and the one job it owns. "You are a shipping-and-delivery support agent for an apparel store. You handle order-status, tracking, and delivery-exception questions."
2. Audience & tone — who it's talking to and how. "Customers, often anxious about a late order. Be warm, concise, and concrete. No corporate filler."
3. The decision it owns — and the line it won't cross. "You may look up orders and share tracking. You may not issue refunds or change addresses."
4. Tool-use policy — when to call which tool, and which actions need confirmation. "Always call get_order before answering a status question. Never guess a tracking number."
5. Escalation / handoff rules — the exact conditions for handing to a human. "If the order shows delivered but the customer says it's missing, escalate to the human queue with a one-line summary."
6. Output format — length, structure, and any contract the UI expects. "Reply in 2–4 sentences. Lead with the answer, then the detail."
7. Examples — one or two short before/after exchanges that show the behavior you want.

You don't need a heading for each. A tidy paragraph per idea, in roughly this order, reads cleanly to the model and to the teammate who edits it next month.

Principle 1: Keep it short, and give it one job

The single most common failure mode is an instruction set that tries to do everything. Industry guides land on a useful rule of thumb: effective instructions run roughly 200–500 words, and if you're past ~1,000 words, you probably have several agents, not one. Anthropic's framing is blunter — "Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs." Start simple; add complexity only when you can measure that it helped.

When a single agent genuinely needs to span domains — billing and shipping and technical — don't write a 2,000-word mega-prompt. Split the work into sub-agents: a router agent with a tight brief that delegates to focused specialists, each with its own short instruction set.

This mirrors Anthropic's orchestrator-workers pattern, and it keeps each instruction set readable. A short prompt that does one thing well beats a sprawling one that does five things adequately — every time. (More on the mechanics in the sub-agents docs.)

Principle 2: Write positively, and remove ambiguity

Tell the agent what to do, not just what to avoid. "Always confirm the order number before looking it up" adheres far better than "Don't look things up without the order number." Negative-only rules leave the model guessing at the positive behavior you actually want.

Then hunt down ambiguity. If a phrase isn't crisp to you, it won't be crisp to the model. "Be helpful" means nothing; "answer the question first, then offer one relevant next step" means something. A good test from the prompt-engineering community: run the same input five times. If the answers vary wildly, your instructions are too loose — tighten the language until the behavior stabilizes.

Principle 3: Tell it when — and how — to use its tools

Tools are where a support agent stops being a chatbot and starts resolving things. In Macha you assign tools from connected systems — Shopify, Stripe, Zendesk, and others — plus any custom API tools you build.

Assigning a tool isn't enough; the instructions have to govern it. Anthropic makes the point that the agent-computer interface deserves the same care as a human one — "Think of this as writing a great docstring for a junior developer on your team." In practice that means three things in your prompt:

• When to call it. "For any 'where is my order' question, call get_order first — don't answer from memory."
• What not to do. "Never invent a tracking number. If the lookup fails, say so and offer to escalate."
• What needs confirmation. Write actions (refunds, address changes, cancellations) should ask before they fire. Macha surfaces tool calls and lets you gate writes behind confirmation — your instructions should reinforce that: "Before issuing any refund, state the amount and ask the customer to confirm."

A small touch that pays off: give tools and their parameters clear, hard-to-misuse names. Anthropic calls this poka-yoke — designing the interface so mistakes are difficult in the first place.

Principle 4: Point to knowledge — don't paste it

It's tempting to dump your return policy and FAQ straight into the instructions. Resist it. Facts change; instructions written around stale facts rot silently. Instead, connect the information as a data source — uploaded docs, a crawled help center, or a live Notion/Confluence/Google Docs connection — and let the agent retrieve it.

Your instructions then point at that knowledge rather than duplicating it: "Use the connected Help Center for policy questions. If the answer isn't in the knowledge, say you'll check with the team rather than guessing." That last clause matters — explicitly telling the agent to admit uncertainty is one of the highest-leverage lines you can write against hallucination.

Principle 5: Show, don't tell — use examples

Across every guide we reviewed, the same lever keeps coming up as the most effective single improvement: examples. One or two short before/after exchanges teach tone, structure, and edge-case handling faster than a paragraph of adjectives. Include:

• A happy-path example (the common question, answered well).
• An edge-case example (the lookup fails, or the request is out of scope) showing exactly how you want the agent to bow out or escalate.

Keep them short and realistic. The model pattern-matches on them, so a single crisp example of "I can't see that order on my side — let me hand you to a teammate who can dig deeper" does more than three sentences telling the agent to "be graceful when things fail."

Let the AI builder write your first draft

You don't have to start from a blank box. Macha's AI Agent Builder turns a plain-English description into a working agent — instructions, suggested tools, and model — that you then refine.

Describe the job the way you'd brief a new hire, and the builder drafts the configuration for you:

Treat the output as a first draft, not a final answer. It gets you to 80% — the role, the broad strokes, a sensible toolset — and then you apply the principles above: tighten the tool policy, add your escalation line, drop in an example or two. Editing a good draft is far faster than writing from scratch, and you still end up with instructions you understand and own.

Test before you ship — and evaluate after

Anthropic is emphatic that agents need testing in a safe environment, human checkpoints, and stopping conditions. Macha gives you two layers for this.

Before you ship, run the agent in the test panel. Watch the tool calls fire in real time, confirm it reaches for the right tool at the right moment, and throw the awkward cases at it — the missing order, the out-of-scope refund, the angry opener.

After it's live, use Agent Evaluation. An AI judge runs a checklist over your real chats, trigger runs, and sub-agent handoffs and returns a percentage-followed score with a one-line reason per conversation. That's your feedback loop: when the judge flags a recurring miss, you've found the exact instruction to sharpen. Update instructions when the agent repeatedly fails a task, or when your tools, knowledge, or workflow change — not on a vibe.

A worked example: an annotated WISMO agent

Here's a compact instruction set for a "where is my order" agent, with the seven parts called out. Notice it's well under 300 words and never pastes a single shipping policy — it points at knowledge and tools instead.

You are a shipping & delivery agent for an apparel store. (role & scope) You handle order-status, tracking, and delivery-exception questions for customers — who are often worried about a late order, so be warm, concise, and concrete. (audience & tone) You may look up orders and share tracking details. You may not issue refunds or change shipping addresses — those go to a human. (the line it won't cross) For any order question, always call get_order first using the order number; if you don't have it, ask for it. Never invent a tracking number — if the lookup fails, say so plainly. (tool-use policy) For policy questions (delivery windows, lost-package handling), use the connected Help Center knowledge. If the answer isn't there, tell the customer you'll check with the team rather than guessing. (knowledge + anti-hallucination) If an order shows delivered but the customer says it never arrived, escalate to the human queue with a one-line summary. (escalation) Reply in 2–4 sentences: lead with the answer, then the detail. (output format) Example — Customer: "Where's my order?!" → "I've got it — order #1043 shipped Tuesday and is out for delivery today, arriving by 8pm. Here's your tracking: [link]. Anything else I can check?" (example)

That's the whole shape: short, positive, tool-aware, knowledge-backed, and honest about its limits.

Watch-outs: when good intentions backfire

A few honest failure modes worth naming:

• Over-instructing. A 1,500-word prompt doesn't make a smarter agent; it makes a confused one. If yours is ballooning, that's the signal to split into sub-agents.
• Hard-coding facts. Anything that changes — prices, policies, hours, inventory — belongs in knowledge, not the prompt. Pasted facts go stale and nobody notices until a customer does.
• Over-constraining. Pile on too many "never do X" rules and the agent gets timid, refusing reasonable requests. Frame positively and trust the model with the easy cases.
• Instructions can't fix a missing tool. No amount of prompting lets an agent look up an order it has no connector for. If the behavior needs an action, the fix is a tool or connector, not another sentence.
• Writing once and walking away. Instructions are living documents. The teams whose agents quietly degrade are the ones who never look at the evaluation scores.

FAQ

How long should agent instructions be? Aim for ~200–500 words. If you're pushing past 1,000, you almost certainly have multiple jobs that should be separate sub-agents, each with its own short brief.

Should I write instructions from scratch? No need — use Macha's AI Agent Builder to generate a first draft from a plain-English description, then refine the tool policy, escalation rules, and examples yourself.

Where do facts like my return policy go — in the instructions or knowledge? Knowledge. Connect them as a data source and have the instructions point at that knowledge. Facts in the prompt go stale silently.

How do I stop an agent from making things up? Two layers: connect real knowledge and tools so it has the facts, and write an explicit line telling it to admit uncertainty and escalate rather than guess.

How do I know my instructions are working? Test in the panel before launch (watch the tool calls), then use Agent Evaluation after launch — an AI judge scores real conversations and flags the recurring misses worth fixing.

Does running and testing agents cost anything? Macha is credit-based, where credits are spent per AI action (roughly 0.5–9 by model, with the default model at 1 per action). See the pricing page for current plans.

Start writing better instructions

The fastest way to get good at this is to ship one focused agent and read its evaluation scores. Start a 7-day free trial, no credit card required, describe your first agent to the builder, then sharpen its instructions with the seven-part template above. If you're on Zendesk, the Macha on Zendesk page shows where these agents plug into your existing workflow — and the docs walk through every field in depth.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.