Learn a library part

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

Annotations already flag readOnlyHint=false and destructiveHint=true, and the description goes well beyond that: it discloses that temporary samples are deleted in the same call, that zoom is changed and left changed ('Tapir cannot set the zoom back'), that the Door or Window tool may be left holding the part, the Tapir 1.7.2 GDL restriction causing placed_not_set, and the no-footprint fallback to coordinates. This is unusually rich behavioral disclosure.

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 opening sentence is well front-loaded, but the body is a dense wall of long run-on sentences packed with parenthetical caveats, making it hard to scan. Almost every sentence carries real information, but the packaging could be tightened and structured into clearer units.

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 usefully explains the reply shape ('samples' left to right, first sample's GDL parameters, warnings, 'next'), plus preconditions like the active, unrotated floor plan and Tapir 1.7.2. It is nearly complete for a complex tool, with the unexplained 'port' parameter as the main gap.

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%, so the description carries the full burden. It explains name, kind (object, lamp, door or window) and variants (sets of GDL parameter name/value placed as extra samples), which meaningfully exceeds the bare schema. But the 'port' parameter is never mentioned anywhere, leaving one of four parameters undocumented.

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 states a specific verb and resource ('learn a library part') and details the full mechanism: placing samples past the right edge, measuring footprints, showing one floor plan image, then deleting the samples and storing the measurement. It also sequences itself against the sibling record_library_part ('next, the fields still to give record_library_part') and distinguishes learning from 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?

'Learn a library part once, before placing it by placement; a learned part is then placed with no samples' gives a clear when-to-use condition versus the placement path. It also adds a precondition for windows ('when a window's capture shows no opening lines... learn the window again, before recording hinge and swing'). It stops short of an explicit when-not-to-use or naming a concrete alternative tool for the placement path.

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