lib_add_footprint_track

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

With no annotations, the description carries the burden well: it discloses that the call mutates the current footprint, that a named footprint is made current first and the call 'refuses if it cannot', and that mm values are kept exact rather than rounded. Missing permission/edit-mode requirements and whether tracks can be undone.

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?

Docstring layout with Args/Returns is front-loaded and each line earns its place; slightly verbose in repeating 'in mils' per coordinate, but that redundancy reinforces the units contract.

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?

An output schema exists, so the brief 'Returns: Dictionary confirming track addition' is sufficient. For a mutation tool with no annotations and 8 parameters, the geometry, units, layer and target-footprint semantics are all covered; only permission/state prerequisites are absent.

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%, and the description compensates fully: every parameter is documented with units (mils, or 'mil'/'mm' applying to all lengths), defaults (layer=TopOverlay, units=mil), accepted layer values (BottomOverlay, Mechanical1..16), and the empty-vs-named semantics of footprint_name.

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 concrete verb+resource: 'Add a track to the current footprint' with the intended uses (silkscreen/courtyard) parenthesized. It never distinguishes itself from the sibling lib_add_footprint_tracks (plural batch version), which is the main risk of misselection.

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?

Use context is implied ('for silkscreen/courtyard') and the layer parameter hints at mechanical/courtyard outlines, but there is no explicit when-to-use vs the batch lib_add_footprint_tracks or lib_add_footprint_regions/arc, and no prerequisites such as needing a footprint library open.

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