audit_find_via_antennas

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

With no annotations, the description carries the burden well: it defines exactly what counts as 'connected' by layer (geometric touching or Via.IsConnectedToPlane), discloses that it returns a JSON list rather than selecting/highlighting objects, and states the cost model and typical 1-3 s runtime. It never explicitly says the operation is read-only/no-modification, which is the main remaining gap.

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 definition of the defect, then the counting rule, then cost and return shape — a sensible order for an agent deciding whether to call it. It is on the long side for a zero-parameter tool (the RF-resonance paragraph is educational rather than operational), but no sentence is wasted or contradictory.

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?

Covers the counting semantics, cost, and result shape, and even though an output schema exists it still spells out keys like checked/violations/items and the '(x,y)' mil format. The one omission is any prerequisite such as an active PCB document being required for the audit to run.

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?

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No misleading parameter claims are made.

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 and resource ('Find vias connected on only one layer') and immediately disambiguates the concept with the parenthetical 'resonating stubs' plus an explanation of the failure mode. That definition also separates it from nearby siblings such as audit_find_signal_vias_without_return and pcb_normalize_vias, which target different via problems.

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 concrete triggering situation ('Common after iterative editing where a layer-change via gets stranded') and explains the RF/high-data-rate harm, which tells an agent when this audit is relevant. It stops short of explicit alternatives or exclusions (e.g., versus the return-path via audit), leaving that comparison to inference.

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