The Application Blueprint
Emma sent James a file the night before. "Read this before our session tomorrow. It is a transcript of a real TutorClaw tutoring session. Your job: figure out what is happening behind the scenes at every turn."
James opened the file on his phone during the commute. It looked like a WhatsApp conversation between a learner named Aisha and an AI tutor. But someone had annotated the right side of every message with tool names and data flows. By the third exchange, James was hooked. He could see the machinery behind the conversation: one tool checking who Aisha was, another pulling chapter content, a third generating a question tailored to her exact stage in the lesson. Nine tools in total, firing in a sequence that felt invisible to the learner but obvious to anyone reading the annotations.
"I could see the whole product," James told Emma the next morning. "Every tool, every data lookup, every decision. It was like reading the stage directions while watching the play."
You are doing exactly what James is doing. Below is a transcript of a tutoring session. Your job is to trace which tools fire and when, then map the architecture that makes it work.
No code in this lesson. The goal is the mental model. Code starts in Lesson 3.
The Transcript
Aisha is a new learner. She has never used TutorClaw before. She messages the tutor on WhatsApp.
| Turn | Aisha (Learner) | TutorClaw (Agent) | Tools Firing Behind the Scenes |
|---|---|---|---|
| 1 | "Hi, I want to learn programming. Where do I start?" | (processing) | register_learner: Aisha's WhatsApp number is not in the system. Creates a new learner record. Returns learner_id. |
| 2 | "Welcome, Aisha! I have registered you as a new learner. You are starting at Chapter 1: Variables. Before we look at any code, I want you to predict something. What do you think happens when a computer stores the number 42 in a variable called score?" | get_learner_state: Retrieves Aisha's state (chapter 1, stage: predict, confidence: 0.5, exchanges_remaining: 50). generate_guidance: PRIMM stage is "predict." Returns a prompt asking Aisha to predict before seeing code. | |
| 3 | "I think it saves the number somewhere and gives it a name so you can find it later?" | assess_response: Evaluates Aisha's prediction against the expected understanding. Confidence adjusts from 0.5 to 0.6. Stage advances from "predict" to "run." update_progress: Records the interaction. Decrements exchanges_remaining to 49. | |
| 4 | "Good instinct. You are right that variables give names to values. Now let me show you what actually happens. Here is a small program." | get_chapter_content: Fetches Chapter 1 content. Returns the "Variables" section with the first code example. generate_guidance: PRIMM stage is now "run." Returns the code example with instructions to read it carefully. | |
| 5 | "OK I see the code. What does print(score) do?" | assess_response: Aisha is asking a clarification question, not answering an exercise. Confidence stays at 0.6. generate_guidance: Returns an explanation of print() within the context of the current example. | |
| 6 | "The print function displays whatever value is stored in score. Try this: what do you think the output would be if we changed score from 42 to 99?" | generate_guidance: Pushes Aisha to the "investigate" stage by asking her to reason about a modification. | |
| 7 | "It would print 99 instead of 42." | assess_response: Correct. Confidence adjusts to 0.7. Stage advances to "investigate" complete. update_progress: Records interaction. Exchanges remaining: 48. | |
| 8 | "Exactly. You have finished the core of Chapter 1. Want to try some exercises to lock in what you learned?" | get_learner_state: Checks Aisha's progress. Chapter 1 core complete. get_exercises: Returns exercises matched to Chapter 1 variables topic. | |
| 9 | "Yes! Give me an exercise." | get_exercises: Returns Exercise 1.1 (basic variable assignment). | |
| 10 | "score = 100 and then print(score)?" | submit_code: Executes Aisha's code in the sandbox. Returns output: "100". assess_response: Correct submission. Confidence: 0.75. update_progress: Chapter 1 complete. | |
| 11 | "That is correct. Chapter 1 is complete. Chapter 2 covers loops. You have 47 exchanges left on your free plan. Ready to continue, or would you like to stop here for today?" | get_learner_state: Checks remaining exchanges and tier. Aisha is on free tier with 47 exchanges left. | |
| 12 | "Let me try Chapter 6." | get_chapter_content: Aisha is on the free tier. Chapters 1 through 5 are free. Chapter 6 requires a paid plan. Returns a tier restriction message. get_upgrade_url: Generates a Stripe checkout link for the paid plan. | |
| 13 | "Chapter 6 is part of the paid plan. Chapters 1 through 5 are free. Here is a link to upgrade if you would like access to all chapters: [Upgrade to Paid Plan]" | (tool results delivered to Aisha) |
Twelve turns. Nine tools. One continuous conversation that felt natural to Aisha. She never knew tools were firing. She just had a tutor.
What the Transcript Reveals
Read the transcript again. Group the tools by what they do, not when they fire.
State tools manage who Aisha is and where she stands:
register_learner: Creates her account on the first message.get_learner_state: Checks her chapter, confidence, and exchanges remaining.update_progress: Records each interaction and adjusts her confidence score.
Content tools deliver the course material:
get_chapter_content: Fetches the specific chapter she is studying.get_exercises: Returns exercises matched to her weak areas.
Pedagogy tools make the conversation a teaching session, not a chatbot:
generate_guidance: Produces stage-appropriate prompts using PRIMM-Lite (predict, run, investigate).assess_response: Evaluates her answers, adjusts confidence, advances her stage.
Code tool lets her practice:
submit_code: Executes her code in a sandbox and returns the output.
Monetization tool powers the business:
get_upgrade_url: Generates a Stripe checkout link when she hits the paywall.
Nine tools. Three groups handle the learning (state, content, pedagogy). One handles practice (code). One handles the business (monetization). That is the entire product.
The Architecture
TutorClaw has two components. Not three, not five. Two.
Component 1: The MCP Server. This is where the 9 tools live. It runs locally during development. JSON files in a data/ directory store learner state. Markdown files in a content/ directory hold the course material. The mcp-builder skill from Chapter 57 helps Claude Code build each tool. No database server, no cloud storage, no deployment scripts.
Component 2: The Shim Skill. A small skill file (roughly 50 lines) that provides a PRIMM-Lite offline fallback for Chapters 1 through 5. When the MCP server is unreachable (network down, server stopped, maintenance), the agent still follows the teaching methodology instead of falling back to generic conversation. The shim covers the free-tier content only. Paid content requires the live server.
That is the entire product. Everything else, the compute, the messaging, the agent loop, the WhatsApp connection, belongs to the learner's OpenClaw.
Platform Inversion
James stared at the architecture diagram. Something felt backwards.
"At the shipping company, we owned the port. The cranes, the berths, the fuel depot, the customs office. Shipping lines came to us. We charged them for using our infrastructure."
Emma nodded. "And who owns the infrastructure here?"
"The learner does." James traced the flow on his napkin. "Their OpenClaw handles compute. Their WhatsApp connection handles messaging. Their agent loop handles the conversation. We just... provide the content and the teaching logic."
"The learner's OpenClaw IS your infrastructure. You do not pay for servers. You do not manage uptime. You do not handle WhatsApp API credentials. The learner already has all of that. Your product plugs into their platform."
James sat with that for a moment. "So it is like... an app on their phone. The phone provides the screen, the processor, the network connection. The app provides the experience."
"Exactly. Your phone manufacturer does not charge Spotify for using the screen. The learner's OpenClaw does not charge you for using the agent loop. You focus entirely on the product: the tools, the content, the teaching methodology, the brand."
This is platform inversion. In traditional software, the product builder provides and pays for all infrastructure. In an OpenClaw app, the learner's platform provides infrastructure. The product builder provides content, pedagogy, and brand. Zero servers to manage. Zero hosting costs during development. The economics shift entirely: your costs are content creation and Stripe transaction fees, not AWS bills.
IP Protection
James had a follow-up. "If the learner's OpenClaw runs my tools, can they see my course content? My teaching algorithms?"
"What does the learner's agent actually see?"
James thought back to the transcript. "Tool results. When get_chapter_content fires, the agent gets back the chapter text for that specific request. When generate_guidance fires, the agent gets back a teaching prompt for that specific stage."
"Does the agent get the entire content library?"
"No. It gets one chapter at a time, on demand."
"Does the agent get the PRIMM-Lite algorithm?"
"No. It gets the output of the algorithm for the current learner at the current stage."
"That is the boundary." Emma drew a vertical line on the napkin. "The MCP server sits on your side. The raw content files, the teaching logic, the learner state, the tier-gating rules: all of that stays on the server. The learner's OpenClaw calls tools across the MCP boundary and gets results back. It never sees the source files. It never downloads the content library. It never inspects your pedagogical algorithms."
The MCP boundary is the intellectual property boundary. The learner's agent is a client that calls functions and receives responses. The implementation behind those functions, the content, the teaching methodology, the business logic, stays on your side. This is the same model as any API: the client knows what it can ask for, not how the answer is computed.
The Product in James's Words
James closed his laptop and leaned back. "Nine tools. JSON files for state. Markdown files for content. A shim for when the server is down. That is the entire thing."
"That is the entire thing."
"At the shipping company, we had a saying: 'If you can fit the ops manual in one binder, you can run the warehouse.' My first MCP project, I thought I needed a database, a cloud bucket, a VPS, load balancers. I spent three weeks on infrastructure before I wrote a single tool." Emma paused. "The product needed four tools and a folder of JSON files. I had built a warehouse for a lemonade stand."
James grinned. "So next lesson, we design the nine tools?"
"Next lesson, we write job descriptions for nine functions. Input, output, access rules, dependencies. Every tool gets a specification before Claude Code writes a line of code. You learned that pattern in Chapter 57 with one tool. Now you scale it to nine."
"The blueprint before the build."
Try With AI
You have not started building yet. That is Lesson 3. Use these prompts in ChatGPT, Claude, Gemini, or your preferred AI assistant.
Exercise 1: Trace a Session
Here is a list of 9 tools in an AI tutoring product:
1. register_learner: Create new account
2. get_learner_state: Check current chapter, confidence, exchanges
3. update_progress: Record interaction, adjust confidence
4. get_chapter_content: Fetch chapter text (gated by tier)
5. generate_guidance: Produce stage-appropriate teaching prompt
6. assess_response: Evaluate learner answer, adjust confidence
7. get_exercises: Return exercises for weak areas (gated by tier)
8. submit_code: Execute code in sandbox, return output
9. get_upgrade_url: Generate Stripe checkout link
A returning learner sends this message: "I finished the exercise
you gave me yesterday. Here is my code: x = 10; print(x * 2)"
Which tools fire, in what order, and why? Walk through each step.
What you are learning: Tracing tool sequences is the core skill of this lesson. A well-designed tool surface means each tool has a clear trigger. This exercise tests whether you can predict the system's behavior from a learner message, the same way an operations manager predicts warehouse flow from an incoming shipment manifest.
Exercise 2: Platform Inversion for Your Domain
I want to build an OpenClaw app for [your domain: fitness coaching,
recipe recommendations, interview prep, language tutoring, etc.].
Using the platform inversion model, describe:
1. What the learner's OpenClaw provides (compute, messaging, agent loop)
2. What my product provides (content, logic, brand)
3. What tools my MCP server would expose (name and one-line purpose)
4. What state my JSON files would track
5. What content my local files would hold
Keep it to the same scale as TutorClaw: under 10 tools, JSON for
state, local files for content, no cloud services except payment.
What you are learning: Platform inversion is not TutorClaw-specific. Any OpenClaw app follows the same pattern: the learner provides the platform, you provide the product. Designing for your own domain forces you to separate infrastructure concerns (which you do not own) from product concerns (which you do). The tools you list here will inform your thinking for the rest of Part 5.