construction_plane

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

With no annotations, the description carries the full burden and does: it discloses that mismatched fields yield INVALID_PARAMS with the accepted field list, that wrong entity kinds return details {param, expected, got}, and that a Fusion failure raises FUSION_API_ERROR and leaves the timeline unchanged. It also notes units (mm/degrees) and that string expressions keep the plane driven by that expression — genuine behavioral context not available in the schema.

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-line purpose, then a compact table, then ref/units/error notes, then return shape and three examples. Front-loaded and dense with no filler sentences; the table replaces what would otherwise be paragraphs of prose.

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 14-parameter, single-required-parameter tool with no output schema, the description supplies the method matrix, ref formats, error contracts, and the return object shape (ref, type, name, origin_mm, normal, health, warning), which is exactly what an agent needs to call it correctly.

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 goes beyond it by documenting cross-parameter constraints (method → exactly its fields) and the ref grammar `origin:XY|XZ|YZ|X|Y|Z|O`, which the per-property descriptions only partially cover. Units and expression-string semantics reinforce this.

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?

Opens with a specific verb and resource ('Create a construction plane') and immediately states its role ('a reference for sketches, mirrors, splits'). Alongside siblings construction_axis and construction_point, the plane/axis/point distinction is clear from the name plus this gloss.

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 method table is effectively usage guidance: each row tells the agent which defining fields a given construction mode requires, with inline qualifiers ('midway between them', 'coplanar straight edges', 'cylinder/cone'), and it warns that extra fields are refused. It lacks explicit 'when to use this instead of constructing a sketch plane' or exclusions versus siblings, so it stops short of a 5.

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