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

Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds real substance beyond them: it modifies copper by inserting vias, constrains them to lie inside the island and inside the net's main copper on another layer, clear of other nets, and notably reports islands it found no site for (partial-failure behavior). The run_drc follow-up is a useful operational caveat.

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 sentences, all earning their place: the core operation, the failure-reporting behavior, and the run_drc imperative. Front-loaded with the operation, though the first sentence is dense with placement clauses that take effort to parse.

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 carries the return burden and does disclose that it reports islands with no viable site. Combined with the destructive annotation and the run_drc directive, an agent has enough to call it correctly; only the scope of nets (all nets when omitted) and the max_vias cap are left implicit.

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 75% (nets, wait_s, and design_id are documented in-schema), so the schema does most of the work and baseline 3 applies. The description alludes to via count ('one through-via per island') but never clarifies max_vias, the one undocumented parameter, so it does not compensate for the remaining gap.

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 operation: placing one through-via per pour island that KiCad has cut off from its net, with concrete placement constraints. It is far more specific than a restatement of the name, though it opens with a dense clause ('A filled pour cut into islands by routing') rather than a clean verb+resource and never names a sibling to distinguish against.

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?

Usage is implied by the scenario (islands cut off from their net after routing) and there is one workflow directive, 'Run run_drc afterwards.' However, there is no explicit when-to-use vs. when-not, and no comparison to conceptually adjacent siblings such as tie_rail_pads, tidy_copper, or ripup_routing.

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