MCP Tools Reference
MCP tools are the low-level primitives your AI uses while it works. You usually do not type them directly; they show up in activity traces as the agent loads memory, checkpoints progress, verifies quality, and closes the session. TRW exposes 24 MCP tools across six reader-friendly groups so you can tell what the agent is doing and why.
Naming note
One tool still carries a historical name: trw_claude_md_sync. In modern TRW installs it syncs high-impact learnings into whichever client surfaces this repo targets — not just Claude-specific files.
Quick reference
All 24 tools at a glance. The Phase column shows where each tool typically fires in the six-phase lifecycle.
| Tool | Description | Phase |
|---|---|---|
| trw_session_start | Load prior learnings and recover any active run. | Research |
| trw_init | Create a run directory for progress tracking. | Plan |
| trw_status | Show current phase, progress, and next steps. | Any |
| trw_checkpoint | Save an atomic progress snapshot. | Implement |
| trw_pre_compact_checkpoint | Emergency checkpoint before context compaction. | Any |
| trw_learn | Record a discovery for all future sessions. | Review |
| trw_learn_update | Mark learnings as resolved or obsolete. | Any |
| trw_recall | Search past learnings by keyword, tags, or impact. | Research |
| trw_claude_md_sync | Promote high-impact learnings into the client-facing instruction surfaces for this repo. | Deliver |
| trw_build_check | Record pytest, mypy, and coverage results for delivery gates. | Validate |
| trw_review | Independent code review with rubric scoring. | Review |
| trw_deliver | Persist learnings, sync artifacts, close run. | Deliver |
| trw_prd_create | Generate an AARE-F requirements document. | Plan |
| trw_prd_validate | Check requirements quality and completeness. | Plan |
Session & Workflow
These tools manage the lifecycle of a single work session. They ensure your agent never starts from scratch — prior learnings load automatically, and checkpoints survive context compaction so interrupted work resumes where it left off.
| Tool | What it does | When to use |
|---|---|---|
| trw_session_start | Load prior learnings and recover any active run. | Start of every session |
| trw_init | Create a run directory for progress tracking. | New tasks beyond quick fixes |
| trw_status | Show current phase, progress, and next steps. | Resuming after interruption |
| trw_checkpoint | Save an atomic progress snapshot. | After each milestone |
| trw_pre_compact_checkpoint | Emergency checkpoint before context compaction. | Automatically before context window fills |
Tip
Always call trw_session_start first. Without it, your agent has no memory of prior sessions — it will rediscover gotchas that were already solved.
Learning & Knowledge
The knowledge layer is what makes TRW compound. These tools capture discoveries, search prior learnings, and promote high-impact knowledge into your project's permanent instruction surfaces. Session 50 surfaces the gotcha that session 3 discovered.
| Tool | What it does | When to use |
|---|---|---|
| trw_learn | Record a discovery for all future sessions. | On errors, gotchas, or patterns |
| trw_learn_update | Mark learnings as resolved or obsolete. | When issues are fixed |
| trw_recall | Search past learnings by keyword, tags, or impact. | Before starting unfamiliar work |
| trw_claude_md_sync | Promote high-impact learnings into the client-facing instruction surfaces for this repo. | During delivery or after major discoveries |
Info
Learnings are scored with Q-learning and Ebbinghaus decay curves. High-impact entries auto-promote into the repo's instruction surfaces via trw_claude_md_sync. Low-impact entries decay and are eventually pruned.
Quality & Verification
Quality gates prevent rework. Build checks catch failures before code review, independent reviews score against DRY/KISS/SOLID rubrics, and delivery gates ensure learnings persist. Without these gates, AI-generated code ships untested.
| Tool | What it does | When to use |
|---|---|---|
| trw_build_check | Record pytest, mypy, and coverage results for delivery gates. | After implementation |
| trw_review | Independent code review with rubric scoring. | Before committing changes |
| trw_deliver | Persist learnings, sync artifacts, close run. | End of every task |
Warning
trw_build_check runs the full test suite and type-checker. On large projects this can take several minutes. Use scope="fast" for quick validation during implementation, then scope="full" before delivery.
Requirements
Requirements are the bridge between what you want and what your agent builds. These tools create AARE-F compliant PRDs with EARS-format requirements, then validate them for completeness before implementation begins.
| Tool | What it does | When to use |
|---|---|---|
| trw_prd_create | Generate an AARE-F requirements document. | Defining new features |
| trw_prd_validate | Check requirements quality and completeness. | Before implementation begins |
Tip
For a full pipeline — create, groom, review, and plan in one step — use the /trw-prd-new skill instead. It orchestrates both tools automatically.
Usage examples
Your AI calls these tools automatically. These examples show the shape of the activity you should expect to see while a task moves from startup to delivery.
Common patterns
Tools combine into patterns depending on task complexity. Your agent selects the right pattern automatically, but understanding these helps you predict what your agent will do.
MCP resources
In addition to tools, TRW exposes 6 read-only MCP resources. Your AI reads these for configuration, state, and templates without making a tool call.
| Resource | What it provides |
|---|---|
| trw://config | Current TRW configuration — ceremony mode, trust level, target platforms |
| trw://version | Framework and package versions for compatibility checks |
| trw://run-state | Active run phase, checkpoints, and progress metrics |
| trw://learnings | Recent high-impact learnings for the current project |
| trw://templates | PRD templates, commit formats, and skill scaffolds |
| trw://analytics | Historical build pass rates, ceremony compliance, and learning yield |
MCP Tool Search
TRW ships 24 MCP tools. In large sessions, tool descriptions alone can consume a significant share of the context window. MCP Tool Search defers tool schemas until they are actually needed, keeping the active context lean.
| Behavior | Details |
|---|---|
| Default state | Enabled — auto-activates when tool descriptions exceed 10% of the context window |
| Mechanism | Tool schemas are deferred and fetched on demand, reducing prompt overhead for tools not used in the current session |
| Opt out | Set ENABLE_TOOL_SEARCH=false in the env section of a client config file such as .claude/settings.json |
| Force enable | Set ENABLE_TOOL_SEARCH=true to activate regardless of context window size |
{
"env": {
"ENABLE_TOOL_SEARCH": "false" // disable deferred schemas
}
}Next steps
Tools are the primitives. Skills show the packaged workflows built on top of them, agents show who uses them, and lifecycle explains when each one should appear.