Copy, align and group

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

Annotations already declare readOnlyHint=false and destructiveHint=true, so the mutation risk is known. The description adds valuable behavioral details beyond that: 'flip' turns a piece back to front and 'rebuilds what is inside it', 'mirror only swaps left and right and leaves the front where it was', and each sub-action has specific side effects. It also discloses the return value ('Returns new ids'). This goes well beyond the basic annotations.

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 description is long (about 150 words) but packs a lot of information for a tool with 9 sub-actions and 16 parameters. It front-loads the overall purpose ('Arrange elements in one undo step') and then lists each action in a structured, semi-colon-separated format. No sentence is wasted, though the density requires careful reading. It could be slightly more concise by grouping, but it stays efficient.

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 tool this complex, the description covers each action's parameters and behavior, plus the return value. It does not cover edge cases or prerequisites (e.g., whether ids must be on the same level, coordinate system assumptions), but given the output schema exists and annotations cover safety, an agent can invoke it correctly for the listed scenarios. The main gap is a lack of examples or warnings about interactions between actions, but it is sufficient.

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 100%, so every parameter is already documented. The description adds meaning by explaining how parameters drive each action, e.g., 'array {ids,n,dx,dy,dz} adds n copies stepping by dx/dy/dz cm' and 'align {ids,axis,edge:low|middle|high,value} lines pieces up by an edge'. It clarifies the purpose of 'edge' values (low=middle=high) and 'value' as the target coordinate, which goes beyond the schema's terse field names.

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 clear, multi-purpose resource: 'Arrange elements in one undo step' and enumerates each sub-action with its verb and resource ('array' copies pieces, 'align' lines up edges, 'distribute' sets them side by side, etc.). It explicitly distinguishes from sibling tools by detailing unique behaviors like 'flip' (turn a piece back to front) and 'front/back' (draw rooms on top/underneath), so an agent can select it without opening the 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?

The description explains what the tool does but not when to prefer it over alternatives. It never mentions sibling tools like 'move', 'place', or 'joinery' or gives conditions for using those instead. The atomic 'one undo step' hint is useful, but the guidance is implicit rather than explicit about alternative selection.

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