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

Annotations only declare non-read-only, non-idempotent, non-destructive; the description adds real behavioral substance beyond that: a new revision is created, the effect report contains n_changed/rejected/cloned/carried, changed-since-read elements are rejected individually while others still write, and relatively placed elements are carried along. It also flags that a successful call may not complete the job, which is a non-obvious verification requirement.

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?

Purpose is front-loaded and no sentence is pure filler, but the telegraphic fragments ("name about", "Axis vertical unless given", "Beyond the named", "A call that succeeds is not a job that's done") are hard to parse and bury important constraints. Compression here costs comprehension for a 13-parameter mutation tool.

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 13-parameter, nested-schema, plan-based mutation tool with no output schema, the description covers the key facts an agent needs: target forms, pivot options, axis default, revision/effect reporting, refusal conditions, and the dry_run/plan_id protocol. It could say more about error outcomes and ordering of multi-element rotations, but nothing essential is 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 100%, so the baseline is 3; the description still adds meaning by contrasting the pivots ("placement_origin turns about the placement point (often a corner: the body moves)" versus default in-place center) and by explaining axis defaults. It adds less for parameters like request_id, note and expect_contacts, which the schema already documents well.

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 ("Rotates elements (guid, guids or set) in place") and immediately pins the default pivot ("about their body center, so each stays where it stood"), which distinguishes it from move_elements, mirror_elements and scale_elements. The target-type constraint ("guid, guids or a set from find_elements/get_selection, never a filter") further separates it from filter-based siblings.

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 clear operating context: which target forms are legal, that an element with body_gap is refused, and the escalation path when the call reaches beyond the named elements (PLAN_REQUIRED, then run its plan_id with expect_beyond). It does not explicitly compare itself to move/mirror siblings or state when a rotation is the wrong operation, so it stops short of full when/when-not guidance.

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