add_via

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

The annotations state destructiveHint=true, so the description does not need to repeat destructiveness. The description adds that diameter/drill default to netclass, which is useful behavioral context beyond the schema (schema gives defaults of null but not that they are overridden by netclass). However, it does not mention what happens to existing vias or whether the via is placed on the active board layer. Given annotations already cover the destructive hint, a 3 is appropriate.

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 description is a single, concise sentence that packs significant meaning: placement, coordinates, net, and defaults. It is front-loaded with the verb and resource. Every word earns its place, with no filler or repetition. This is an efficient, high-quality description.

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?

The tool has 6 parameters, 0 required, and no output schema details are given beyond that an output schema exists. The description covers x, y, net, and mentions diameter/drill defaults, but leaves 'path' undefined and does not specify units or behavior of optional parameters. For a placement tool with destructive annotation, more guidance on what constitutes a valid call (e.g., coordinate units) might be needed, but the description is adequate for a basic understanding. It is not complete enough to handle all edge cases.

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 0%, so the description must compensate. The description explains the meaning of x, y, net (placing via at coordinates) and that diameter/drill default to netclass, adding meaning not in the schema (which just gives defaults of null). However, it does not explain the 'path' parameter at all; for a PCB tool, 'path' likely refers to a net path or connection, but this is unclear. With 0% coverage, the description partially compensates but leaves at least one parameter ambiguous.

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 clearly states the verb 'Place' and the resource 'through via', and specifies coordinates, net, and defaults to netclass for diameter/drill. It is specific and includes key parameters. It does not explicitly differentiate from siblings like 'add_track', but given the distinct resource (via vs track), the distinction is fairly clear.

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?

The description implies usage context: it says 'Place a through via at (x, y) mm on net', which implies the agent should use this when adding a via to a PCB. However, it does not provide explicit guidance on when not to use it or mention alternatives like 'add_track' or other placement tools. It lacks explicit exclusionary info, but the action is clear enough for a basic call.

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