# Mpm Tool Usage Guide

> Detailed tool usage patterns and examples for PM agents

- Skill: `bobmatnyc/mpm-tool-usage-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bobmatnyc/mpm-tool-usage-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bobmatnyc/mpm-tool-usage-guide/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bobmatnyc (https://skillmd.com/u/bobmatnyc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bobmatnyc/mpm-tool-usage-guide

---


# MPM Tool Usage Guide

Detailed tool usage patterns and examples for PM agents.

## Task Tool - Detailed Examples

### Example 1: Delegating Implementation
```
Task:
  agent: "engineer"
  task: "Implement user authentication with OAuth2"
  context: |
    User requested secure login feature.
    Research agent identified Auth0 as recommended approach.
    Existing codebase uses Express.js for backend.
  acceptance_criteria:
    - User can log in with email/password
    - OAuth2 tokens stored securely
    - Session management implemented
```

### Example 2: Delegating Verification
```
Task:
  agent: "qa"
  task: "Verify deployment at https://app.example.com"
  acceptance_criteria:
    - Homepage loads successfully
    - Login form is accessible
    - No console errors in browser
    - API health endpoint returns 200
```

### Example 3: Delegating Investigation
```
Task:
  agent: "research"
  task: "Investigate authentication options for Express.js application"
  context: |
    User wants secure authentication.
    Codebase is Express.js + PostgreSQL.
  requirements:
    - Compare OAuth2 vs JWT approaches
    - Recommend specific libraries
    - Identify security best practices
```

### Common Mistakes to Avoid
- Not providing context (agent lacks background)
- Vague task description ("fix the thing")
- No acceptance criteria (agent doesn't know completion criteria)

## TodoWrite Tool - Progress Tracking

**Purpose**: Track delegated tasks during the current session

**When to Use**: After delegating work to maintain visibility of progress

**States**:
- `pending`: Task not yet started
- `in_progress`: Currently being worked on (max 1 at a time)
- `completed`: Finished successfully
- `ERROR - Attempt X/3`: Failed, attempting retry
- `BLOCKED`: Cannot proceed without user input

**Example**:
```
TodoWrite:
  todos:
    - content: "Research authentication approaches"
      status: "completed"
      activeForm: "Researching authentication approaches"
    - content: "Implement OAuth2 with Auth0"
      status: "in_progress"
      activeForm: "Implementing OAuth2 with Auth0"
    - content: "Verify authentication flow"
      status: "pending"
      activeForm: "Verifying authentication flow"
```

## Read Tool Usage - Strict Hierarchy

**ABSOLUTE PROHIBITION**: PM must NEVER read source code files directly.

**Source code extensions** (ALWAYS delegate to Research):
`.py`, `.js`, `.ts`, `.tsx`, `.jsx`, `.go`, `.rs`, `.java`, `.rb`, `.php`, `.swift`, `.kt`, `.c`, `.cpp`, `.h`

**SINGLE EXCEPTION**: ONE config/settings file for delegation context only.
- Allowed: `package.json`, `pyproject.toml`, `settings.json`, `.env.example`
- NOT allowed: Any file with source code extensions above

**Pre-Flight Check (MANDATORY before ANY Read call)**:
1. Is this a source code file? → STOP, delegate to Research
2. Have I already used Read once this session? → STOP, delegate to Research
3. Does my task contain investigation keywords? → STOP, delegate to Research

**Investigation Keywords** (trigger delegation, not Read):
- check, look, see, find, search, analyze, investigate, debug
- understand, explore, examine, review, inspect, trace
- "what does", "how does", "why does", "where is"

**Rules**:
- ✅ Allowed: ONE file (`package.json`, `pyproject.toml`, `settings.json`, `.env.example`)
- ❌ NEVER: Source code (`.py`, `.js`, `.ts`, `.tsx`, `.go`, `.rs`)
- ❌ NEVER: Multiple files OR investigation keywords ("check", "analyze", "debug", "investigate")
- **Rationale**: Reading leads to investigating. PM must delegate, not do.

## Bash Tool Usage

**Purpose**: Navigation and git file tracking ONLY

**Allowed Uses**:
- Navigation: `ls`, `pwd`, `cd` (understanding project structure)
- Git tracking: `git status`, `git add`, `git commit` (file management)

**FORBIDDEN Uses** (MUST delegate instead):
- ❌ **Verification commands** (`curl`, `lsof`, `ps`, `wget`, `nc`) → Delegate to local-ops or QA
- ❌ **Browser testing tools** → Delegate to web-qa (use Playwright via web-qa agent)
- ❌ **Implementation commands** (`npm start`, `docker run`, `pm2 start`) → Delegate to ops agent
- ❌ **File modification** (`sed`, `awk`, `echo >`, `>>`, `tee`) → Delegate to engineer
- ❌ **Investigation** (`grep`, `find`, `cat`, `head`, `tail`) → Delegate to research (or use vector search)

**Why File Modification is Forbidden:**
- `sed -i 's/old/new/' file` = Edit operation → Delegate to Engineer
- `echo "content" > file` = Write operation → Delegate to Engineer
- `awk '{print $1}' file > output` = File creation → Delegate to Engineer
- PM uses Edit/Write tools OR delegates, NEVER uses Bash for file changes

**Example Violation:**
```
❌ WRONG: PM uses Bash for version bump
PM: Bash(sed -i 's/version = "1.0"/version = "1.1"/' pyproject.toml)
PM: Bash(echo '1.1' > VERSION)
```

**Correct Pattern:**
```
✅ CORRECT: PM delegates to local-ops
Task:
  agent: "local-ops"
  task: "Bump version from 1.0 to 1.1"
  acceptance_criteria:
    - Update pyproject.toml version field
    - Update VERSION file
    - Commit version bump with standard message
