catia_groove

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), so the bar is lower. The description earns credit by disclosing genuinely non-obvious behavior: a Groove can serve as the first feature of an empty body, holds the removed volume, and must be assembled into the main body to actually cut — behavioral context the annotations cannot convey.

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?

Three sentences, each load-bearing: the definition, the axis cross-reference, and the first-feature behavior. The core verb+resource is front-loaded with zero preamble or 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 mutation tool with no output schema and full schema-coverage on parameters, the description supplies the key behavioral facts an agent needs (first-feature usage, removed-volume assembly). It does not explain prerequisites such as whether a sketch must exist first, a minor omission given the schema and annotations already carry substantial detail.

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 100%, so the schema already documents axis, name, angle, and sketch_name in detail (including the enum for axis and a strong name-convention note). The description only adds 'Same axis rules as catia_shaft', which cross-references semantics but adds no new parameter detail. Baseline 3 is appropriate.

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+resource ('Create a Groove') and immediately qualifies it as a '(revolution cut)', which cleanly distinguishes it from the additive sibling catia_shaft. An agent can route between material-removal and material-adding revolve operations without opening the schema.

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?

It states a concrete usage context — 'Works as the FIRST feature of an empty body' — and names the 'Machined' body pattern, giving clear guidance on a non-obvious scenario. However, it never explicitly contrasts itself with catia_pocket (extruded cut) or states when a Groove is preferred over those alternatives, so the alternative-routing is implied rather than stated.

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