Pal MCP Toolkit

The Pal MCP toolkit provides specialized tools for comprehensive code analysis and development workflows. Each tool follows a multi-step workflow pattern with expert validation.

Quick Reference: Tool Selection

Task Type	Tool	Reference
Architecture & code analysis before complex tasks	mcp__zen__analyze	analyze.md
Bug investigation & root cause analysis	mcp__zen__debug	debug.md
Strategic planning & task breakdown	mcp__zen__planner	planner.md
Code smell detection & refactoring	mcp__zen__refactor	refactor.md
Code review after completing tasks	mcp__zen__codereview	review.md
Execution flow & dependency tracing	mcp__zen__tracer	tracer.md

Critical Workflow Requirements

Mandatory Completion Rules

• NEVER stop a workflow before next_step_required: false is returned
• ALWAYS increment step_number and call the tool again when next_step_required: true
• TASK INVALIDATION: Incomplete workflows result in immediate task rejection
• NO EXCEPTIONS: Even if analysis seems complete after step 1, you MUST complete all steps

Model Requirement

• MANDATORY: Always use model: "anthropic/claude-opus-4.6" for ALL Pal MCP tool calls
• NEVER use any other model when calling Pal MCP tools

Workflow Validation Checklist

1. Check next_step_required in every response
2. If true, call the tool again with incremented step_number
3. Never proceed with implementation while next_step_required: true
4. Workflow is complete ONLY when next_step_required: false

Tool Overview

Analyze (mcp__zen__analyze)

When to Use:

• Before complex tasks to understand existing architecture
• Architecture review and system design assessment
• Performance, security, and technical debt analysis

Key Parameters:

• analysis_type: "architecture" | "performance" | "security" | "quality" | "general"
• output_format: "summary" | "detailed" | "actionable"

See references/analyze.md for complete documentation.

---

Debug (mcp__zen__debug)

When to Use:

• Bug investigation and root cause analysis
• Performance issues, memory leaks, race conditions
• Integration failures and service communication problems

Key Parameters:

• hypothesis: Current theory about the root cause
• confidence: "exploring" | "low" | "medium" | "high" | "very_high" | "almost_certain" | "certain"

See references/debug.md for complete documentation.

---

Planner (mcp__zen__planner)

When to Use:

• Breaking down complex tasks into manageable steps
• System design and architectural decisions
• Migration planning and implementation strategies

Key Parameters:

• is_step_revision: For refining previous steps
• is_branch_point: For exploring alternative approaches
• branch_id: Naming alternative approaches

See references/planner.md for complete documentation.

---

Refactor (mcp__zen__refactor)

When to Use:

• Addressing code smells and technical debt
• Decomposing large modules or classes
• Modernizing legacy patterns

Key Parameters:

• refactor_type: "codesmells" | "decompose" | "modernize" | "organization"
• focus_areas: ["performance", "readability", "maintainability", "security"]

See references/refactor.md for complete documentation.

---

Code Review (mcp__zen__codereview)

When to Use:

• After completing a task (MANDATORY)
• Before submitting pull requests
• Validating implementation against project standards

Key Parameters:

• review_type: "full" for comprehensive analysis
• severity_filter: "all" to catch all severity levels
• focus_on: Specific areas like "performance", "security", "type-safety"

See references/review.md for complete documentation.

---

Tracer (mcp__zen__tracer)

When to Use:

• Understanding code execution paths
• Mapping dependencies before refactoring
• Debugging complex flows

Key Parameters:

• trace_mode: "precision" (execution flow) | "dependencies" (structural analysis) | "ask"
• target_description: Clear description of what to trace and why

See references/tracer.md for complete documentation.

Common Required Parameters

All Pal MCP tools require these base parameters:

{
  "step": "Description of current step",
  "step_number": 1,
  "total_steps": 2,
  "next_step_required": true,
  "findings": "Findings from this step",
  "model": "anthropic/claude-opus-4.6"
}

File Path Requirements

• ALWAYS use full absolute paths for relevant_files
• Include files directly involved in the analysis
• Include related files that provide context
• Include test files when relevant

Typical Workflow Pattern

1. Start: Call the tool with step_number: 1 and initial strategy
2. Iterate: Increment step_number and refine findings based on previous step
3. Continue: Keep calling until next_step_required: false
4. Complete: Only proceed with implementation after workflow completes

Violation Examples (Task Rejection)

• Calling a Pal tool once and proceeding to implementation
• Skipping steps because analysis seems complete
• Starting implementation before next_step_required: false
• Using a model other than anthropic/claude-opus-4.6