draw_mermaid

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

Annotations flag destructiveHint=true, yet the description never says whether rendering replaces the current scene or appends to it, what existing elements are lost, or what happens with malformed Mermaid or the 2000-character limit. With annotations covering the safety profile only at a flag level, the description should supply the 'what gets destroyed' context and does not. No annotation contradiction, since rendering to a scene is plausibly destructive.

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?

A single tight sentence with the key action front-loaded and no filler. It is appropriately sized as a purpose statement, though brevity here comes at the cost of the missing parameter and behavior detail.

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?

An output schema exists, so return values need not be explained, but the definition is still too thin for a tool with five parameters, 0% schema coverage, and destructive semantics. An agent cannot tell from this description how to choose layout/elbowed/roundness or whether its current scene survives the call.

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 description coverage is 0% across five parameters, so the description carries the full burden and only implies that mermaid_code is the input. layout, elbowed, direction, and roundness get no explanation of what 'layered' vs 'horizontal' vs 'vertical' means or how direction and layout interact. This is a significant gap for a 5-param tool.

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 gives a specific verb+resource: 'Parse Mermaid flowchart/graph code and render it directly to the Excalidraw scene.' That clearly separates it from element-level siblings like add_rectangle or draw_architecture. It stops short of explicitly naming those alternatives, so it does not fully distinguish itself in prose.

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?

There is no when-to-use guidance and no mention of alternatives such as draw_architecture, preview, or auto_fix_layout. An agent must infer from the name alone that this tool is chosen when it already has Mermaid source text rather than a scene spec.

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