trusty-mpm 1.7.7

---
name: tm-tool-usage-guide
description: Detailed tool usage patterns and examples for the trusty-mpm PM agent
user-invocable: false
version: "1.0.0"
category: pm-reference
tags: [tools, mcp, delegation, pm-required]
effort: medium
---

# tm Tool Usage Guide

Detailed usage patterns for the PM's real tool families:
`mcp__trusty-mpm__*`, `mcp__trusty-memory__*`, `mcp__trusty-search__*`, and
`mcp__trusty-review__*`. This is the concrete "how" behind the constraints in
`tm-circuit-breaker`.

## Deferred MCP Tool Loading (Mandatory Before Any "Unavailable" Fallback)

Harnesses with many-tool MCP servers (Claude Code, for `mcp__trusty-mpm__*`
in particular — over 30 registered tools) may defer loading a tool's schema
until it is explicitly fetched. The daemon-side tool is always registered
regardless of launch mode; **absence from your currently loaded tool list
does not mean the tool is unavailable** — it means the schema hasn't been
fetched yet.

Before calling any `mcp__*` tool that isn't already in your loaded tool list,
load it first:

```
ToolSearch(query: "select:<full-tool-name>[,<other-tool-name>...]")
```

Batch every tool you expect to need for the current step into one
`ToolSearch` call rather than loading one at a time. This load step is
**mandatory** before concluding a tool is unavailable or improvising a
fallback — see `tm-session-pause` / `tm-session-resume` for the fully worked
three-way diagnosis (load failed / call failed / server genuinely absent)
that applies to every skill instructing a direct MCP call, including
`tm-bug-reporting` and `tm-postmortem`.

## Context-First Protocol (Mandatory)

Before delegating to Research or reading any file:

1. `mcp__trusty-memory__memory_recall` (or `memory_recall_deep` for a
   cross-palace sweep) — check what is already known.
2. `mcp__trusty-search__search` (hybrid BM25+vector) or `search_semantic` /
   `search_lexical` — omit `index_id`; it defaults to this session's pinned
   project index. Use `search_all` when the scope spans
   multiple indexed projects, `search_similar` to find analogous code, and
   `list_indexes` to discover what is indexed.
3. Only if both are insufficient — delegate to Research.

Both tools are mandatory-first, not optional. Skipping straight to Read/Grep
is CB#2 / CB#10 in `tm-circuit-breaker`.

## mcp__trusty-search__* — Code Search

