MCP tools reference

Use this page to identify tools and understand their roles. TRW registers 15 registered MCP tools. An ordinary session gets the always-on tools, plus each config-gated tool whose flag is on in .trw/config.yaml; tool_resolution_mode: all also turns on the peer messaging tools and trw_assess. Reviewer sessions get only trw_recall and trw_code.

Start here

For a typical task, start with trw_session_start, then use trw_recall when prior project knowledge may help. After implementation, run your project checks and record them with trw_build_check; use trw_deliver when the delivery gate is satisfied. The catalog below lists every registered tool and its surface.

Quick reference

Complete registered tool catalog. Surface describes default eligibility, not a guarantee that every session can call the tool.

The trw-mcp server registers 15 tools. Every session gets the always-on kernel; a few more tools are config-gated behind a project flag, and reviewer sessions receive a separate, smaller read-only surface. Registration does not imply that every session can call every tool. See the MCP server reference for runtime details and lifecycle for the delivery gate.

Filter tools

trw_session_startInspect

Description: Load prior learnings and any active run so you start with full context.
Surface: always-on

trw_initInspect

Description: Create a run directory and register it as the active run.
Surface: always-on

trw_statusInspect

Description: Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.
Surface: always-on

trw_recallInspect

Description: Retrieve prior learnings, or with graph_id=<id> that learning's graph neighbours.
Surface: always-on

trw_learnInspect

Description: Use when capturing a discovery, or correcting one with learning_id. Routine observations dilute recall. Record root causes before fixing; label uncertainty; update, never duplicate.
Surface: always-on

trw_checkpointInspect

Description: Append a progress snapshot so work survives context compaction.
Surface: always-on

trw_deliverInspect

Description: Persist learnings and progress so future sessions inherit this session's work.
Surface: always-on

trw_build_checkInspect

Description: Record build/test results for ceremony tracking and delivery gates.
Surface: always-on

trw_reviewInspect

Description: Compute a pass/warn/block review verdict and persist review.yaml.
Surface: always-on

trw_prd_validateInspect

Description: Score a PRD against the validation suite; returns a READY/NEEDS-WORK verdict.
Surface: always-on

trw_codeInspect

Description: Search indexed code, find a symbol's definition, or get before-edit hints.
Surface: always-on

trw_dispatchInspect

Description: Delegate a prompt to a sub-agent CLI in claude, codex, agy, opencode, cursor-cli, copilot, grok, or read a job or evidence. Use when you need an independent agent's review.
Surface: config-gated

trw_sendInspect

Description: Use when sending a request, reply or status to a formation peer.
Surface: config-gated

trw_inboxInspect

Description: Use when fetching messages, ACKing IDs, reading body-free status, or running a peer action (enroll, list, heartbeat, announce, withdraw, discover, ack_pause).
Surface: config-gated

trw_assessInspect

Description: Use when triaging, grading, routing or ranking. ONE call, every question (mix types); items={"key": state} screens many states with the same questions. state: facts plus known operator prefs, not your lean.
Surface: config-gated

Tool	Description	Surface
`trw_session_start`	Load prior learnings and any active run so you start with full context.	always-on
`trw_init`	Create a run directory and register it as the active run.	always-on
`trw_status`	Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.	always-on
`trw_recall`	Retrieve prior learnings, or with graph_id=<id> that learning's graph neighbours.	always-on
`trw_learn`	Use when capturing a discovery, or correcting one with learning_id. Routine observations dilute recall. Record root causes before fixing; label uncertainty; update, never duplicate.	always-on
`trw_checkpoint`	Append a progress snapshot so work survives context compaction.	always-on
`trw_deliver`	Persist learnings and progress so future sessions inherit this session's work.	always-on
`trw_build_check`	Record build/test results for ceremony tracking and delivery gates.	always-on
`trw_review`	Compute a pass/warn/block review verdict and persist review.yaml.	always-on
`trw_prd_validate`	Score a PRD against the validation suite; returns a READY/NEEDS-WORK verdict.	always-on
`trw_code`	Search indexed code, find a symbol's definition, or get before-edit hints.	always-on
`trw_dispatch`	Delegate a prompt to a sub-agent CLI in claude, codex, agy, opencode, cursor-cli, copilot, grok, or read a job or evidence. Use when you need an independent agent's review.	config-gated
`trw_send`	Use when sending a request, reply or status to a formation peer.	config-gated
`trw_inbox`	Use when fetching messages, ACKing IDs, reading body-free status, or running a peer action (enroll, list, heartbeat, announce, withdraw, discover, ack_pause).	config-gated
`trw_assess`	Use when triaging, grading, routing or ranking. ONE call, every question (mix types); items={"key": state} screens many states with the same questions. state: facts plus known operator prefs, not your lean.	config-gated

Session and workflow

These tools manage one work session. trw_session_start explicitly requests prior learnings and active-run state; checkpoints preserve milestones that a later session can recover after interruption or compaction.

trw_session_startInspect

What it does: Load prior learnings and any active run so you start with full context.
When to use: Start of every session

