Emma dropped a blank document on James's screen. "Nine tools. Design all of them before you write a single line of code."
James scrolled through the empty page. "All nine? I barely got register_learner working in the last chapter."
"Exactly. You know how to describe a tool, steer a spec, and verify the result. That is the building skill. This is the planning skill." She tapped the screen. "Write a contract for every tool. Name, inputs, outputs, who can call it, what data it needs. Like writing job descriptions before you hire anyone."
James thought about that. In his warehouse days, he never hired someone without a job description. The description told you what the person did, what they needed access to, and who they reported to. A function was no different.
"Nine job descriptions," he said.
"Nine job descriptions. Then we build."
You have the same blank sheet and the same constraint: contracts first, code second.
In this chapter, you design all 9 TutorClaw tools as specifications. No code, no terminal, no Claude Code. You define what each tool does, what it accepts, what it returns, who can call it, and what data it depends on. By the end, you have the complete blueprint for Module 9.3, Chapters 3 through 7.
Every tool gets a contract with five parts:
You already know the first tool. Start there.
These manage learner data. All three depend on a single resource: the JSON state file stored locally in the data/ directory.
You built this in Module 9.2. Now write the full contract:
These are the tools you have not seen before. Design each one carefully.
Three categories. Every tool falls into exactly one:
Notice the logic. "All" tools are the core tutoring loop: register, check state, teach, assess, record progress. Every learner needs these regardless of whether they pay.
"Gated" tools deliver the content that makes paying worthwhile: full chapter access, targeted exercises, code execution. Free learners get a taste (chapters 1 through 5). Paid learners get everything.
"Free only" has exactly one tool. Once a learner has paid, showing them a checkout link is pointless and confusing.
Every tool depends on at least one resource. There are exactly four resource types in TutorClaw:
The dependency map:
Two patterns to notice. First: every tool depends on the JSON state file. It is the backbone of the entire system. If the state file is corrupted, every tool breaks. Second: only two tools touch external resources beyond JSON and content files. submit_code needs a sandbox; get_upgrade_url needs Stripe. Everything else is local file reads and writes.
Trace a single session to see how the tools chain together:
Seven tool calls. Five hit the JSON state file. Two also hit the content directory. Zero hit Stripe or the sandbox. This is the typical pattern: most of a tutoring session lives inside state and content. Payment and code execution are occasional events, not every-turn events.
Pick a tool that does NOT exist in TutorClaw yet: a get_learning_path tool that recommends the next three chapters based on the learner's confidence scores across all completed chapters.
What you are learning: Writing a tool contract forces you to think through the agent's decision: when would the agent call this tool instead of another? The description must make that unambiguous.
Look at the dependency graph above and identify the single resource that, if it became slow or unavailable, would affect the most tools.
What you are learning: Dependency mapping reveals risk. The JSON state file is a single point of failure for all 9 tools. This is fine for a local prototype (the whole point of this chapter), but it is the first thing you would change when scaling to production.
TutorClaw currently has two tiers (free and paid). Imagine a third tier, "student," that gets chapters 1 through 10 and limited code submissions but no exercises.
What you are learning: Tier design is product design, not engineering. Changing a tier means updating tool contracts and gating logic, not rewriting code. The spec absorbs the change; Claude Code implements it.
James finished the last contract and leaned back. "Nine tools. Five fields each. That took longer than I expected."
Emma scanned the page. She paused at submit_code. "You listed 'mock sandbox' as the dependency. Walk me through why."
"Because we are not actually executing learner code in production yet. The mock returns hardcoded output so we can test the flow. Real sandboxing is a scaling problem for later, not a product problem for now."
Emma nodded slowly. "When I designed my first tool server, I spent two weeks building a real sandbox before I had a single tool working end to end." She paused. "I should have mocked it first and shipped."
James grinned. "Like shipping crates from the warehouse. You do not build custom crates for every product. You use standard boxes, ship the product, and upgrade the packaging when volume justifies it."
"Standard boxes." Emma wrote the phrase in the margin of the spec. "I am stealing that analogy for the next chapter." She closed the document. "Your nine job descriptions are done. Module 9.3, Chapter 3: you hand the first three to Claude Code and watch it build them."