attach_part

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

No annotations are provided, so the description carries the full burden. It does disclose one meaningful behavioral trait: attachment uses measured closest points, never guessed coordinates, which is a trust-relevant guarantee. However it does not mention that the operation mutates the scene, that oversized moves are refused (max_move), that overlap is refused by default, or what happens on failure — all of which live only in the schema.

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?

A single tight sentence with zero filler, and the operative constraint (measured points, no guessing) is front-loaded alongside the sibling reference. It is appropriately sized for a one-line pointer, though it is arguably terse for a tool with three distinct modes.

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 an 8-parameter mutation tool with three modes, no annotations, and no output schema, the description is minimal but not deficient: the schema fully documents parameters and the description supplies the workflow link and the no-guessing guarantee. It still omits what the tool returns/modifies and the refusal behaviors that an agent acting without annotations would benefit from knowing.

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 100%, so the schema already documents all eight parameters, including mode semantics, gap behavior per mode, direction, target, and safety limits. The description adds no parameter-level meaning beyond that, which is the expected baseline-3 case when the schema does the heavy lifting.

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 action (attach a detached part to close the gap) and explicitly ties it to the sibling check_contacts, so the agent knows this consumes measured contact data. It stops short of naming the resource directly ('attach_part' infers it) and does not distinguish its three modes, which only the schema covers.

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 implies a workflow prerequisite ('the gaps check_contacts measured'), which tells the agent to run check_contacts first, and the target parameter warns 'do not just accept the nearest part.' But there is no explicit when-to-use-this-vs-alternatives statement, no mention of when to skip it, and no guidance on choose-move-vs-extend-vs-conform beyond the schema.

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