trw_initInspect

What it does: Create a run directory and register it as the active run.
When to use: New tasks beyond quick fixes

trw_statusInspect

What it does: Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.
When to use: Resuming after interruption

trw_checkpointInspect

What it does: Append a progress snapshot so work survives context compaction.
When to use: After each milestone; pre_compact=True before a context compaction

Tool	What it does	When to use
`trw_session_start`	Load prior learnings and any active run so you start with full context.	Start of every session
`trw_init`	Create a run directory and register it as the active run.	New tasks beyond quick fixes
`trw_status`	Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.	Resuming after interruption
`trw_checkpoint`	Append a progress snapshot so work survives context compaction.	After each milestone; pre_compact=True before a context compaction

Learning and knowledge

These tools record, retrieve, and update durable discoveries. Recall is explicit and ranked against the current query; delivery does not promote arbitrary learning text into your client's instruction file.

trw_learnInspect

What it does: Use when capturing a discovery, or correcting one with learning_id. Routine observations dilute recall. Record root causes before fixing; label uncertainty; update, never duplicate.
When to use: On errors, gotchas, or patterns; when an issue is fixed

trw_recallInspect

What it does: Retrieve prior learnings, or with graph_id=<id> that learning's graph neighbours.
When to use: Before starting unfamiliar work

Tool	What it does	When to use
`trw_learn`	Use when capturing a discovery, or correcting one with learning_id. Routine observations dilute recall. Record root causes before fixing; label uncertainty; update, never duplicate.	On errors, gotchas, or patterns; when an issue is fixed
`trw_recall`	Retrieve prior learnings, or with graph_id=<id> that learning's graph neighbours.	Before starting unfamiliar work

Quality and verification

Quality tools record validation outcomes, produce structured review artifacts, and enforce the delivery receipt boundary. Run the real project commands first; these tools preserve and evaluate the evidence rather than replacing the test runner.

trw_build_checkInspect

What it does: Record build/test results for ceremony tracking and delivery gates.
When to use: After implementation

trw_reviewInspect

What it does: Compute a pass/warn/block review verdict and persist review.yaml.
When to use: Before committing changes

trw_deliverInspect

What it does: Persist learnings and progress so future sessions inherit this session's work.
When to use: End of every task

Tool	What it does	When to use
`trw_build_check`	Record build/test results for ceremony tracking and delivery gates.	After implementation
`trw_review`	Compute a pass/warn/block review verdict and persist review.yaml.	Before committing changes
`trw_deliver`	Persist learnings and progress so future sessions inherit this session's work.	End of every task

Requirements

Requirements are the bridge between what you want and what your agent builds. trw_prd_validate checks an AARE-F PRD with EARS-format requirements for completeness before implementation begins; the trw-mcp prd create command drafts one.

trw_prd_validateInspect

What it does: Score a PRD against the validation suite; returns a READY/NEEDS-WORK verdict.
When to use: Before implementation begins

Tool	What it does	When to use
`trw_prd_validate`	Score a PRD against the validation suite; returns a READY/NEEDS-WORK verdict.	Before implementation begins

Code

trw_code answers code questions from a local index: text search, symbol lookup, and before-edit hints that pair a file with the learnings recorded about it. Build or refresh the index with the trw-mcp code index command; a query never rebuilds it.

trw_codeInspect

What it does: Search indexed code, find a symbol's definition, or get before-edit hints.
When to use: Before editing unfamiliar code: mode="search", "symbol", or "hint"

Tool	What it does	When to use
`trw_code`	Search indexed code, find a symbol's definition, or get before-edit hints.	Before editing unfamiliar code: mode="search", "symbol", or "hint"

Feedback

Send the TRW maintainer a bug report, install issue, feature request, or general feedback without leaving your editor. Submissions go through the authenticated platform endpoint, and PII - license keys, API key prefixes, your home path, and sensitive env vars - is redacted client-side before anything leaves your machine.

trw_statusInspect

What it does: Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.
When to use: When you hit a bug or want to send feedback: trw_status(feedback={...})

Tool	What it does	When to use
`trw_status`	Report the active run's phase, progress and last activity. delivery=<id>: a trw_deliver status. feedback={category, subject, message}: post a memo (never a false success). detail="surface": the resolved profile and tool surface.	When you hit a bug or want to send feedback: trw_status(feedback={...})

Config-gated tools

Each of these tools appears only while its flag is on in .trw/config.yaml. The peer messaging tools (comms_enabled) are on by default; trw_assess (assess_enabled) and trw_dispatch (dispatch_tools_exposed) are off until you turn them on.

trw_sendInspect

What it does: Use when sending a request, reply or status to a formation peer.
When to use: Messaging a formation peer; on by default (comms_enabled)

trw_inboxInspect

What it does: Use when fetching messages, ACKing IDs, reading body-free status, or running a peer action (enroll, list, heartbeat, announce, withdraw, discover, ack_pause).
When to use: Reading or acknowledging peer messages; on by default (comms_enabled)

