pcb_add_teardrops

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

With no annotations, the description carries the burden and does well: it discloses the modal dialog that cannot be scripted away, that human confirmation is required, and critically that the tool returns once dispatched rather than once completed. It does not state reversibility or that teardrops can later be stripped via pcb_remove_teardrops.

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 action in the first sentence, then the operational caveat. Each sentence is informative; the parenthetical ECO-dialog comparison is mild filler but does anchor the behavior for returning users.

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 command with an output schema, the description covers the essentials an agent needs: what it does, that it is non-atomic, and that a manual dialog step intervenes. Nothing required to invoke it 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?

Zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The absence of any scoping/filter argument is implicitly conveyed by 'board-wide' and 'on all objects'.

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 verb and resource ('Add teardrops') plus the exact geometric targets ('pad/via-track junctions') and scope ('board-wide'). It is unmistakable against the sibling pcb_remove_teardrops and the many other pcb_* mutation tools.

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 makes clear the command operates on all objects with no selective mode, and warns that a modal dialog must be confirmed manually in Altium before the effect occurs. It stops short of naming a preferred alternative or stating preconditions (e.g. an active PCB document must be focused).

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