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

Annotations only say readOnlyHint=false, idempotentHint=false, destructiveHint=false. The description goes well beyond them: plain solve comparison is unmetered, adding monteCarlo triggers two metered runs against the account quota, Free accounts are refused with PLAN_REQUIRED, and the same seed makes movement attributable to the change. That is exactly the operational context an agent needs and cannot get from the annotations.

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?

It is front-loaded and dense — action first, then a return-value inventory, then the usage directive and plan gate. Almost every clause earns its place, but the content is crammed into one long run-on paragraph with no separation between parameters, returns and usage, which hurts scannability.

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?

There is no output schema, so the description carries the full burden of describing returns, and it does so item by item (changes, delta shape { a, b, delta }, stages, nodes, warnings.resolved/introduced, optional yield). Combined with the plan and metering disclosures, an agent has everything needed to call this correctly.

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 already 100%, so the baseline is 3. The description still adds real meaning: the two sides may be mixed freely across design document, { designId } and { templateId }, and the monteCarlo seed carries the attribution semantics and default trial count. It slightly exceeds the schema, though most field-level documentation lives in the schema.

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 (compare) and resource (two designs) and immediately scopes it to 'what changed between them, and what the change did'. It also enumerates the exact outputs (changes, delta, stages, nodes, warnings), which distinguishes it from solve_design and run_monte_carlo_job at a glance.

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 an explicit directive with an alternative: 'USE THIS after every edit instead of reading two full solve results side by side; it is the cheap way to see whether a part swap helped.' It also flags the metering distinction (plain solve unmetered, monteCarlo metered) and the Pro/Team requirement. It stops short of naming sibling tools or stating when-not to use it, so it lands just under the top tier.

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