The `chat` Tool

Relevant source files

The following files were used as context for generating this wiki page:

• tools/chat.py
• systemprompts/chat_prompt.py
• systemprompts/generate_code_prompt.py
• README.md
• tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json
• tools/CLAUDE.md

The chat tool is a core collaborative component within the Zen MCP Server ecosystem. It functions as a general-purpose conversational partner for developers, designed for brainstorming, validating ideas, getting second opinions, and exploring technical problems. The tool acts as an interface to external AI models, supporting multi-turn conversations with context preservation through file attachments, images, and conversation continuation IDs.

A key feature of the chat tool is its ability to facilitate structured code generation. When used with a capable model, it can produce complete code implementations based on a user's prompt. This makes it more than just a discussion partner; it's an active participant in the development process, capable of generating actionable code artifacts. Other tools within the project include thinkdeep for deeper analysis and consensus for multi-model debates.

Sources: tools/chat.py:5-11, README.md:129-133, tools/CLAUDE.md:11-13

Architecture and Class Structure

The chat tool is implemented as the ChatTool class, which inherits from the SimpleTool base class. This inheritance provides a standardized structure for tool implementation, including request handling, prompt preparation, and response formatting. The ChatTool is designed as a drop-in replacement for a previous implementation, ensuring behavioral compatibility while leveraging a more maintainable architecture.

Sources: tools/chat.py:60-68

The diagram below illustrates the class hierarchy and the main data model used by the ChatTool.

Core Functionality

The primary function of the chat tool is to process a user's request, send it to a specified AI model, and format the model's response for the calling agent.

System Prompt and Persona

The tool's behavior is guided by a detailed system prompt that defines its persona as a "senior engineering thought-partner." The goal is to collaborate with another AI agent to brainstorm, validate ideas, and offer well-reasoned second opinions.

The prompt establishes several key principles for the AI's interaction:

Guideline Category	Description
Scope & Focus	Ground suggestions in the project's tech stack, avoid over-engineering, and keep proposals practical.
Collaboration Approach	Treat the other agent as a peer, engage deeply with input, examine edge cases, and challenge assumptions constructively.
Brainstorming Guidelines	Offer multiple strategies only when beneficial, surface pitfalls early, and evaluate scalability and maintainability.
Information Requests	Provides a structured JSON format to request additional files if more context is needed to proceed.

Sources: systemprompts/chat_prompt.py:5-59

Request Data Model

All requests to the chat tool must conform to the ChatRequest Pydantic model. This model structures the input, ensuring all necessary information is provided.

Field	Type	Description
prompt	str	The user's question or idea. It is the main input for the AI model.
absolute_file_paths	Optional[list[str]]	A list of full, absolute file paths to provide code context to the model.
images	Optional[list[str]]	A list of image paths or base64 strings for visual context.
working_directory_absolute_path	str	The absolute path to an existing directory where generated code artifacts will be saved.

Sources: tools/chat.py:44-57

Here is the Pydantic model definition:

# tools/chat.py:44-57

class ChatRequest(ToolRequest):
    """Request model for Chat tool"""

    prompt: str = Field(..., description=CHAT_FIELD_DESCRIPTIONS["prompt"])
    absolute_file_paths: Optional[list[str]] = Field(
        default_factory=list,
        description=CHAT_FIELD_DESCRIPTIONS["absolute_file_paths"],
    )
    images: Optional[list[str]] = Field(default_factory=list, description=CHAT_FIELD_DESCRIPTIONS["images"])
    working_directory_absolute_path: str = Field(
        ...,
        description=CHAT_FIELD_DESCRIPTIONS["working_directory_absolute_path"],
    )

Code Generation Workflow

A significant capability of the chat tool is its ability to handle structured code generation. This feature is activated when the tool is used with a model that has the allow_code_generation capability. The workflow is governed by the GENERATE_CODE_PROMPT, which instructs the model to wrap substantial code output in a specific XML-like format.

Sources: tools/chat.py:91-94, systemprompts/generate_code_prompt.py:12-28

The process is as follows:

1. The AI model generates a response containing a <GENERATED-CODE> block.
2. The ChatTool's format_response method detects and extracts this block.
3. The extracted code is saved to a file named zen_generated.code in the user-specified working_directory_absolute_path.
4. A formatted message is returned to the calling agent, providing the path to the artifact and critical instructions on how to use it safely.

