Create linear dimensions

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

Annotations only say readOnly=false, destructive=false, idempotent=false; the description adds real behavior beyond them: the whole call is 'one undo step', unresolved linked points silently fall back to static with a 'warning', and a single failing item does not abort the rest. It also documents per-item error returns and input-order correspondence.

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?

Dense but front-loaded: purpose, then point model, then units, then placement, then alternatives, then return shape. Every sentence carries information, though the middle associative-point explanation is one long parenthetical that takes a re-read.

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 complex mutation tool with no output schema, the description covers everything an agent needs: creation semantics, units, placement rules, fallback behavior, partial-failure tolerance, the wall alternative, and an inline description of the returned array shape.

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?

Top-level schema coverage is reported as 0% (the sole 'dimensions' param wraps a deeply-annotated item schema), so the description must carry the burden and does: it spells out the three point forms ({x,y}, {element, at}, {element, x, y}), the anchor-listing prerequisite via get_dimension_anchors, projection semantics, and the m vs paper-mm unit split.

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+resource ('Creates linear dimension chains') and immediately scopes it against siblings by naming the alternative ('For walls prefer dimension_walls'). It is trivially distinguishable from create_angle_dimensions, create_radial_dimensions, create_level_dimensions and dimension_walls.

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?

Explicitly routes walls to dimension_walls with the 'Thickness' mode for wall widths, and explains the placement consequence of associative vs static points (Floor Plan with storyIndex vs active window). It stops short of full when-not guidance (e.g. when to prefer modify_dimensions over recreating dimensions).

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