audit_find_missing_decoupling

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

No annotations exist, so the description carries the full burden, and it does well: it discloses the detection heuristic (net-name or pin-name matching, C* designators on the same net), the bucket definitions, and — importantly — the false-negative boundary that unrecognised power pins cause the IC to be silently skipped. What it does not state is that this is a non-mutating audit with no side effects, nor any cost/performance expectation on large boards.

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?

The core definition is front-loaded and the bucket list is scannable, so the agent gets the essential decision input immediately. It loses a little to material that does not help tool selection — the RST formatting, the 'Pattern: ports the dashboard's JS-side analyzeDecoupling' implementation note, and a Returns block that partly duplicates the output schema.

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 zero-parameter audit the description covers the heuristic, the categorization logic, the skip conditions, and the practical failure mode it is meant to prevent. An output schema already exists, yet the extra item-level shape given here is consistent with it and adds no contradiction, so nothing an agent needs in order to call this correctly is missing.

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 applies. It correctly makes no attempt to invent parameter semantics.

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 opening sentence names a specific verb and resource ('Find ICs whose power pins lack a nearby decoupling cap') and scopes it precisely enough that an agent can separate it from siblings such as audit_find_unconnected_ic_pins or audit_find_orphan_power_objects. The subsequent paragraph removes any ambiguity about what counts as a violation by defining the two buckets.

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 a clear usage context ('Catches the single most-skipped pre-release review check') and states two exclusion conditions: fully-covered ICs are not surfaced, and ICs with no recognised power pins are skipped. It never names a sibling tool as the alternative for a related check, so it falls short of explicit when-not/alternatives routing.

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