assembly_component_from_bodies

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

With no annotations, the description carries the full burden and does well: it discloses the mutation, position preservation, atomic failure behavior, and the critical fact that old body refs stop resolving. That is exactly the kind of post-call behavior an agent needs.

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-loads the purpose, then covers behavior and return shape, then a concrete example. The example and return block are somewhat redundant with each other, but both are useful for ref handling.

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?

No output schema exists, so the description compensates by specifying the exact return keys and showing body refs in '<token>@<occurrence path>' form. Combined with the atomicity and ref-invalidation notes, it is complete enough to call correctly.

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 already 100%: the schema documents that name is unique in the design and bodies must be owned by the same component. The description mostly repeats those constraints and adds an example, but does not add substantial parameter semantics beyond the schema.

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 and resource: turn existing bodies into a new component. It is distinguishable from siblings like assembly_new_component and assembly_add_occurrence because it explicitly consumes existing body refs and creates one occurrence in their current owner.

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 a clear condition for use and a hard precondition: all bodies must belong to the same component, otherwise INVALID_PARAMS and nothing moves. It does not explicitly name a competing sibling or say when not to use it, so it stops short of a 5.

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