plasticity_create_printed_hex_pair

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

Beyond the annotations (readOnly=false, destructive=true, openWorld=false), the description discloses real behavior: process metadata (printer, material, slicer profile, nozzle, layer height, orientation, clearance evidence) is recorded, an optional immutable qualification ID is validated against the exact process/thread/clearance/engagement before mutation, and without it the output is flagged as needing a physical fit test. That is meaningful mutation-time context an agent cannot get from the declared hints.

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 create statement, then the designation/parameter split, then the qualification behavior, then the ISO caveat. Sentences are dense but each carries distinct information; no filler or restatement of the name. Slightly clause-heavy for a 5.

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 17-required-parameter, nested-schema, no-output-schema mutation tool, the description covers the conceptual model and the qualification gate well, but leaves the geometric vector inputs, defaults (handedness, radialDirection, cutterOvershootMm), units, and what is returned/created (bodies, groups, names) unspecified. Adequate but with real gaps given the tool's complexity.

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% across 23 parameters, so the description must carry the load. It successfully maps designation to crest diameter plus thread length and names pitch, rounded-profile depth, normal clearance, and head/nut envelopes as explicit, and enumerates the process sub-fields — but positional/vector params (axis, flatNormalDirection, radialDirection, screwAxisStartMm, nutEntryCenterMm), plus handedness, revision, intent, cutterOvershootMm and wall thickness, go unexplained. Partial compensation only.

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 (Create) and resource (a complete matched printable hex screw and nut pair), plus the input form ('printed M5x10 pair'). The 'matched pair' framing and the closing note that it is 'not ISO metric hardware' clearly separate it from sibling tools that make only a screw (plasticity_create_printed_hex_screw), only a nut (plasticity_create_printed_hex_nut), or bare threads.

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 implicitly defines its scope by explaining what the designation supplies versus what remains explicit, and it explains the qualification-ID path versus the no-ID path. But it never says when to choose this pair tool over the individual screw/nut/thread siblings, nor states prerequisites (units, existing document state). Usage is implied rather than prescribed.

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