This flow is visualized in the diagram below.

The <GENERATED-CODE> Protocol

The GENERATE_CODE_PROMPT defines a strict protocol for the model to follow when generating code. The code must be enclosed in a <GENERATED-CODE> block, which can contain instructions and one or more file blocks.

• <NEWFILE: path/to/file.py>: Used for creating entirely new files. The block must contain the complete, runnable code for the file.
• <UPDATED_EXISTING_FILE: path/to/file.py>: Used for modifying existing files. The block should contain the full, updated implementation of the function or class being changed.

This structured format allows an automated agent to parse and apply the changes correctly.

Sources: systemprompts/generate_code_prompt.py:53-87

An example of a response using this protocol:

"<GENERATED-CODE>
Here is the implementation for the requested Python module. I've structured this as a proper Python package for better organization and scalability.

1.  Create a new file `calculator/__init__.py`. This file makes the `calculator` directory a Python package and exposes the `add` and `multiply` functions for convenient importing (e.g., `from calculator import add`).
2.  Create a new file `calculator/operations.py` to house the core arithmetic functions. This separation of concerns keeps the logic clean.

<NEWFILE: calculator/__init__.py>
\"\"\"A simple calculator package.\"\"\"

from .operations import add, multiply

__all__ = [\"add\", \"multiply\"]
</NEWFILE>

<NEWFILE: calculator/operations.py>
\"\"\"
Core arithmetic operations.

This module provides basic functions for performing mathematical calculations.
\"\"\"

from typing import Union

# Define a type alias for numeric types for clarity
Numeric = Union[int, float]


def add(a: Numeric, b: Numeric) -> Numeric:
    \"\"\"
    Calculate the sum of two numbers.

    Args:
        a: The first number (integer or float).
        b: The second number (integer or float).

    Returns:
        The sum of a and b.
    \"\"\"
    return a + b


def multiply(a: Numeric, b: Numeric) -> Numeric:
    \"\"\"
    Calculate the product of two numbers.

    Args:
        a: The first number (integer or float).
        b: The second number (integer or float).

    Returns:
        The product of a and b.
    \"\"\"
    return a * b
</NEWFILE>
</GENERATED-CODE>"

Sources: tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json

Response Formatting

The format_response method is responsible for preparing the final output. If no code is generated, it appends a standard message instructing the agent to evaluate the model's perspective.

If code generation occurs and the artifact is saved successfully, a different message is constructed. This message warns the agent that the generated file may contain partial snippets and must be integrated thoughtfully, not blindly copy-pasted.

# tools/chat.py:350-366

@staticmethod
def _build_agent_instruction(artifact_path: Path) -> str:
    return (
        f"CONTINUING FROM PREVIOUS DISCUSSION: Implementation plan saved to `{artifact_path}`.\n"
        "\n"
        f"CRITICAL WARNING: `{artifact_path}` may contain partial code snippets from another AI with limited context. "
        "Wholesale copy-pasting MAY CORRUPT your codebase with incomplete logic and missing lines.\n"
        "\n"
        "Required workflow:\n"
        "1. For <UPDATED_EXISTING_FILE:...> blocks: Partial excerpts only. Understand the intent and implement using YOUR full context. "
        "DO NOT copy wholesale - adapt ideas to fit actual structure.\n"
        "2. For <NEWFILE:...> blocks: Understand proposal and create properly. Verify completeness (imports, syntax, logic).\n"
        "3. Validation: After ALL changes, verify correctness using available tools (build/compile, linters, tests, type checks, etc.).\n"
        f"4. Cleanup: After you're done reading and applying changes, delete `{artifact_path}` once verified to prevent stale instructions.\n"
        "\n"
        "Treat this as a patch-set requiring manual integration, not ready-to-paste code. You have full codebase context - use it."
    )

This careful handling ensures that the powerful code generation feature is used safely and effectively, treating the AI's output as a proposal to be integrated by a developer-in-the-loop, rather than a final, infallible command.

Sources: tools/chat.py:270-316, 350-366

Summary

The chat tool is a foundational element of the Zen MCP Server, providing a flexible and powerful interface for AI-assisted development. Its role as a "senior engineering thought-partner" is well-defined through its system prompt, and its architecture allows for robust handling of user requests. The integrated code generation workflow, with its structured protocol and safety-oriented response formatting, elevates the tool from a simple conversationalist to an active contributor in the software development lifecycle.