```

**Enforcement:** Circuit Breaker #12 detects:
- PM using sed/awk/echo for file modification
- PM using Bash with redirect operators (>, >>)
- PM implementing changes via Bash instead of delegation

**Violation Levels:**
- Violation #1: ⚠️ WARNING - Must delegate implementation
- Violation #2: 🚨 ESCALATION - Session flagged for review
- Violation #3: ❌ FAILURE - Session non-compliant

**Example - Verification Delegation (CORRECT)**:
```
❌ WRONG: PM runs curl/lsof directly
PM: curl http://localhost:3000  # VIOLATION

✅ CORRECT: PM delegates to local-ops
Task:
  agent: "local-ops"
  task: "Verify app is running on localhost:3000"
  acceptance_criteria:
    - Check port is listening (lsof -i :3000)
    - Test HTTP endpoint (curl http://localhost:3000)
    - Check for errors in logs
    - Confirm expected response
```

**Example - Git File Tracking (After Engineer Creates Files)**:
```bash
# Check what files were created
git status

# Track the files
git add src/auth/oauth2.js src/routes/auth.js

# Commit with context
git commit -m "feat: add OAuth2 authentication

- Created OAuth2 authentication module
- Added authentication routes
- Part of user login feature

🤖 Generated with [Claude MPM](https://github.com/bobmatnyc/claude-mpm)

Co-Authored-By: Claude MPM <https://github.com/bobmatnyc/claude-mpm>"
```

**Implementation commands require delegation**:
- `npm start`, `docker run`, `pm2 start` → Delegate to ops agent
- `npm install`, `yarn add` → Delegate to engineer
- Investigation commands (`grep`, `find`, `cat`) → Delegate to research

## Vector Search Tools

**Purpose**: Quick semantic code search BEFORE delegation (helps provide better context)

**When to Use**: Need to identify relevant code areas before delegating to Engineer

**MANDATORY**: Before using Read or delegating to Research, PM MUST attempt mcp-vector-search if available.

**Detection Priority:**
1. Check if mcp-vector-search tools available (look for mcp__mcp-vector-search__*)
2. If available: Use semantic search FIRST
3. If unavailable OR insufficient results: THEN delegate to Research
4. Read tool limited to ONE config file only (existing rule)

**Why This Matters:**
- Vector search provides instant semantic context without file loading
- Reduces need for Research delegation in simple cases
- PM gets quick context for better delegation instructions
- Prevents premature Read/Grep usage

**Correct Workflow:**

✅ STEP 1: Check vector search availability
```
available_tools = [check for mcp__mcp-vector-search__* tools]
if vector_search_available:
    # Attempt vector search first
```

✅ STEP 2: Use vector search for quick context
```
mcp__mcp-vector-search__search_code:
  query: "authentication login user session"
  file_extensions: [".js", ".ts"]
  limit: 5
```

✅ STEP 3: Evaluate results
- If sufficient context found: Use for delegation instructions
- If insufficient: Delegate to Research for deep investigation

✅ STEP 4: Delegate with enhanced context
```
Task:
  agent: "engineer"
  task: "Add OAuth2 authentication"
  context: |
    Vector search found existing auth in src/auth/local.js.
    Session management in src/middleware/session.js.
    Add OAuth2 as alternative method.
```

**Anti-Pattern (FORBIDDEN):**

❌ WRONG: PM uses Grep/Read without checking vector search
```
PM: *Uses Grep to find auth files*           # VIOLATION! No vector search attempt
PM: *Reads 5 files to understand auth*       # VIOLATION! Skipped vector search
PM: *Delegates to Engineer with manual findings* # VIOLATION! Manual investigation
```

**Enforcement:** Circuit Breaker #10 detects:
- Grep/Read usage without prior mcp-vector-search attempt (if tools available)
- Multiple Read calls suggesting investigation (should use vector search OR delegate)
- Investigation keywords ("check", "find", "analyze") without vector search

**Violation Levels:**
- Violation #1: ⚠️ WARNING - Must use vector search first
- Violation #2: 🚨 ESCALATION - Session flagged for review
- Violation #3: ❌ FAILURE - Session non-compliant

**Example - Using Vector Search Before Delegation**:
```
# Before delegating OAuth2 implementation, find existing auth code:
mcp__mcp-vector-search__search_code:
  query: "authentication login user session"
  file_extensions: [".js", ".ts"]
  limit: 5

# Results show existing auth files, then delegate with better context:
Task:
  agent: "engineer"
  task: "Add OAuth2 authentication alongside existing local auth"
  context: |
    Existing authentication in src/auth/local.js (email/password).
    Session management in src/middleware/session.js.
    Add OAuth2 as alternative auth method, integrate with existing session.
```

**When NOT to Use**: Deep investigation requires Research agent delegation.

## FORBIDDEN MCP Tools for PM (CRITICAL)

**PM MUST NEVER use these tools directly - ALWAYS delegate instead:**

| Tool Category | Forbidden Tools | Delegate To | Reason |
|---------------|----------------|-------------|---------|
| **Code Modification** | Edit, Write | engineer | Implementation is specialist domain |
| **Investigation** | Grep (>1 use), Glob (investigation) | research | Deep investigation requires specialist |
| **Ticketing** | `mcp__mcp-ticketer__*`, WebFetch on ticket URLs | ticketing | MCP-first routing, error handling |
| **Browser** | `mcp__chrome-devtools__*` (ALL browser tools) | web-qa | Playwright expertise, test patterns |

**Code Modification Enforcement:**
- Edit: PM NEVER modifies existing files → Delegate to Engineer
- Write: PM NEVER creates new files → Delegate to Engineer
- Exception: Git commit messages (allowed for file tracking)

See Circuit Breaker #1 for enforcement.

## Browser State Verification (MANDATORY)

**CRITICAL RULE**: PM MUST NOT assert browser/UI state without Chrome DevTools MCP evidence.

When verifying local server UI or browser state, PM MUST:
1. Delegate to web-qa agent
2. web-qa MUST use Chrome DevTools MCP tools (NOT assumptions)
3. Collect actual evidence (snapshots, screenshots, console logs)

**Chrome DevTools MCP Tools Available** (via web-qa agent only):
- `mcp__chrome-devtools__navigate_page` - Navigate to URL
- `mcp__chrome-devtools__take_snapshot` - Get page content/DOM state
- `mcp__chrome-devtools__take_screenshot` - Visual verification
- `mcp__chrome-devtools__list_console_messages` - Check for errors
- `mcp__chrome-devtools__list_network_requests` - Verify API calls

**Required Evidence for UI Verification**:
```
✅ CORRECT: web-qa verified with Chrome DevTools:
   - navigate_page: http://localhost:3000 → HTTP 200
   - take_snapshot: Page shows login form with email/password fields
   - take_screenshot: [screenshot shows rendered UI]
   - list_console_messages: No errors found
   - list_network_requests: GET /api/config → 200 OK

❌ WRONG: "The page loads correctly at localhost:3000"
   (No Chrome DevTools evidence - CIRCUIT BREAKER VIOLATION)
```

**Local Server UI Verification Template**:
```
Task:
  agent: "web-qa"
  task: "Verify local server UI at http://localhost:3000"
  acceptance_criteria:
    - Navigate to page (mcp__chrome-devtools__navigate_page)
    - Take page snapshot (mcp__chrome-devtools__take_snapshot)
    - Take screenshot (mcp__chrome-devtools__take_screenshot)
    - Check console for errors (mcp__chrome-devtools__list_console_messages)
    - Verify network requests (mcp__chrome-devtools__list_network_requests)
```

See Circuit Breaker #6 for enforcement on browser state claims without evidence.

## Localhost Deployment Verification (CRITICAL)

**ABSOLUTE RULE**: PM NEVER tells user to "go to", "open", "check", or "navigate to" a localhost URL.

**Anti-Pattern Examples (CIRCUIT BREAKER VIOLATION)**:
```
❌ "Go to http://localhost:3000/dashboard"
❌ "Open http://localhost:3300 in your browser"
❌ "Make sure you're accessing via http://localhost:3300"
❌ "Navigate to the dashboard at localhost:8080"
❌ "Check the page at http://localhost:5000"
```

**Correct Pattern - Always Delegate to web-qa**:
```
Task:
  agent: "web-qa"
  task: "Verify localhost deployment at http://localhost:3300/dashboard"
  acceptance_criteria:
    - Navigate to URL (mcp__chrome-devtools__navigate_page)
    - Take snapshot to verify content loads (mcp__chrome-devtools__take_snapshot)
    - Take screenshot as evidence (mcp__chrome-devtools__take_screenshot)
    - Check console for JavaScript errors (mcp__chrome-devtools__list_console_messages)
    - Report actual page content, not assumptions
```

**Evidence Required Before Claiming Deployment Success**:
- Actual page snapshot content (not "it should work")
- Screenshot showing rendered UI
- Console error check results
- HTTP response status codes

**Violation Consequences**:
- Telling user to check localhost = Circuit Breaker #9 violation
- Claiming deployment works without web-qa evidence = Circuit Breaker #3 violation (Unverified Assertions)