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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description then adds real behavioral substance beyond that: it discloses the per-pad output (free corridors, via viability, blocker attribution to parts, nets, or board edge) and defines a domain term, CRAMPED, with its consequence. It does not cover timeout/polling behavior, though the schema's wait_s description partially does.

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-loaded with the output contract, then the CRAMPED special case, then the sibling routing advice — no filler. The first sentence is a dense fragment ("For every net still open (or the nets named): each pad with...") that takes a second read, which keeps it short of a 5.

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 return-value burden and does so by describing the corridor/via/blocker breakdown and the CRAMPED verdict. For a read-only diagnostic with 80% schema coverage the definition is close to self-sufficient; only the undocumented max_nets parameter leaves a 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 description coverage is 80%, so the schema documents design_id, nets, wait_s, and reach_mm adequately; baseline is 3. The description reinforces the nets parameter (open nets vs named nets) and gestures at reach_mm via the corridor-free concept, but adds no syntax or format detail and never mentions max_nets.

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 (diagnose) and resource (open nets that won't route) and immediately enumerates what is inspected per pad: escape corridors on its own layer, via sites, and the specific blockers. An agent can distinguish it from route_board, repair_board, and ripup_routing without opening any schema.

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 an explicit alternative and the condition that selects it: "Use it instead of repeating repair_board on a net that keeps failing." It also defines the default scope (every open net) versus the narrowed scope (the nets named), so the agent knows both when to reach for it and at what breadth.

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