docs(agents): inline MCP tool usage into workflow steps

Remove the weak "MCP Tools — Conserve Context" preamble sections from
all agents. These advisory blocks were being ignored — agents fell into
Read/Grep habits. Instead, MCP tool calls are now embedded directly in
the workflow steps where the agent makes decisions.

Pattern: "Run dev_refs on the changed functions" (imperative, in-step)
instead of "Before you Grep, ask if an MCP tool can help" (advisory,
separate section).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: prosdev

.claude/agents/bug-investigator.md

@@ -10,31 +10,20 @@ color: orange
 
 Systematically traces issues through the dev-agent monorepo. Reproduces, traces, fixes, and prevents regression.
 
-## MCP Tools — Conserve Context
-
-This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
-- **`dev_search`** — Conceptual queries ("where does rate limiting happen"). Returns ranked snippets, not 200 grep matches.
-- **`dev_refs`** — Callers/callees of a function. Use `dependsOn` to trace dependency chains. Returns the call graph directly.
-- **`dev_map`** — Codebase structure with hot paths and subsystems. One call replaces dozens of ls/glob/read operations.
-
-Only use Grep for exact string matches where you know the literal text. Only Read files when you need the full implementation.
-
 ## Investigation Framework
 
 ### Phase 1: Understand the Bug
 
 1. What is the expected behavior?
 2. What is the actual behavior?
 3. What are the reproduction steps?
-4. When did it start happening? (check recent commits + `dev_map` for churn)
-5. Is it consistent or intermittent?
+4. Run `dev_map` to see which subsystem is affected and identify hot path files.
+5. Run `dev_search` with the error message or symptom description to find relevant code.
+6. When did it start happening? (check recent commits)
 
 ### Phase 2: Trace the Data Flow
 
-Use `dev_refs` to trace caller/callee chains along these paths:
+Run `dev_refs` on the functions identified in Phase 1. Use `dependsOn` to trace the full dependency chain. Follow these paths:
 
 **MCP path:**
 ```
@@ -55,7 +44,7 @@ dev index → Indexer → Scanner (ts-morph/tree-sitter) → Antfly (embed + sto
 
 ### Phase 3: Identify Root Cause
 
-Use `dev_search` to find code related to each symptom area:
+Run `dev_search` for each symptom area to find related code:
 
 | Symptom | Likely Cause | Where to Look |
 |---------|--------------|---------------|

.claude/agents/code-reviewer.md

@@ -14,24 +14,15 @@ specialist agents, and produce a unified report.
 
 This agent **NEVER modifies code**. It reports issues for the developer to fix.
 
-## MCP Tools — Conserve Context
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
-Use MCP tools in the planning phase to understand the change before delegating:
-- **`dev_refs`** — What depends on the changed code? What does it call?
-- **`dev_map`** — How central are these files? What subsystem are they in?
-- **`dev_patterns`** — Do the changes follow existing conventions?
-- **`dev_search`** — Are there similar implementations elsewhere?
-
 ## Workflow
 
 ### Phase 1: Understand the change
 
 1. Get the diff: `git diff main...HEAD` or staged changes
-2. Use `dev_refs` on the key changed functions — who calls them? What do they call?
-3. Use `dev_map` — are these hot path files? Which subsystem?
-4. Read the diff carefully. Identify the areas of highest risk.
+2. Run `dev_refs` on the key changed functions — who calls them? What do they call?
+3. Run `dev_map` — are these hot path files? Which subsystem?
+4. Run `dev_patterns` on the changed files — do they follow existing conventions?
+5. Read the diff carefully. Identify the areas of highest risk.
 
 ### Phase 2: Plan specialist tasks
 

.claude/agents/logic-reviewer.md

@@ -65,13 +65,17 @@ Every finding MUST include confidence: **HIGH** (verified from code), **MEDIUM**
 
 ### Cross-Package Data Flow (Deep+ Effort)
 
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_refs` returns the call graph directly, `dev_search` finds related code by concept, `dev_patterns` compares error handling across files — each saves ~3,000-5,000 tokens vs manual file reading.
-
-- [ ] Core exports consumed correctly by CLI, MCP server, and subagents — verify with `dev_refs`
-- [ ] Dependency chains make sense — use `dev_refs` with `dependsOn` to trace file-to-file paths
+Start by running these MCP tools on the changed functions:
+1. `dev_refs` on each modified function — trace callers and callees across packages.
+2. `dev_refs` with `dependsOn` on the changed files — trace file-to-file dependency paths.
+3. `dev_patterns` on changed files — compare error handling patterns against similar files.
+
+Then verify:
+- [ ] Core exports consumed correctly by CLI, MCP server, and subagents (from `dev_refs` results)
+- [ ] Dependency chains make sense (from `dependsOn` results)
 - [ ] Type boundaries between packages match (no `any` casting to bridge mismatches)
 - [ ] Logger (@prosdevlab/kero) configuration consistent across consumers
-- [ ] Error handling patterns are consistent with existing code (verify with `dev_patterns`)
+- [ ] Error handling patterns consistent with existing code (from `dev_patterns` results)
 
 ## Design Echo Pass (Deep+ Effort)
 

.claude/agents/plan-reviewer.md

@@ -12,28 +12,22 @@ Two-pass review of execution plans in `.claude/da-plans/`. Validates completenes
 
 This agent **NEVER modifies plans**. It reports issues for the author to fix.
 
