pcb_renumber_pads

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

With no annotations, the description carries the full behavioral burden. It usefully discloses the spatial sorting algorithm, tolerance banding, target footprint, and return mapping, but it does not explicitly state that existing designators are overwritten, whether the operation is reversible, or any permission/undo considerations.

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 front-loaded with the main action and then cleanly separates Args and Returns. It is slightly verbose around the community-tool comparison, but no sentence is confusing or wasteful.

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 four-parameter mutation tool with no annotations and an output schema, the description covers target scope, algorithm, parameter meanings, and return shape. It is nearly complete, though explicit mutation side effects and usage exclusions would improve it.

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%, but the description fully compensates by documenting all four parameters. It explains order values lr_tb and tb_lr, default and meaning of start, increment semantics, and a concrete prefix example.

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: renumber pads in the current PcbLib footprint in spatial order. It clearly explains the spatial sorting behavior, but does not explicitly distinguish this tool from related sibling tools such as lib_fix_designators or sch_increment_designators.

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 gives implied usage by explaining it is the non-interactive equivalent of the community RenumberPads tool and operates on the active PCB library's current footprint. However, it does not state when-not to use it or name alternative tools for related designator workflows.

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