The `consensus` Tool
Relevant source files
The following files were used as context for generating this wiki page:The consensus tool is a powerful workflow designed to facilitate complex decision-making by gathering and synthesizing perspectives from multiple AI models. It orchestrates a structured debate where different models can be assigned specific stances (e.g., "for," "against," "neutral") to evaluate a technical proposition, architectural choice, or feature proposal. This process helps surface diverse viewpoints, identify potential risks, and build a comprehensive recommendation.
The tool operates as a step-by-step workflow. It begins with an initial analysis by the primary agent, followed by parallel consultations with a user-defined roster of models. Each model provides its assessment in isolation, based only on the original proposal. Finally, the tool aggregates these responses, enabling the primary agent to synthesize a final, well-rounded conclusion. This structured approach is ideal for complex decisions where multiple trade-offs must be considered.
Sources: tools/consensus.py:10-20, README.md:120-121
Architecture and Workflow
The consensus tool follows a multi-step, parallel processing workflow to gather insights from various AI models. The process is managed by the ConsensusTool class, which inherits from WorkflowTool.
High-Level Workflow
The diagram below illustrates the end-to-end process of the consensus tool, from the initial user request to the final synthesis of model responses.
This diagram shows the two main stages: initial analysis followed by parallel model consultations, and the final synthesis stage where all feedback is combined.
Sources: tools/consensus.py:431-488
Key Components
The tool is built around two primary classes: ConsensusTool and ConsensusRequest.
This diagram illustrates that ConsensusTool extends the base WorkflowTool and uses the ConsensusRequest data model for its inputs.
Sources: tools/consensus.py:70, tools/consensus.py:155
Input Data Model: ConsensusRequest
The consensus tool's behavior is configured through the ConsensusRequest Pydantic model. This model validates the input arguments for each step of the workflow.
| Field | Type | Description |
|---|---|---|
step | str | The exact proposal/question for the models. For subsequent steps, it captures internal notes. |
step_number | int | The current step index, starting at 1. |
total_steps | int | Total steps in the workflow. |
next_step_required | bool | True if more steps remain; False when ready for synthesis. |
findings | str | In Step 1, the agent's independent analysis. In later steps, a summary of the latest model's response. |
models | list[dict] | Required in Step 1. A list of models to consult. Each entry can specify model, stance, and stance_prompt. |
relevant_files | list[str] | Optional list of absolute file paths to provide context to the models. |
images | list[str] | Optional list of absolute image paths or base64 strings for visual context. |
current_model_index | int | Internal 0-based index tracking the next model to consult. |
model_responses | list[dict] | Internal log of responses gathered from models. |
Sources: tools/consensus.py:73-149, tests/test_consensus.py:28-43
A key validation rule ensures that the models field is provided in the first step and that each model and stance combination is unique.
Sources: tools/consensus.py:121-138
Stance-Based Analysis
A core feature of the consensus tool is its ability to steer model responses using predefined stances. This is achieved by injecting a specific "perspective framework" into the system prompt for each model consultation. The _get_stance_enhanced_prompt method is responsible for selecting the appropriate prompt fragment.
Sources: tools/consensus.py:648-735
| Stance | Objective |
|---|---|
for | Advocate for the proposal, identify strengths, and propose solutions to overcome challenges. Must act in good faith and refuse to support genuinely bad ideas. |
against | Critique the proposal by identifying risks, complexities, and alternatives. Must not be contrarian for its own sake and must acknowledge sound ideas. |
neutral | Provide a balanced and objective analysis, weighing pros and cons based on the evidence. Avoids artificial 50/50 splits if evidence strongly favors one side. |
Sources: tools/consensus.py:654-735
Stance Prompt Example (against)
The following is the prompt fragment used for the against stance, which instructs the model on how to perform its critique responsibly.
# From tools/consensus.py
"CRITICAL PERSPECTIVE WITH RESPONSIBILITY
You are tasked with critiquing this proposal, but with ESSENTIAL BOUNDARIES:
MANDATORY FAIRNESS CONSTRAINTS:
- You MUST NOT oppose genuinely excellent, common-sense ideas just to be contrarian
- You MUST acknowledge when a proposal is fundamentally sound and well-conceived
- You CANNOT give harmful advice or recommend against beneficial changes
- If the idea is outstanding, say so clearly while offering constructive refinements
...
YOUR CRITICAL ANALYSIS SHOULD:
- Identify legitimate risks and failure modes
- Point out overlooked complexities
- Suggest more efficient alternatives
- Highlight potential negative consequences
- Question assumptions that may be flawed
Remember: Being "against" means rigorous scrutiny to ensure quality, not undermining good ideas that deserve support."
Sources: tools/consensus.py:683-711
Model Consultation Process
The _consult_model async method orchestrates the interaction with each individual AI model. It ensures that each consultation is independent and based on the original proposal.
This sequence diagram shows the flow of a single model consultation.
This diagram shows that ConsensusTool retrieves a provider, constructs a stance-specific prompt, and calls the model. The consultation is "blinded," meaning models do not see each other's responses.
Sources: tools/consensus.py:575-646
Mandatory Response Format
All models consulted by the consensus tool are instructed to reply in a specific Markdown format. This ensures that responses are structured, consistent, and easy to parse and synthesize.
The required format is defined in the CONSENSUS_PROMPT.
## Verdict
Provide a single, clear sentence summarizing your overall assessment...
## Analysis
Provide detailed assessment addressing each point in the evaluation framework...
## Confidence Score
Provide a numerical score from 1 (low confidence) to 10 (high confidence)...
Format: "X/10 - [brief justification]"
## Key Takeaways
Provide 3-5 bullet points highlighting the most critical insights, risks, or recommendations...
Sources: systemprompts/consensus_prompt.py:84-106, tests/gemini_cassettes/consensus/step2_gemini25_flash_against/mldev.json, tests/openai_cassettes/consensus_step1_gpt5_for.json
Final Output and Synthesis
After all models have been consulted in parallel, the execute_workflow method aggregates the responses. The final output is a JSON object that includes the agent's initial analysis and the complete set of model responses.
| Field | Description |
|---|---|
status | Set to consensus_workflow_complete. |
agent_analysis | Contains the initial_analysis and findings from the primary agent in Step 1. |
complete_consensus | A summary object containing the initial_prompt, a list of models_consulted, and total_responses. |
accumulated_responses | A list of objects, where each object contains the model, stance, status, and verdict (the full Markdown response) from one of the consulted models. |
next_steps | Instructions for the primary agent to synthesize the results, highlighting points of agreement and disagreement and forming a final recommendation. |
Sources: tools/consensus.py:456-488
The workflow concludes by instructing the primary agent to perform the synthesis, turning the raw model outputs into a single, actionable conclusion.
Summary
The consensus tool provides a robust and structured framework for leveraging multiple AI models to analyze complex topics. By using parallel consultations, stance-based prompting, and a mandatory response format, it ensures that the final synthesis is based on a diverse and well-reasoned set of expert opinions. This makes it an invaluable tool for making high-stakes technical and architectural decisions within the Zen MCP ecosystem.
Sources: README.md:120-121, tools/consensus.py:10-20