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

Beyond the annotations (non-readOnly, non-destructive, closed-world), the description discloses exactly what is preserved, that nets are transferred pad by pad, that schematic Footprint fields are rewritten as a side effect, and that leftovers are reported — much of the safety-relevant context. It omits failure modes (footprint not found in fp-lib-table, unknown refs) and async/job follow-up behavior, which lives in the wait_s schema field rather than the description.

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?

Tightly front-loaded with the core action first, then preservation guarantees, then pad_map semantics and reporting. The long single sentence carries a lot of clauses but every one adds information; no filler.

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?

With no output schema, the description does state what the tool reports (pads left without a net, old nets left behind), which covers the return-value burden, and async handling is documented in the wait_s parameter. Minor gap: no mention of what happens on partial failure or if a footprint is missing from the library.

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 coverage is 67%, and the description compensates by explaining the non-obvious semantics of pad_map (NEW pad → OLD pad whose net it takes) and clarifying that rot_deg is the rotation control, plus the library:name format for footprint. refs and the wait_s async behavior are left to the schema.

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?

Specific verb (replace/swap), specific resource (footprints), and explicit source constraint (a library in the project's fp-lib-table, addressed as library:name). It is clearly distinguishable from siblings like place_footprints and add_custom_footprint because it is an in-place swap that preserves the existing placement.

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 clear usage context: use pad_map 'for packages numbered differently', and it spells out the conditions under which this tool is the right choice (ref, value, position, rotation, side, lock and schematic link must survive). It stops short of naming an explicit alternative or a when-not-to-use condition versus place_footprints.

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