reorder_grid_tracks

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

With no annotations, the description carries the full burden, and it does disclose the key non-obvious behavior that children travel with the moved tracks. However, it says nothing about whether insertionIndex is evaluated before or after the source tracks are removed, what happens to sibling track indices, permission requirements, or error conditions for non-grid nodes.

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?

Two tight sentences with no filler, and the core action is front-loaded before the parameter clarification. Nothing is redundant, though it is terse enough that the missing edge-case behavior could not be squeezed in.

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 4-required-param mutation tool with no annotations and no output schema, the description covers purpose, the child-carrying behavior, and two parameter meanings. It still leaves index-shift behavior and failure modes unexplained, so it is adequate but incomplete.

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 0%, so the description must compensate, and it explains two of the four parameters: fromIndices as 0-based tracks to move and insertionIndex as the landing spot. nodeId and axis are self-evident from their names and the ROWS/COLUMNS enum, but the subtle index-shift semantics of insertionIndex after removal are left unresolved.

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 ('Move whole rows or columns of a GRID frame') and clarifies the scope with 'taking their children with them', which separates it from generic node movers like move_node or arrange_children. It does not name a sibling alternative directly, so it stops short of a 5.

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 implies the tool only applies to GRID frames, but gives no explicit when-to-use guidance, no exclusions, and no pointers to related tools such as set_grid_layout or set_grid_child_position. An agent must infer applicability from the phrase 'GRID frame' alone.

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