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

Annotations already declare readOnlyHint=false and destructiveHint=false; the description earns credit by explaining why a removal tool is non-destructive — a via survives if its removal disconnects anything, and zones are refilled and re-verified. It also discloses the runtime cost ('runs for minutes on a large board'), which annotations cannot express.

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?

Three dense sentences, front-loaded with the core behavior before the nets hint and the runtime/follow-up warning. Parentheticals are informative rather than filler; only the 'pours already join most of their pads' aside is arguably optional.

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 long-running mutation tool with no output schema, the description covers the decision rule (kept if removal disconnects), the runtime expectation, the long-job continuation hint exists in the schema, and the required follow-ups. It does not state what is returned (e.g. count of removed vias) or how partial/interrupted runs are reported, a minor gap.

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 50%: design_id and wait_s are documented in-schema, while nets and workers are not. The description adds real meaning for nets (candidate limiting, GND/plane rails prioritized) but says nothing about workers or about how nets interacts with the connectivity test. Baseline 3 given partial coverage.

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 and resource: 'Remove every via the board does not need', then defines 'redundant' concretely via the refill-and-compare-unconnected-count test. It never names the closest sibling (polish_vias), so an agent must infer the distinction itself.

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 a clear usage pattern: 'nets limits the candidates (GND and the plane rails first: pours already join most of their pads)' and names the follow-up sequence 'then fill_zones, run_drc'. No explicit when-not-to-use or exclusion versus polish_vias/tidy_copper, which keeps it below a 5.

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