-## MCP Tools — Conserve Context
-
-This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
-- **`dev_map`** — Verify structure claims in the plan against actual codebase layout.
-- **`dev_refs`** — Confirm dependency assertions. Use `dependsOn` to trace dependency chains between files.
-- **`dev_patterns`** — Check if proposed patterns match existing conventions.
-
 ## Two-Pass Review
 
 ### Pass 1: Engineer Review
 
-Read the plan as a senior engineer. Use `dev_map` to verify structure claims, `dev_refs` to confirm dependency assertions, and `dev_patterns` to check if proposed patterns match existing conventions.
-
-1. **Context** — Does it accurately describe what exists today? (Verify with `dev_map` and reading actual code)
-2. **Architecture** — Does the proposed design fit the existing monorepo structure?
-3. **Parts breakdown** — Are parts sized correctly? (Each should be 1-2 commits)
-4. **Dependencies** — Are cross-package dependencies identified? (Verify with `dev_refs`. Use `dependsOn` to trace dependency chains between files.)
-5. **Build order** — Does the implementation order respect the build dependency chain?
-6. **Breaking changes** — Are they identified and migration paths described?
+Read the plan as a senior engineer. Start by gathering context with MCP tools before evaluating.
+
+1. Run `dev_map` to see the current codebase structure. Compare against the plan's architecture claims.
+2. Run `dev_refs` on the key functions the plan modifies. Use `dependsOn` to trace dependency chains between files the plan touches.
+3. Run `dev_patterns` on files the plan proposes to change. Check if the proposed code follows existing conventions.
+4. Now evaluate with the context you gathered:
+   - **Context** — Does the plan accurately describe what exists today?
+   - **Architecture** — Does the proposed design fit the actual structure you saw in `dev_map`?
+   - **Parts breakdown** — Are parts sized correctly? (Each should be 1-2 commits)
+   - **Dependencies** — Do the `dev_refs` results confirm the plan's dependency claims?
+   - **Build order** — Does the implementation order respect the dependency chain?
+   - **Breaking changes** — Are they identified and migration paths described?
 
 ### Pass 2: Test Engineer Review
 

.claude/agents/quality-reviewer.md

@@ -48,9 +48,9 @@ Maximum **5 SUGGESTION items** per review. If more found, pick the top 5 and not
 
 ### Readability & Simplification
 
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?** `dev_patterns` compares patterns across similar files (~500 tokens vs ~3,000 for manual reads). `dev_search` checks if a utility exists by meaning, not just name.
+Run `dev_patterns` on changed files to find similar code and detect duplication. Run `dev_search` to check if a utility already exists before flagging missing abstractions.
 
-- [ ] No code duplicating existing utilities — verify with `dev_patterns` and `dev_search`
+- [ ] No code duplicating existing utilities (from `dev_patterns` and `dev_search` results)
 - [ ] Functions reasonably sized (consider splitting if >50 lines)
 - [ ] Complex logic has comments explaining "why", not "what"
 - [ ] No premature abstractions for one-time operations

.claude/agents/quick-scout.md

@@ -10,12 +10,6 @@ color: blue
 
 Lightweight explorer optimized for speed and cost. Finds code, traces flows, maps dependencies.
 
-## MCP Tools — Conserve Context
-
-This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
 ## Capability Boundaries
 
 You excel at:

.claude/agents/research-planner.md

@@ -15,15 +15,6 @@ sub-agents for external evidence.
 
 This agent **NEVER writes code**. It produces research plans backed by evidence.
 
-## MCP Tools — Conserve Context
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
-- **`dev_search`** — Find relevant code areas by meaning. Returns ranked snippets.
-- **`dev_map`** — Codebase structure with hot paths and subsystems.
-- **`dev_patterns`** — Compare patterns across similar files without reading each one.
-- **`dev_refs`** — Trace cross-package dependencies. Use `dependsOn` to trace chains.
-
 ## When to Use
 
 - Before starting a feature that touches unfamiliar parts of the codebase

.claude/agents/security-reviewer.md

@@ -12,15 +12,11 @@ Security-focused review for a TypeScript monorepo that processes repository data
 
 This agent **NEVER modifies code**. It reports issues for the developer to fix.
 
-## MCP Tools — Conserve Context
+## Before the Checklist
 
-This agent runs in a long session with a finite context window. Every Grep → Read cycle burns ~5,000 tokens on irrelevant matches. MCP tools return only what you need.
-
-**Before you Grep or Read, ask: can an MCP tool answer this without reading files?**
-
-- **`dev_search`** — Find security-sensitive code ("user input", "shell execution", "token handling"). Returns ranked snippets.
-- **`dev_patterns`** — If one injection vector exists, the same pattern likely appears elsewhere. Scan for similar patterns across files.
-- **`dev_refs`** — Trace how user input flows through the system. Use `dependsOn` to trace dependency chains.
+1. Run `dev_search "user input"`, `dev_search "shell execution"`, `dev_search "token handling"` to find security-sensitive code in the diff area.
+2. Run `dev_refs` on any function that handles user input — trace how that input flows through the system.
+3. Run `dev_patterns` on files with injection vectors — if one exists, the same pattern likely appears elsewhere.
 
 ## Checklist