tool-renderer

Implementing a Tool Renderer

This guide walks through adding rendering support for a new Claude Code tool, using WebSearch as an example.

Before You Start

Examine existing test data to understand the tool's actual JSON structure:

# Find test files containing the tool
rg -l "ToolName" test/test_data/

# Look at actual JSONL entries
rg '"name":\s*"ToolName"' test/test_data/ -A 2 -B 2

Key fields to identify:

• Input parameters: What's in tool_use.input?
• toolUseResult structure: What metadata does the structured result contain?
• tool_result.content: What does the raw text output look like?

The toolUseResult field on transcript entries often contains richer structured data than tool_result.content. Always prefer parsing from toolUseResult when available.

Overview

Tool rendering involves several components working together:

1. Models (models.py) - Type definitions for tool inputs and outputs
2. Factory (factories/tool_factory.py) - Parsing raw JSON into typed models
3. HTML Formatters (html/tool_formatters.py) - HTML rendering functions
4. Renderers - Integration with HTML and Markdown renderers

Step 1: Define Models

Tool Input Model

Add a Pydantic model for the tool's input parameters in models.py:

class WebSearchInput(BaseModel):
    """Input parameters for the WebSearch tool."""
    query: str

Tool Output Model

Add a dataclass for the parsed output. Output models are dataclasses (not Pydantic) since they're created by our parsers, not from JSON:

@dataclass
class WebSearchLink:
    """Single search result link."""
    title: str
    url: str

@dataclass
class WebSearchOutput:
    """Parsed WebSearch tool output."""
    query: str
    links: list[WebSearchLink]
    preamble: Optional[str] = None  # Text before the Links
    summary: Optional[str] = None   # Markdown analysis after the Links

Note: Some tools have structured output with multiple sections. WebSearch is parsed as preamble/links/summary - text before Links, the Links JSON array, and markdown analysis after. This allows flexible rendering while preserving all content.