Revolve

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

Annotations only say it is a non-idempotent, non-destructive write; the description goes well beyond that by disclosing a real side effect (a non-world-aligned axis becomes a construction line in the sketch), an explicit failure mode (AXIS_OUT_OF_PLANE), the special casing for world-aligned axes through the model origin, and the fact that the result reports axis_model_start/axis_model_end. It does not explain how the operation modes (join/cut/intersect) affect existing bodies, which is the one behavioral gap left.

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?

Four sentences, front-loaded with purpose, then the axis contract, the edge-case behavior, and the return fields. The middle sentence is long and chains three conditional behaviors together, which costs a little readability, but no sentence is filler.

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 9-parameter mutation tool with no output schema, the description covers the geometry contract, the failure mode, and the returned axis endpoints well enough to call the tool confidently. What remains thin is the semantics of the operation enum and whether the source sketch is modified or consumed.

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?

At 78% schema coverage the baseline would be 3, but the description both restates the unit contract ('axis_origin and axis_direction are model space (cm)') and adds rules absent from the schema: the axis must be coplanar with the profile, world-aligned directions resolve to Fusion's construction axis, and off-plane axes are rejected. This is genuine meaning beyond the field-level descriptions.

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 opens with a specific verb and resource: 'Revolve the most recent sketch's profile about an axis.' That immediately separates it from the other sketch-consuming siblings (extrude, sweep, loft) and pins down which input geometry is consumed. It stops short of explicitly naming an alternative for the cases where revolve is wrong, so a 5 is not warranted.

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 rather than stated: the tool operates on 'the most recent sketch's profile', which tells the agent a sketch must already exist, and the coplanarity rule tells it which axes are legal. There is no explicit when-to-use/when-not guidance relative to extrude, sweep or loft, and nothing about prerequisites such as a closed profile.

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