How to Brief an AI Agent Like a Colleague: Writing Effective Agent Instructions
In one sentence: The best agent instructions read like a brief to a capable new colleague: a clear role and goal, the context they need, firm boundaries, rules for using tools, a path for escalation and a definition of d
In one sentence: The best agent instructions read like a brief to a capable new colleague: a clear role and goal, the context they need, firm boundaries, rules for using tools, a path for escalation and a definition of done.
Ask a dozen teams what separates a good AI agent from a frustrating one and many will say the model. Look closely at their instructions and a different picture emerges. Vague wording, missing context and unstated boundaries cause far more disappointment than any limitation of the technology. This post shows how to write instructions that work. We use the STAR format (Situation, Task, Action, Result) to move from a familiar problem to a repeatable method.
The Instruction That Said Everything and Nothing
Meet a property manager weβll call Summit Property Services. As in our earlier posts, this is a composite scenario, not a customer case, but the pattern will be recognizable.
Summit looks after thousands of rental homes. Tenants report problems by email and chat: leaks, broken heaters, noisy neighbors, lost keys. The company builds an agent to triage these requests and a well-meaning manager writes its instructions in one sentence: βYou are a helpful maintenance assistant. Be professional, handle tenant requests and use your judgment.β
In testing, the agent seems fine. In the first week of live use, a pattern of small disasters appears. A tenant writes at two in the morning that the heating has failed and there is a baby in the flat. The agent replies politely and books a routine visit for the following Tuesday. Another tenant asks for a rent refund because of the broken heating and the agent, trying to be helpful, says it will arrange one. A third asks about a leak and the agent asks for the address, which the system already holds.
Nothing here is a failure of intelligence. The agent did exactly what a smart but entirely uninformed new hire would do on day one, if that hire had been given the same single sentence. Nobody told it what βurgentβ means at Summit. Nobody told it that refunds are not its decision. Nobody told it which system holds the tenantβs details. Its judgment was fine; its information was missing.
This is the heart of the matter. We tend to imagine instructions as magic words that unlock good behavior. In practice, they are a brief and a brief is only as good as what it tells the reader. Figure 1 contrasts vague and effective instructions across the dimensions that matter.
Figure 1. Vague vs. effective instructions
Pause and check: Read the instructions of an agent you use or are building. Imagine handing them to a capable stranger on their first day. What would that person need to ask before they could do the job safely?
Write the Brief a Colleague Would Want
Your task is to write instructions that give an agent what a skilled new colleague would need, no more and no less. The analogy is practical, not sentimental. When you brief a person well, you explain the purpose, share the background, state the limits and say when to ask for help. You do not recite every possible situation and you do not leave them to guess. The same applies to an agent.
Three principles keep this grounded:
β’ Be specific about what matters. Define the terms your organization uses, name the systems that hold the truth and describe what βdoneβ looks like.
β’ Separate guidance from control. Instructions guide behavior. Limits that must never be crossed, such as spending caps and permissions, belong in tools and platform rules, not only in words.
β’ Treat the brief as a living document. It will change as you learn, so it should be versioned and tested like any other part of the system.
For Summit, the task becomes concrete: rewrite the one-sentence instruction as a complete brief, move hard limits into the tools and test the new version against the disasters it caused.
Anatomy of a Good Brief
Effective briefs share a recognizable structure. Figure 2 shows the seven parts, which you can adapt to almost any agent.
Figure 2. The seven parts of an agent brief
+-------------------------------------------------------------+
| 1. ROLE AND GOAL Who you are and the outcome you own |
| 2. CONTEXT Terms, audience and where facts live |
| 3. BOUNDARIES What you must never do |
| 4. TOOLS When and how to use each one |
| 5. ESCALATION When to hand over to a person |
| 6. STYLE AND OUTPUT Tone, length and the shape of replies |
| 7. DONE MEANS What a finished case looks like |
+-------------------------------------------------------------+
Optional: 2-3 worked examples of good behavior
- Role and goal. Begin with who the agent is and what outcome it owns. βYou are the maintenance-coordination agent for Summit Property Servicesβ is better than βhelpful assistant,β and a goal such as βget every request safely triaged, logged and scheduled, or handed to a person with a clear case noteβ gives every later decision a purpose.
- Context. Supply what the agent cannot guess. Who is writing in and in what state of mind? What does βurgentβ mean in your business? Which system is the source of truth? Context is where most weak briefs are thinnest and where the biggest gains are found.
- Boundaries. State plainly what the agent must never do: promise refunds, give legal advice, share one customerβs details with another. Short, concrete prohibitions are easy to follow and easy to test.
- Tools. Explain when to use each tool and in what order. βCheck the tenant record before asking the tenant for details you already holdβ prevents a whole class of irritating behavior. Where possible, expose tools through governed standards such as the Model Context Protocol (MCP), so that access rules are enforced outside the prompt.
- Escalation. Replace βuse your judgmentβ with named situations: an injury, a child or vulnerable person at risk, a threat, a tool failure on an urgent case, or a tenant asking for a manager. Agents behave well when they know exactly when to stop.
- Style and output. Describe tone, length and structure. βPlain language, under 120 words, warm and direct, ending with what happens next and whenβ produces consistent replies and makes outputs easier to review.
- Done means. Define completion. A case is done when a work order exists, the tenant knows the next step and urgent matters are with a person. Without this, agents either stop too early or keep going. Two or three short worked examples, including one where the right answer is to escalate, teach tone and judgment faster than extra paragraphs.
The brief in practice
Now the technical part. The first snippet is Summitβs rewritten brief, stored as a plain text file so that it can be versioned, reviewed and compared. It is an illustrative example, not a template to copy blindly.
Figure 3a. Summitβs maintenance-coordination brief
Role and goal
You are the maintenance-coordination agent for Summit Property Services.
Your goal: get each tenant request safely triaged, logged and scheduled,
or handed to a person with a clear case note.
Context
- Tenants write by email and chat. Many are stressed and not technical.
- Urgent means: no heat in cold weather, gas smell, flooding, no water, or a failed security lock.
- The work-order system is the source of truth for tenants and units.
Boundaries (never do these)
- Never promise refunds, rent reductions or compensation.
- Never give legal advice or diagnose gas or electrical faults.
- Never share one tenantβs details with another.
Tools
- Use get_tenant before asking for details we already hold.
- Use create_work_order for every request; set priority from the urgent list.
- Use notify_oncall for urgent cases only.
Escalate to a person when
- A request is urgent and notify_oncall fails.
- Anyone mentions injury, a child or elderly person at risk, or a threat.
- You are unsure, or the tenant asks for a manager.
Style and output
- Plain language, under 120 words, warm and direct.
- End with what happens next and when.
Done means
A work order exists, the tenant knows the next step and urgent cases
are with a person.
Notice what the brief does not contain. It does not try to list every possible maintenance problem and it does not repeat the full repair policy. Reference material such as policies and repair guides belongs in a knowledge base that the agent searches, so the brief stays short enough to read in one sitting. A long brief is usually a sign that knowledge has been stuffed into the wrong place.
The second snippet is a simple linter. It cannot judge quality, but it catches common omissions and vague phrases before a version ever reaches testing.
Figure 3b. A basic brief linter
REQUIRED = ["role and goal", "context", "boundaries", "tools",
"escalate", "style", "done means"]
VAGUE = ["be helpful", "use your judgment", "as appropriate",
"if necessary", "try to", "etc."]
def lint_brief(text: str) -> list[str]:
problems, lowered = [], text.lower()
for section in REQUIRED:
if section not in lowered:
problems.append(f"Missing section: {section}")
for phrase in VAGUE:
if phrase in lowered:
problems.append(f"Vague wording: '{phrase}'")
if len(text.split()) > 700:
problems.append("Long brief: move reference material to the knowledge base")
return problems
The third snippet is the most important. It tests the instructions against the very situations that caused trouble, so every revision is checked against what went wrong before.
Figure 3c. Regression tests for an instruction version
CASES = [
{"input": "No heating, 2am, my baby is cold",
"expect_tool": "notify_oncall", "expect_priority": "urgent"},
{"input": "Can I get a rent refund for last week?",
"must_not_say": ["we will refund", "you will receive a refund"],
"expect_escalation": True},
{"input": "Tap is dripping in the kitchen",
"expect_tool": "create_work_order", "expect_priority": "routine"},
]
def test_brief(agent) -> list[str]:
failures = []
for case in CASES:
run = agent.run(case["input"])
if "expect_tool" in case and case["expect_tool"] not in run.tools_used:
failures.append(f"{case['input']}: expected {case['expect_tool']}")
for phrase in case.get("must_not_say", []):
if phrase in run.reply.lower():
failures.append(f"{case['input']}: said '{phrase}'")
return failures
Three habits make this work. The brief lives in a file, so every change is visible and reversible. Tests turn complaints into permanent checks. And hard limits, such as the prohibition on refunds, should also be enforced where the agent cannot talk its way around them, for instance by giving it no refund tool at all. Instructions guide; tools and platform rules constrain.
When a brief underperforms, the cause usually falls into one of a few categories. Figure 4 pairs the common wording mistakes with a stronger rewrite.
Figure 4. Common mistakes and better rewrites
A further question is where each kind of instruction should live. Not everything belongs in the brief. Figure 5 sorts the common types of guidance into the places where they work best.
Figure 5. Where each kind of guidance belongs
What Good Looks Like
As in our previous posts, we will not promise a particular improvement. Results depend on your starting instructions, your processes and your data, so keep a baseline and add your own verified figures before presenting a business case.
What does change is the character of the agentβs behavior. For Summit, the heating failure at two in the morning now triggers the on-call notification and a human hand-off. The refund request is acknowledged and passed to a person, with no promise made. The leak report no longer asks for an address the system already holds. When something goes wrong, the team does not argue about whether the agent was βsmart enough.β They look at the brief, add a test and release a better version.
Figure 6. A scorecard for agent instructions
Three pitfalls to avoid
β’ Writing longer instead of clearer. Piling on rules produces contradictions. Prefer a short, well-structured brief supported by a knowledge base.
β’ Relying on instructions for safety. A prohibition in the prompt is a request. A missing tool or a platform rule is a guarantee.
β’ Never revisiting the brief. Instructions drift out of date as policies and products change. Review them on a schedule and after every incident.
Figure 7. STAR recap
Where should you start?
Pick one agent and find the three worst things it has done. Write each as a test case, then rewrite the brief using the seven parts, paying special attention to context, boundaries and escalation. Run the tests, fix what fails and store the brief in version control. You will probably find that most of the improvement comes from the first hour of this exercise.
The quality of an agentβs work is a reflection of the quality of its brief. Treat instructions the way you would treat onboarding for a valued colleague: explain the purpose, share the background, set the limits and say when to ask for help. Do that well and the agentβs intelligence has something worth working with.
Visit www.intellibooks.io.
Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.




