Render D2 Diagram

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this a safe, idempotent, read-only operation, but the description adds substantial behavioral context beyond them: the elk performance hazard ('extremely slow in WASM'), the exact output contract (SVG markup starting with <?xml ...?> unless no_xml_tag=true, or ASCII art), the ~500KB font-data implication of skip_fonts, and the multi-board animation semantics of animate_interval/target. It also discloses error behavior ('Returns error with syntax details if D2 code is invalid'). This is rich, decision-relevant behavior disclosure well above the annotation baseline.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (overview, Args, Returns, Examples, Error Handling) and front-loads the core purpose in the first sentence. Given 15 parameters and complex multi-board/ASCII/font behaviors, the length is largely justified. However, the Args section re-states each parameter that the 100%-covered schema already documents, creating redundancy that costs agent context; a tighter version could reference the schema and add only the warnings, examples, and return contract.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with no output schema and high complexity (15 params, interactive behavior between animate_interval and target, two output modalities), the description is complete: it specifies the return type and format, the XML declaration condition, error behavior, and the validation workflow. The examples cover the major invocation patterns (simple, styled, ASCII, animated, HTML-embed, embedded-fonts), so an agent has everything needed to call the tool correctly without inspecting further.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, and the description does add genuine meaning beyond the schema: concrete D2 syntax examples ('a -> b: connects', styled blocks with theme_id=3, steps: { s1: {a} ... }), a compact key for theme IDs (0, 3, 300, 200), and the return-format context for params like no_xml_tag and ascii. Some duplication exists — layout, target, and animate_interval wording largely mirrors the schema — but the examples section teaches correct parameter combinations in a way the schema alone does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource+output: 'Render D2 diagram source code to SVG or ASCII art using the D2 WASM engine.' It further clarifies it compiles D2 code without requiring the d2 binary, making the tool's function unambiguous. The rendering action is inherently distinct from siblings like d2_validate, d2_format, and d2_list_themes, so an agent can select it correctly without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives strong when-not guidance: 'elk is extremely slow in WASM — do NOT use unless explicitly requested' and 'skip_fonts ... Only set false if user explicitly requests embedded fonts.' It also routes to a sibling in the Error Handling section: 'Use d2_validate first to check syntax before rendering,' and points to d2_list_themes for theme options. However, it does not systematically contrast with d2_inspect or d2_format (e.g., when to prefer format/inspect over render), leaving some alternative-selection judgment to the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.