trw_assessInspect

What it does: Use when triaging, grading, routing or ranking. ONE call, every question (mix types); items={"key": state} screens many states with the same questions. state: facts plus known operator prefs, not your lean.
When to use: Only when assess_enabled is true and assessment is appropriate

trw_dispatchInspect

What it does: Delegate a prompt to a sub-agent CLI in claude, codex, agy, opencode, cursor-cli, copilot, grok, or read a job or evidence. Use when you need an independent agent's review.
When to use: Handing a second-opinion review to another coding CLI; needs dispatch_tools_exposed

Tool	What it does	When to use
`trw_send`	Use when sending a request, reply or status to a formation peer.	Messaging a formation peer; on by default (comms_enabled)
`trw_inbox`	Use when fetching messages, ACKing IDs, reading body-free status, or running a peer action (enroll, list, heartbeat, announce, withdraw, discover, ack_pause).	Reading or acknowledging peer messages; on by default (comms_enabled)
`trw_assess`	Use when triaging, grading, routing or ranking. ONE call, every question (mix types); items={"key": state} screens many states with the same questions. state: facts plus known operator prefs, not your lean.	Only when assess_enabled is true and assessment is appropriate
`trw_dispatch`	Delegate a prompt to a sub-agent CLI in claude, codex, agy, opencode, cursor-cli, copilot, grok, or read a job or evidence. Use when you need an independent agent's review.	Handing a second-opinion review to another coding CLI; needs dispatch_tools_exposed

Usage examples

A connected agent calls these tools when the workflow requires them. These examples show the activity shape you may see as a task moves from startup to delivery.

Common patterns

Tools combine differently depending on task risk and client capability. Start with the smallest pattern that preserves the evidence and handoff the task actually needs.

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. Unlike tools, resources are not filtered by task type — all of them are readable in every session.

Resource: trw://framework/config
What it provides: Current TRW configuration - ceremony mode, trust level, target platforms

Resource: trw://framework/versions
What it provides: Framework and package versions for compatibility checks

Resource: trw://run/state
What it provides: Active run phase, checkpoints, and progress metrics

Resource: trw://learnings/summary
What it provides: Recent high-impact learnings for the current project

Resource: trw://templates/prd
What it provides: PRD requirements-document template (AARE-F)

Resource: trw://templates/shard-card
What it provides: Shard-card scaffold for decomposing larger requirements

Resource	What it provides
`trw://framework/config`	Current TRW configuration - ceremony mode, trust level, target platforms
`trw://framework/versions`	Framework and package versions for compatibility checks
`trw://run/state`	Active run phase, checkpoints, and progress metrics
`trw://learnings/summary`	Recent high-impact learnings for the current project
`trw://templates/prd`	PRD requirements-document template (AARE-F)
`trw://templates/shard-card`	Shard-card scaffold for decomposing larger requirements

Claude Code MCP tool search

TRW registers 15 MCP tools. Claude Code can defer MCP schemas until they are needed, reducing host-context overhead without changing the server catalog. Other clients own their discovery and schema-loading behavior.

Behavior: Template default
Details: The bundled Claude Code settings set ENABLE_TOOL_SEARCH=true

Behavior: Mechanism
Details: Tool schemas are deferred and fetched on demand, reducing prompt overhead for tools not used in the current session

Behavior: Opt out
Details: Set ENABLE_TOOL_SEARCH=false in the env section of a client config file such as .claude/settings.json

Behavior: Boundary
Details: This changes how Claude Code loads MCP schemas; it does not remove tools from the trw-mcp server

Behavior	Details
Template default	The bundled Claude Code settings set ENABLE_TOOL_SEARCH=true
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`
Boundary	This changes how Claude Code loads MCP schemas; it does not remove tools from the trw-mcp server

client config example (.claude/settings.json)

{
  "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.

Skills

Slash commands that orchestrate multiple tools into single workflows

Agents

Specialists that call these tools during implementation, review, and audit

Lifecycle

The six phases that determine when each tool should fire

Start here

Quick reference

Session and workflow

Learning and knowledge

Quality and verification

Requirements

Code

Feedback

Config-gated tools

Usage examples

trw_session_startAlways first - loads prior learnings and recovers active runs.

trw_recallSearches project knowledge before unfamiliar work.

trw_learnCaptures discoveries the next session should inherit.

trw_checkpointSaves progress before interruption or compaction.

trw_build_checkRecords project-native validation evidence before delivery.

trw-mcp prd createCreates structured requirements from a feature request.

trw_deliverAlways last - persists learnings and closes the run.

Common patterns

Quick fixBug fixes, typo corrections, and config changes. Minimal ceremony - three tools, under 10 minutes.

Feature implementationNew capabilities, multi-file changes, and anything with requirements. Full six-phase ceremony with checkpoints.

Resume interrupted workContext compacted or a session crashed. The agent recovers from the last checkpoint and keeps going.

MCP resources

Claude Code MCP tool search

Next steps

Pair the right tool with the workflow it belongs in.