Create draw.io diagram

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

The annotations are empty/uninformative (all false hints), so the description carries the full burden of behavioral disclosure. It clearly indicates mutation by saying 'create', but it does not disclose what happens if output_path already exists (overwrite defaults to false), how the file lives in layout impacts x/y coordinates, or what a successful invocation returns. No contradiction with annotations, but meaningful behavioral context is missing.

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 a single sentence with zero filler: it states the output format, the source ingredients, and the key layout behavior. Each phrase earns its place, and the constructing verb is placed front and center.

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?

With 8 paramters, 2 required arrays, nested objects, no output schema, and a sibling set, this one-sentence description is not enough for an agent to correctly plan an invocation. It does not explain when to prefer this over update_diagram, what automatic layout means for x/y inputs, whether node IDs are used to correlate edges and groups, or what a successful call returns.

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%, so the description must compensate. It does translate the main arrays into the tool's domain ('structured groups, nodes, and edges') and hints that layout is handled automatically, which is useful. However, it provides no semantics for overwrite, page_name, title, output_path, the 'kind' field on nodes, or how its edges/groups reference node IDs—leaving much of the schema unexplained.

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 states a specific verb ('Create') and a concrete resource ('editable .drawio XML diagram'), and it details the construction inputs ('structured groups, nodes, and edges') plus the 'automatic layout' behavior. It naturally distinguishes itself from the sibling tools: server_info/inspect/validate act on existing diagrams, and update modifies, while this one creates a brand-new diagram.

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 phrase 'Create a new' implies that this tool is for new diagrams rather than modifying an existing one, which gives some conditional guidance. However, the description does not explicitly mention siblings or say 'use update_diagram if the diagram already exists', so the usage distinction is left implied rather than stated.

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