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

Annotations declare destructiveHint=true and readOnlyHint=false, and the description earns credit on top of that by disclosing the cross-region side effect: overlapping recomputed regions may shift FOLLOWING regions (org, ERD, process, journey, arch, captable) as a whole, not card by card. It stops short of saying whether the rearrangement is undoable or reversible, which matters for a destructive call.

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?

One front-loaded sentence pair: the action and resulting layout come first, the caveat about other regions second. It is dense but every clause carries information; the all-caps FOLLOWING/AS A WHOLE reads slightly awkward but signals emphasis rather than padding.

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 destructive, zero-required-parameter mutation with no output schema, the description covers what changes, what is preserved, and what collateral movement can occur. The main remaining gap is recoverability (undo/rollback) and what happens if phases or swimlanes are 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 baseline is 3, but the description adds real meaning by tying the geometry to the parameters — columns correspond to phases and rows to swimlanes, which is what columnWidth and swimlaneHeight control. It also surfaces 'order via orderInPhase', a phase-ordering concept not visible in the input 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?

The description names a specific verb ('Rearranges') and resource ('journey blocks') and states the exact resulting geometry: phases as a horizontal header, steps at phase column × swimlane. That geometry plus the journey-specific framing clearly separates it from auto_layout_org, auto_layout_process, auto_layout_canvas and auto_layout_mcd.

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?

Usage is implied (call it to snap journey blocks into a grid) and one boundary is stated — it does not touch the internal layout of other kinds. But there is no explicit trigger condition, no 'use auto_layout_canvas instead when…' routing, and no prerequisite such as having phases or swimlanes defined first.

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