The `debug` Tool
Relevant source files
The following files were used as context for generating this wiki page:
The debug tool provides a structured and systematic workflow for root cause analysis of complex bugs, performance issues, and other software problems. Unlike a simple chat interaction, it guides the AI agent through methodical investigation steps, ensuring thorough code examination and evidence gathering before reaching a conclusion. It is designed to handle a wide range of issues, including race conditions, memory leaks, and integration problems.
This tool enforces a multi-step process with forced pauses, preventing rushed analysis. It supports hypothesis evolution, confidence tracking, and can integrate with external "expert" models for deeper analysis, making it a core component of the Zen MCP server's code analysis and quality suite.
Sources: tools/debug.py:1-15, 110-118, README.md:154-155
Architecture and Core Components
The debug tool is built upon the WorkflowTool base class, inheriting its structure for managing multi-step, stateful interactions. Its architecture is composed of three main parts: the tool implementation, the data model for requests, and the system prompt that guides the AI's behavior.
Sources: tools/debug.py:108, tools/workflow/base.py
The diagram below shows the class hierarchy for the debug tool.
Key Components
| Component | File | Description |
|---|---|---|
DebugIssueTool | tools/debug.py | The main class that implements the debugging workflow, inheriting from WorkflowTool. It orchestrates the investigation steps and expert analysis calls. |
DebugInvestigationRequest | tools/debug.py | A Pydantic model that defines the structured input required for each step of the debugging process. |
DEBUG_ISSUE_PROMPT | systemprompts/debug_prompt.py | The system prompt that instructs the AI agent on its role as a debugging assistant and defines the required JSON output format for its analysis. |
Sources: tools/debug.py:70, 108, systemprompts/debug_prompt.py:5-12
The Debugging Workflow
The debug tool operates as a stateful, multi-step workflow. It forces the agent to pause and perform offline investigation between steps, ensuring that analysis is based on concrete evidence rather than speculation. The workflow's progression is controlled by the next_step_required flag and the confidence level reported by the agent.
This flowchart illustrates the systematic investigation process managed by the debug tool.
A key feature is the mandatory pause between steps. The tool provides explicit instructions on what to investigate next, such as "Examine the specific files you've identified" or "Trace method calls and data flow". The agent cannot proceed to the next step without performing this investigation and returning with new findings.
Sources: tools/debug.py:284-316
Data Model: DebugInvestigationRequest
All interactions with the debug tool are structured via the DebugInvestigationRequest model. This ensures that the agent provides all necessary information at each step of the investigation.
| Parameter | Type | Description |
|---|---|---|
step | str | A textual description of the investigation performed in the current step. |
step_number | int | The index of the current step, starting at 1. |
total_steps | int | The agent's estimate of the total steps required for the investigation. |
next_step_required | bool | If False, the investigation loop terminates and proceeds to final analysis. |
findings | str | Specific discoveries, code/log evidence, or disproven theories from the step. |
files_checked | list[str] | A list of all absolute file paths examined during the investigation. |
relevant_files | list[str] | A subset of files_checked that are directly relevant to the issue. |
relevant_context | list[str] | Central methods or functions related to the issue (e.g., 'Class.method'). |
hypothesis | Optional[str] | A concrete theory about the root cause, based on evidence. |
confidence | Optional[str] | The agent's confidence in the hypothesis. Can be exploring, low, medium, high, very_high, almost_certain, or certain. |
images | Optional[list[str]] | Optional paths to screenshots or other visuals that clarify the issue. |
Sources: tools/debug.py:19-94
System Prompt and AI Role
The systemprompts/debug_prompt.py file defines the core behavior of the AI agent when using the debug tool. It instructs the agent to act as an "expert debugging assistant" that analyzes systematic investigation findings provided by another agent.
The prompt requires the AI to respond in a structured JSON format. If the analysis is complete, the JSON object must contain the following key fields.
| JSON Key | Description |
|---|---|
status | Must be analysis_complete. |
summary | A brief description of the problem and its impact. |
investigation_steps | A list of steps detailing how the analysis was performed. |
hypotheses | A list of ranked hypotheses, each with a root cause, evidence, and a minimal fix. |
key_findings | Important discoveries made during the analysis. |
immediate_actions | Steps to take regardless of which hypothesis is correct. |
prevention_strategy | Optional measures to prevent the issue from recurring. |
Sources: systemprompts/debug_prompt.py:5-12, 65-103
Expert Analysis Integration
The debug tool can leverage an external, "expert" model for a second opinion or deeper analysis. This is triggered automatically when the investigation is complete (next_step_required is False), unless the agent has declared certain confidence.
The should_skip_expert_analysis method explicitly prevents this external call if confidence is 'certain', trusting the agent's local analysis.
Sources: tools/debug.py:360-363, 228-237
The following sequence diagram shows the interaction when expert analysis is engaged.
When calling the expert, the prepare_expert_analysis_context method compiles a comprehensive prompt including the initial issue, a summary of investigation steps, error context, relevant code, and the evolution of hypotheses.
Sources: tools/debug.py:243-294
Usage Example
The following is a basic example of how to initiate a debugging session.
Use debug to investigate [error description] in [file path].
For more complex scenarios involving context:
Use debug with model o3 to analyze this error:
[paste error message]
Context: The error occurs when [scenario description].
Sources: examples/prompts/tool-usage-examples.md:30-39
Conclusion
The debug tool is a powerful feature of the Zen MCP server that formalizes the debugging process. By enforcing a structured, evidence-based workflow, it improves the quality and reliability of root cause analysis. Its ability to pause for investigation, track confidence, and optionally integrate expert models makes it suitable for diagnosing even the most complex and elusive bugs in a software project.
Sources: tools/debug.py:1-15, 110-118, systemprompts/debug_prompt.py:5-12