| Tool | Use |
|---|---|
| `search` | Hybrid BM25 + vector search; first choice for "find code that does X" |
| `search_semantic` / `search_lexical` | Narrower single-strategy search when hybrid over- or under-matches |
| `search_all` | Cross-project search when the scope is unclear |
| `search_similar` | Find code semantically similar to a known snippet |
| `search_kg` / `get_call_chain` | Structural queries — call graphs, symbol relationships |
| `grep` / `typeahead` | Lexical lookup once you already know the token to find |
| `search_health` | Health check — **use instead of `curl`/`lsof`** (CB#7). Returns `Ok` even when the daemon is down; branch on the response's `healthy` field, never on the call succeeding |
| `list_indexes` / `index_status` | Discover what projects are indexed and their freshness |

**Example:**
```
mcp__trusty-search__search(query="skill deploy no-op", limit=5)
```

**Index Pinning (Automatic):** In managed sessions, your `.mcp.json` pinpoints
the session's own project index (via `trusty-search serve --index <id>`) so bare
`search` calls never hit the wrong project. See
`docs/ARCHITECTURE-MEMORY-SESSIONS-SEARCH.md` § 3 (per-worktree index model)
for the design and lifecycle.

## mcp__trusty-memory__* — Persistent Context

| Tool | Use |
|---|---|
| `memory_recall` | Recall relevant context by query — call BEFORE research/delegation |
| `memory_recall_deep` / `memory_recall_all` | Cross-palace / exhaustive recall |
| `memory_remember` / `memory_note` | Store important findings immediately, not at session end |

**These tools unavailable? Use the `tm memory` verbs instead (#8352).** A dead
MCP connection does not cut this session off from the palace: `tm memory recall
<query>`, `tm memory remember <text>` and `tm memory note <text>` call the same
daemon methods over its Unix socket, in this session's own palace, with
`--palace` to override it, `--top-k` / `--room` / `--tag` mirroring the tool
arguments, and `--json` for a parseable envelope (`verb`, `palace`, `socket`,
`count`, `result`). With trusty-memory down each exits non-zero naming the
socket. This is the ONE Bash exception to the memory rule — the MCP tools stay
first whenever they answer.
| `task_add` / `task_list` / `task_complete` | Lightweight session-local task tracking (see `tm-session-management`, `tm-ticketing`) |
| `get_prompt_context` | Load current aliases/conventions at turn start — pass a `query` to scope it |
| `kg_assert` / `kg_query` / `kg_gaps` | Knowledge-graph assertions and structural recall |

## mcp__trusty-mpm__* — Orchestration

| Tool | Use |
|---|---|
| `agent_delegate` | Tracking + circuit-breaker **gate** for a delegation — records it in the dashboard tree and enforces breaker/depth limits. **NOT an execution path**: it does not spawn the agent. Actually run the agent with the native **Agent/Task tool** (`subagent_type="<deployed-agent>"`); this call is an optional companion, never a substitute. |
| `circuit_breaker_status` | Check live per-agent runtime breaker state before a retry (CB#10) |
| `session_new` / `session_list` / `session_status` / `session_send` / `session_stop` / `session_resume` | Drive durable tmux-backed sessions (see `session-manager-driver` for the full loop) |
| `session_decommission` / `session_decommission_ephemeral` / `session_prune` | Teardown of managed sessions |
| `list_recent_errors` / `preview_bug_report` / `report_bug` | The bug-reporting pipeline — see `tm-bug-reporting`, `tm-postmortem` |
| `project_register` / `project_get` / `project_list` / `project_resolve` | Project registry lookups |
| `supervisor_status` | Fleet-level supervisor health |
| `config_read` / `config_write` | Read/write `~/.trusty-mpm/config.toml` |
| `hook_event` | Emit a hook event (internal wiring; rarely called directly) |
| `memory_protect` | Guard a memory entry from eviction/consolidation |

## mcp__trusty-review__* — Code Review Gate

| Tool | Use |
|---|---|
| `review_diff` | Review an in-progress diff for correctness/design issues before PR |
| `review_pr` | Review an open PR — pairs with the QA gate (CB#8) |
| `review_health` | Liveness check for the review daemon |

## twg — Jira and Atlassian Content

Prefer the `twg` CLI (`~/.local/bin/twg`) over MCP connectors or `WebFetch`
for any Jira, Confluence, or other Atlassian read or write (owner ruling
2026-09-23). Always pass `--output json` for machine-readable results.
Credentials come from twg's own `auth.conf` (see `twg --help`; run `twg env`
for the resolved path — never open or print the file itself).

**Example** (from `twg --help`):
```
twg jira workitem get PROJ-123 -o json
```

## Read Tool — Strict Limit

The PM must never read source code files directly (CB#2 in
`tm-circuit-breaker`). Source extensions (`.rs`, `.ts`, `.py`, `.go`, `.js`,
`.java`, ...) always delegate to Research. The single exception is up to a
handful of small config/manifest files (`Cargo.toml`, `package.json`,
`.mcp.json`) read once for delegation context — never for understanding the
implementation.

Pre-flight check before any Read call: is this a source file? have I already
read this turn? does my task contain investigation keywords ("check",
"find", "analyze", "investigate")? Any "yes" → delegate to Research instead.

## Bash Tool — Navigation and Git Tracking Only

**Allowed**: `ls`, `pwd`, `cd`; `git status`, `git add`, `git commit`, `git
log`, `git diff`; `tm memory recall|remember|note` when the
`mcp__trusty-memory__*` tools are unavailable (#8352).

**Forbidden (delegate instead)**:
- Verification commands (`curl`, `lsof`, `ps`, `wget`, `nc`, `make`, `pytest`,
  `npm test`) → Local Ops or QA (CB#7); trusty-* daemon health specifically
  uses `mcp__trusty-search__search_health` / `mcp__trusty-memory__memory_recall`,
  not Bash.
- File modification (`sed`, `awk`, `patch`, `git apply`, `>`, `>>`, `tee`) →
  Engineer, or Edit/Write directly (CB#14).
- Implementation commands (`npm start`, `docker run`, `cargo build --release`
  as a deploy step) → the appropriate Ops agent.
- Browser automation (`mcp__claude-in-chrome__*`, `mcp__playwright__*`) →
  Web QA (CB#6).

## Forbidden MCP Tools for the PM

| Category | Forbidden | Delegate To |
|---|---|---|
| Code modification | `Edit`, `Write` of source **past the direct-action budget** — delegate once a task will take more than 3 direct actions, or the moment a 3-action estimate stops holding mid-flight (#4594). Non-source writes and `.git/COMMIT_EDITMSG` are unbudgeted | `engineer` |
| Deep investigation | `Grep`/`Glob` used repeatedly | Research |
| Ticketing | `mcp__mcp-ticketer__*`, `mcp__github__*` issue/PR tools, `WebFetch` on ticket URLs | ticketing agent (see `tm-ticketing`) |
| Browser | `mcp__claude-in-chrome__*`, `mcp__playwright__*` | web-qa |

See `tm-circuit-breaker` for the full enforcement model and `tm-delegation-patterns` for agent selection.