The server exposes a single tool 'walkthrough_diagram' with an explicitly documented input schema in the source code. However, the tool definition reveals significant quality gaps: (1) the tool name lacks an action verb, making its purpose ambiguous to LLMs; (2) the description is long (170+ chars) and explains the interactive feature, but omits critical metadata about prerequisites, error cases, and expected side effects; (3) the input schema is present with proper JSON Schema structure (three required properties: code, summary, nodes), but the 'code' and 'summary' parameters lack meaningful descriptions beyond trivial type labels; (4) the 'nodes' object schema is underspecified, while it declares additionalProperties with nested object structure, the nested properties lack descriptions explaining what 'title', 'description', 'links', and 'codeSnippet' mean; (5) no output schema is documented, leaving uncertainty about what the tool returns and how downstream operations might use it; (6) no error handling guidance exists, if the Mermaid code is invalid or SVG generation fails, the tool provides no recovery instruction; (7) no security or permission context is declared. The tool performs WRITE operations (per the source), which must be explicitly stated in the description so agents understand the side effects.
Render an interactive Mermaid diagram where users can click nodes to see details. BEFORE calling this tool, deeply explore the codebase: 1. Use search/read tools to find key files, entry points, and architecture patterns 2. Trace execution paths and data flow between components 3. Read source files — don't guess from filenames Then build the diagram: - Use `flowchart TB` with plain text labels, no HTML or custom styling - 5-12 nodes at the right abstraction level (not too granular, not too high-level) - Node keys must match Mermaid node IDs exactly - Descriptions: 2-3 paragraphs of markdown per node. Write for someone who has never seen this codebase — explain what the component does, how it works, and why it matters. Use `code spans` for identifiers and markdown headers to organize longer explanations - Links: include file:line references from your exploration - Code snippets: key excerpts (under 15 lines) showing the most important or representative code
Tool name lacks action verb. 'walkthrough_diagram' is a noun phrase. LLMs infer intent from verb-first naming. Should be 'generate_diagram', 'create_diagram', or 'render_diagram' to signal the create/generate action.
Parameter descriptions are missing or trivial. The 'code' param is labeled only as 'Mermaid diagram code (flowchart format)', this describes the content type, not its purpose or constraints. No guidance on valid Mermaid syntax, acceptable node count, or what happens if code is malformed. The 'summary' param has no description at all in the visible schema. The nested 'nodes' object properties (title, description, links, codeSnippet) lack descriptions explaining what each field should contain or its constraints.
No output schema documented. The tool description mentions rendering and returning an interactive diagram, but no structured response is specified. What does the tool return? A URL? An HTML blob? A diagram ID for later retrieval? Agents need this to plan downstream actions.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-22 | F | 33 | 2026-07-28+ | v2 |
| 2026-03-09 | F | 0 | - | v1 |
No error handling or recovery guidance. If SVG generation fails, Mermaid code is invalid, or the HTTP server is unreachable, the tool provides no actionable error message. Agents have no guidance on retrying, validating input, or alternative actions.
WRITE operation not declared in description. The tool's description does not state that it creates/modifies persistent state (saving diagrams to the local database via saveDiagram() in src/index.ts). Agents need explicit clarity on whether a tool call has irreversible side effects.
Input schema 'nodes' object is underspecified. The schema declares additionalProperties as an object with nested properties, but does not specify minProperties, maxProperties, or constraints on the number of nodes. The description instructs agents to generate '5-12 nodes', but this constraint is buried in prose narrative, not in the JSON Schema where it is machine-parseable.
Mermaid code format acceptance is not validated. The 'code' parameter accepts a free-form string but provides no guidance on supported Mermaid diagrams (only 'flowchart TB' mentioned in description), syntax validation rules, or what happens if the code is unparseable by the satori/resvg rendering pipeline.
No permission or scope declaration. The tool saves diagrams to a persistent store accessible via HTTP. No clarity on whether all agents can call this tool, whether there are rate limits, or what permissions are required. Multi-tenant deployments need permission gates.