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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower, yet the description still adds valuable behavior: replacing source keeps a prior version only on Pro, and 'private' visibility is plan-gated. That is genuine auth/plan and data-retention context an agent cannot get from the annotations. The 'replaces that diagram's source' wording sits in mild tension with destructiveHint=false, but since the diagram itself persists and versioning is offered, it is a nuance rather than a contradiction.

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 first three sentences are well front-loaded, but the bulk is a single unbroken paragraph cramming the entire DSL reference, with no line breaks or grouping. The grammar content is useful for authoring a valid source, yet its density and lack of structure make it hard to scan and it crowds out tool-level guidance.

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 no output schema, the description correctly states what comes back (short link, README embed). It covers create/update modes, visibility semantics, and source syntax, which is what an agent needs to invoke it. It omits account/auth prerequisites for saving and any suggested pre-save validation step.

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 67%, and the description meaningfully extends all three parameters: id (create vs replace plus versioning), visibility ('unlisted' = link-visible, 'private' = Pro only), and source (an extensive DSL grammar covering messages, payload attachment, and directives). It adds substantially more than the schema's terse field descriptions.

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?

Opens with a specific verb+resource and outcome: 'Save a diagram to your Volley account and get a short link and README embed.' It clearly separates create (no id) from update (with id) behavior, which distinguishes it from sibling save_collection by resource. It never explicitly names a sibling to contrast against, so it stops short of a 5.

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?

It gives real usage context for the id parameter (create vs replace) and a plan constraint ('private' is Pro only), which is more than nothing. But it never states when to prefer this tool over siblings like verify_diagram or check_diagram, nor any when-not conditions or prerequisites (e.g. validating source before saving).

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