oring_groove

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

With no annotations the description carries the full burden, and it discloses a lot: the gland rule formula and squeeze band, the exact return fields, that the host input is hidden after the cut, and the off-table error behavior (ok=False with nearest tabulated sizes) rather than a misleading dash number. It stops short of stating whether the cut is destructive/reversible or whether any permissions are needed, which keeps it from a 5 for a mutation tool.

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 and well organized (first sentence states purpose, then per-parameter detail, then return shape), but it is long and contains flourishes that do not help invocation, notably the compound tangent about the ring being "the purchased part this groove exists to hold, which no BOM would otherwise contain because the ring is never a modelled object." Useful content, but some sentences do not earn their place.

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?

Given 8 parameters at 0% schema coverage, no annotations, and no output schema, the description fills every gap an agent needs: input semantics, which fields are conditionally required, the return payload in both modes, and error/degenerate-case behavior. Nothing required to call it correctly is missing.

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 0%, so the description has to do all the work, and it does: it documents all eight parameters with units and constraints (cross_section > 0, inner_diameter required when cutting, face accepting f_* tags / FaceN strings / int-strings and requiring planarity). It even adds semantics not in the schema, e.g. that inner_diameter is used to size diameters even when not cutting, despite the schema default of 0.

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 ("Compute a static O-ring gland (groove)") and the optional side effect ("cut it into a face"), which immediately distinguishes it from generic modeling siblings like add_bearing or shell_solid. An agent can identify the domain (static seal gland) and both operating modes 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?

Clearly explains when the parameters are required ("Required when cut=True", "required only when cut=True") and contrasts the two modes: cut=True machines geometry vs cut=False being a "pure calculator (no geometry, no handle)". It does not, however, route the agent to an alternative such as seal_check for validation-only needs, so there is no explicit sibling exclusion.

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