sheet_metal_cut

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

With no annotations, the description carries the burden and does well: it discloses the parametric coupling (depth tied to thickness), the failure mode (a cut that removes no material is deleted and reported as an error), and the feature-counting behavior for multi-shape sketches. Missing only operational context like whether it runs in a transaction or what permissions/state the document must be in.

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?

Front-loaded with the core action and its parametric behavior, then preconditions, then an alternative — a sensible order. The parenthetical 'parametric!' and multi-line formatting are slightly informal but nothing is wasted.

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 two-parameter mutation tool with an output schema, the agent needs the preconditions, the failure behavior, and the sibling routing — all present. The one gap is the undocumented sketch_index semantics, which matters given the strict 'sketch must be on the panel face' rule.

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 only 50%; 'instance' is documented in-schema, but sketch_index has no description anywhere. The description does add meaning about which sketch is valid (one on the panel face) and that multiple closed shapes yield multiple holes, which partially compensates, but it never explains what sketch_index indexes or defaults to.

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 ('Cut through the panel') and clarifies the scope (a single Cut feature with possibly multiple holes from one sketch). It implicitly contrasts with cut_on_face, though it never names the full sibling set it could be confused with. Clear enough to pick it out of the feature-creation family, but not maximally discriminating.

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?

Gives concrete preconditions (sketch must be on the panel face, not a work plane) and an explicit alternative with its selection condition: 'For holes at known world coordinates, cut_on_face is easier.' It stops short of stating when this tool should never be used or what to do if the sketch isn't on a panel face.

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