lib_add_footprint_pads

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

With no annotations, the description carries the load well: it discloses that coordinates are NOT grid-snapped, that drilled pads are forced to MultiLayer regardless of the layer key, that unit selection applies to the whole call so a pattern can't be half-mm, and that refused writes surface as `property_failures`. It does not state what happens to pre-existing pads with the same designator (overwrite vs duplicate) or any permission constraints, which is the remaining gap for a mutating tool.

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 actionable directive and the why, then the parameter reference — a sensible order for a tool of this complexity. It is long, and the example is mildly inconsistent (advertised as "a 4-pad 0402 + corner pad in one call" but shows only two pads), which costs a point without undermining usability.

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 three-param mutation tool with 0% schema coverage, the description supplies everything the agent needs: full nested pad-key reference, unit scoping, footprint targeting rules, and failure reporting. Return semantics are covered by the existing output schema, so the brief 'Returns:' line is the right amount.

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 0% (pads is an untyped array of open objects), so the description must supply everything — and it does, enumerating every pad key with type, unit, default, and non-obvious semantics (hole_size=0 means SMD, oval = round with x_size!=y_size, corner_radius is percent, hole_length runs along X before rotation, negative paste_expansion closes the opening). It also documents the two top-level params' scoping behavior.

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+resource+cardinality ("Add MANY pads to the current footprint in ONE call") and explicitly contrasts with the sibling `lib_add_footprint_pad`, so an agent can route without opening either schema. The batched nature and the target (footprint pads) are unambiguous.

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?

Gives an explicit directive ("PREFER THIS over looping lib_add_footprint_pad") backed by a concrete cost rationale (64 turns vs one turn, one PreProcess/PostProcess and save). It also states the selection rule between the two `footprint_name` modes, including that a named footprint 'refuses if it cannot' become current rather than writing to the wrong one.

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