get_drawio_reference

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

No annotations exist, so the description carries full burden; it discloses the return type (Markdown) and the lifecycle trait 'A reference stays valid for the rest of the conversation', which prevents redundant re-fetches. It stops short of stating read-only status or the reference's size, but the caching/timing guidance is genuine behavioral value beyond structured fields.

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?

Front-loads the purpose, then segments cleanly per format value with a closing lifecycle note. Dense but every clause (content list, trigger condition, validity) carries information; no wasted sentences.

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 single-parameter lookup tool with no output schema, the description fully explains what is returned (Markdown reference), what each format contains, when to invoke it, and how long it stays valid. Nothing needed to call it correctly is missing.

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 enum values are already documented as 'xml'/'mermaid'. The description adds meaning beyond the schema by explaining what each value's content covers and when each is warranted, exceeding the terse schema description.

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?

States a specific verb+resource ('Returns a full draw.io diagram generation reference as Markdown') and immediately distinguishes itself from siblings by naming open_drawio_xml and open_drawio_mermaid as the tools this reference supplements. An agent can tell this is a documentation-lookup tool, not a diagram generator.

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?

Gives explicit when-to-use conditions per format: 'call it once before the first Mermaid diagram in a conversation' for mermaid, and 'only needed when a diagram uses those' for xml, listing the exact features (layers, tables, grids, etc.) that trigger it. The exclusions are as clear as the inclusions.

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