lib_update_footprint_heights_from_3d

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

With no annotations present, the description carries the full disclosure burden and does it well: it states that neither mode writes zero and why, that footprints without a model are reported as without_model rather than silently zeroed, and that the library is NOT saved so the items[] diff must be reviewed and saved in Altium. It also explains the DRC consequences of both too-low and too-tall heights, which is exactly the kind of side-effect context annotations would otherwise supply.

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?

Content is front-loaded: purpose first, then domain rationale, then the mode parameter, then safety, then returns. It is long, and the trailing Returns section largely restates what the existing output schema already conveys, so a bit of it does not earn its place; the rest is dense with decision-relevant information and 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?

For a single-parameter library mutation with no annotations, the description covers everything an agent needs: scope, mode semantics, no-op and data-integrity hazards, the save-it-yourself requirement, and how failures surface. Even though an output schema exists, the prose adds the field semantics that make the result interpretable.

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?

The single mode parameter has zero schema description coverage and no enum, so the schema alone would leave the agent guessing; the description fully compensates by defining 'raise' (only increases, preserving hand-set heights) and 'match' (also lowers to the model), including which default applies. This is meaning the structured data does not provide anywhere.

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 opens with a concrete verb-and-resource statement plus the exact mechanism: sweep every footprint in the active PCB Library, find the tallest 3D body, write its OverallHeight to Footprint.Height. The scope (whole-library sweep, not one footprint) and the sibling it is not (lib_set_footprint_height) are both named, so an agent can distinguish it without opening any schema.

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 states the default (raise), the exact condition that selects the alternative mode (heights are too TALL, which raising cannot fix), and routes single-footprint or model-less corrections to lib_set_footprint_height. The rationale for why 'match' exists is spelled out with the failure consequence, leaving nothing to inference.

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