The Agent's Instruction Manual
James pulled up the OpenClaw dashboard and scrolled through the last five messages he had sent from WhatsApp. The agent had responded to all of them. Nine tools, working, tested. But the dashboard logs told a different story.
For "Teach me about variables," the agent had called get_chapter_content first, then get_learner_state. For "How am I doing?" it called generate_guidance instead of get_learner_state. For "I want to practice loops," it went straight to get_exercises without checking what chapter the learner was on.
"It picks the right tools most of the time," James said. "But the order is wrong. It does not follow a teaching flow."
Emma looked at the logs. "It has nine tools and no instructions. You gave it tools but never told it how to run a tutoring session." She pointed at his project directory. "Write the manual."
"What manual?"
"AGENTS.md. The instruction document that the agent reads before every conversation. Right now the agent knows what each tool does, because the tool descriptions tell it that. But it does not know the workflow: which tool comes first, what depends on what, when to teach versus when to test. AGENTS.md is the workflow."
You are doing exactly what James is doing. Your agent has nine working tools and no protocol for using them. AGENTS.md is the protocol.
In Lesson 8, you connected TutorClaw to OpenClaw and tested the full flow from WhatsApp. The tools worked individually. But the agent picked tools based on its best guess, not based on a tutoring methodology. This lesson changes that. You write AGENTS.md, place it in your project, and test until the agent follows your protocol.
What AGENTS.md Does
AGENTS.md is a plain text file that the agent reads before every conversation. It contains natural language instructions that shape how the agent behaves: what to do first, which tools to call in which situations, and what order to follow.
It is not code. There are no functions, no conditionals, no special syntax. You write instructions the way you would write a manual for a new employee on their first day.
| Without AGENTS.md | With AGENTS.md |
|---|---|
| Agent guesses which tool to call first | Agent follows the session start protocol |
| Tool order varies by message | Tool order follows the tutoring flow |
| "Help me learn" might skip get_learner_state | "Help me learn" always starts with get_learner_state |
| Agent uses tools but has no teaching methodology | Agent follows PRIMM stages in sequence |
Think of it this way. The tool descriptions are job titles: "register_learner registers new learners." AGENTS.md is the employee handbook: "On every new shift, check the roster first. Then check the day's assignments. Then start working."
Before You Write: Observe the Problem
Send these two messages from WhatsApp and watch the dashboard:
Message 1: "Help me learn"
Message 2: "I want to practice"
Note which tools the agent calls and in what order. You will send the same messages after writing AGENTS.md to see the difference.
Draft AGENTS.md
Create a new file in your TutorClaw project root called AGENTS.md. You can write it by hand or ask Claude Code to help you structure it. Either way, you are the author: you decide what goes in the manual.
Your AGENTS.md needs three sections: session start protocol, tutoring flow, and tool selection rules.
Section 1: Session Start Protocol
Every tutoring session must begin the same way. The agent needs to know who the learner is and where they are in the curriculum before it can teach, test, or advise.
Write instructions like this (adapt to your own words):
## Session Start
When a learner sends the first message of a conversation:
1. Call get_learner_state with the learner's ID
2. If the learner does not exist yet, call register_learner first,
then call get_learner_state
3. Read the learner's current chapter, PRIMM stage, confidence score,
and exchanges remaining
4. Use this state to guide every subsequent tool call in the session
The key rule: the agent must never call get_chapter_content, generate_guidance, get_exercises, or any teaching tool before it knows the learner's current state. Without state, the agent cannot pick the right chapter, the right PRIMM stage, or the right difficulty level.
Section 2: Tutoring Flow
Once the agent has the learner's state, it follows the PRIMM-Lite tutoring methodology. Write the flow as a sequence:
## Tutoring Flow
After retrieving learner state, follow this sequence:
1. Call get_chapter_content for the learner's current chapter
2. Call generate_guidance for the learner's current PRIMM stage
3. Present the guidance to the learner and wait for their response
4. Call assess_response with the learner's answer
5. Call update_progress to record the interaction
6. If the learner's confidence is high and the stage is complete,
advance to the next stage or chapter
7. If the learner's confidence is low, call get_exercises for
targeted practice before advancing
This sequence is not rigid. The learner might ask a question that breaks the flow. The agent should handle that and return to the sequence. But the default path is: content, guidance, response, assessment, progress. That is the teaching loop.
Section 3: Tool Selection Rules
Ambiguous messages are where AGENTS.md matters most. A learner who says "help me" could mean many things. Write explicit rules for the most common cases:
## Tool Selection Rules
- "Help me learn" or "teach me" or "start learning":
Follow the tutoring flow from step 1 (get_chapter_content)
- "I want to practice" or "give me exercises":
Call get_exercises, not get_chapter_content. The learner wants
practice, not new material.
- "Run my code" or "test this":
Call submit_code. Do not call assess_response for code submissions.
submit_code handles execution; assess_response handles conceptual
answers.
- "How do I upgrade?" or "I hit a limit":
Call get_upgrade_url if the learner is on the free tier.
If the learner is already on the paid tier, explain that they
have full access and do not need to upgrade.
- "Where am I?" or "what is my progress?":
Call get_learner_state and present the results. Do not call
generate_guidance or get_chapter_content.
These rules handle the cases where tool descriptions alone are not enough. The tool description for get_exercises says "return exercises matched to weak areas," but without the rule above, the agent might call get_chapter_content when the learner says "I want to practice" because both tools relate to learning content.
Section 4: Error Handling Protocol
Tools fail. The agent needs to know what to do when they do. Add a fourth section:
## When Tools Return Errors
- If get_learner_state returns "learner not found":
Call register_learner to create the account first, then retry
get_learner_state.
- If get_chapter_content returns a tier error:
Tell the learner which chapters are available on their tier.
Offer to call get_upgrade_url for a paid plan link.
- If any tool times out or returns an unexpected error:
Acknowledge the problem to the learner. Do not guess at the
answer. Say: "I had trouble reaching that information. Let me
try again." Then retry once. If it fails again, suggest the
learner try later.
- If submit_code returns a timeout:
Tell the learner their code took too long to run. Suggest they
check for infinite loops or reduce the input size.
Without error handling instructions, the agent either ignores errors silently or generates a vague apology. These rules give it specific recovery actions for each failure mode.
Place AGENTS.md
Save the file in your TutorClaw project root. The exact location matters: the agent reads AGENTS.md from the project directory when the MCP server is connected.
Ask Claude Code to confirm the file is in the right place:
Is AGENTS.md in the project root of my tutorclaw-mcp project?
List the files in the project root.
Test the Protocol
Send the same two messages you sent before writing AGENTS.md.
Test 1: "Help me learn"
Watch the dashboard. The expected tool call order:
- get_learner_state (session start protocol)
- get_chapter_content (tutoring flow step 1)
- generate_guidance (tutoring flow step 2)
If the agent calls get_chapter_content before get_learner_state, your session start protocol needs to be more explicit. Add emphasis:
IMPORTANT: Always call get_learner_state FIRST in every session.
No other tool should be called before the agent knows who the
learner is and what chapter they are on.
Test 2: "I want to practice"
Expected tool call order:
- get_learner_state (session start protocol)
- get_exercises (tool selection rule for practice requests)
If the agent calls get_chapter_content instead of get_exercises, your tool selection rules need refinement. Make the distinction sharper:
When the learner asks to practice, exercise, or drill:
Call get_exercises. Do NOT call get_chapter_content.
Content is for learning new material.
Exercises are for practicing known material.
Test 3: Free-form
Send a message that is not covered by your rules. Something like "I am confused about chapter 3." Watch what the agent does. If the behavior seems wrong, add a new rule to AGENTS.md and test again.
The Refinement Cycle
AGENTS.md is never finished on the first draft. You write it, test it, observe where the agent deviates, and refine. This is the same iterative pattern as tool descriptions: the first version is a guess, testing reveals the gaps, and each revision makes the agent more predictable.
Common refinements after initial testing:
| Observation | Refinement |
|---|---|
| Agent skips get_learner_state on some messages | Add "ALWAYS" or "FIRST" in caps to the session start section |
| Agent calls get_chapter_content for practice requests | Add an explicit "Do NOT" rule distinguishing content from exercises |
| Agent calls generate_guidance without content loaded | Add a dependency note: "generate_guidance requires chapter content to be loaded first" |
| Agent calls get_upgrade_url for paid learners | Add a tier check: "Only call get_upgrade_url if the learner is on the free tier" |
Each refinement is a single sentence or short paragraph added to AGENTS.md. You are not writing code. You are writing clearer instructions.
Try With AI
Exercise 1: Add Error Handling Rules
Your AGENTS.md handles the happy path. What happens when something goes wrong?
Add an error handling section to my AGENTS.md. Cover three cases:
1. What should the agent do when a tool returns an error?
2. What should the agent do when get_learner_state returns "learner
not found"?
3. What should the agent do when get_chapter_content returns a tier
restriction message?
Write the rules in natural language, not code.
What you are learning: Error handling in AGENTS.md is not try/catch blocks. It is written guidance: "If the learner is not found, ask for their name and call register_learner." The agent reads this as instruction, not as code.
Exercise 2: Compare Before and After
Ask Claude Code to analyze the difference your AGENTS.md made:
Before AGENTS.md, the agent called tools in unpredictable order.
After AGENTS.md, it follows a protocol. Review my AGENTS.md and
identify: which rules are the most impactful for consistent
behavior? Are there any gaps where ambiguous messages could still
cause the wrong tool to be selected?
What you are learning: Context engineering is measurable. You can compare agent behavior before and after AGENTS.md and quantify the improvement. The gaps Claude Code identifies become your next round of refinements.
Exercise 3: Write the Protocol for a Different App
Imagine you are building a customer support agent with five tools: get_customer_info, check_order_status, create_ticket, escalate_to_human, and send_follow_up. Draft a short AGENTS.md for that agent.
I am building a customer support agent with five tools:
get_customer_info, check_order_status, create_ticket,
escalate_to_human, send_follow_up. Write a short AGENTS.md
with a session start protocol, a support flow, and tool
selection rules for common customer messages.
What you are learning: AGENTS.md is not specific to TutorClaw. Any multi-tool agent benefits from an instruction manual. The pattern transfers: identify the workflow, define the start protocol, write rules for ambiguous inputs.
James sent "Help me learn" from WhatsApp and watched the dashboard. get_learner_state first. Then get_chapter_content. Then generate_guidance. The PRIMM "predict" prompt appeared on his phone.
He sent "I want to practice." get_learner_state, then get_exercises. Not get_chapter_content. The agent followed the rule.
"It follows the protocol now," he said. "Same tools, completely different behavior."
Emma nodded. "AGENTS.md is not code. It is context. The agent reads it and makes better decisions." She paused, then added something quieter. "I shipped an agent product once with twelve tools and no AGENTS.md. The agent used the tools in random order depending on how the user phrased their message. Support tickets piled up, all variations of 'the bot gave me exercises when I asked for help.' We wrote AGENTS.md in one afternoon and about eighty percent of those tickets disappeared."
"One afternoon?"
"One afternoon of writing instructions. Not code. Not a model retrain. Just clear sentences explaining the workflow." She pointed at his screen. "Your tools are good. Your descriptions are getting better. But descriptions tell the agent what each tool does. AGENTS.md tells it when and why. That is context engineering."
James looked at his AGENTS.md. Three sections. Maybe forty lines. The most impactful file in the project, and it contained zero code.
"Lesson 10," Emma said. "Your tool descriptions are next. AGENTS.md handles the big picture: session flow, tool order, routing rules. But the individual tool descriptions still have room to improve. Two-layer descriptions, cross-tool references, and explicit statements about what a tool should never be used for. That is where tool selection gets precise."