Sketch a hooked sweep path

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

Annotations provide no behavioral hints beyond the title (no readOnlyHint, destructiveHint, etc.), so the description carries the full burden. It only says 'Add a sketch', which implies a mutation, but discloses nothing about side effects, permission requirements, or what happens on failure. The schema's 'validate' parameter hints at verification behavior, but that is not reinforced in the description. This is a notable gap for a creation 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?

The description is a single concise sentence that front-loads the action and purpose. It contains no filler, and every clause earns its place by clarifying what is sketched and why.

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?

With 12 parameters and no output schema, the description is adequate but sparse. It mentions the intended downstream tool (onshape_sweep) and the approximation via segments, which helps, but it does not explain the overall workflow (e.g., that a sketch is added to an existing element) or what the tool returns. Since the schema covers parameter details, the description meets minimum viability but lacks richer context that would help an agent integrate it into a multi-step operation.

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 100%, so all 12 parameters are already documented. The description adds a high-level notion of geometry ('straight stem', 'hooked arc') that maps to straight_height and hook_radius, but the schema already describes those fields. The description does not add relational information, defaults, or unit clarifications beyond what the schema provides, so it meets the baseline without exceeding it.

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 states a specific action ('Add a sketch'), describes the geometry precisely ('straight stem joined to a hooked arc'), and names its intended use ('a ready-made path for onshape_sweep'). This clearly distinguishes it from sibling sketch tools like onshape_sketch_circle or onshape_sketch_line, so an agent knows exactly what this tool creates.

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?

The description explicitly positions the tool as a prerequisite for onshape_sweep, giving a clear usage context. It does not name alternatives or state when not to use it, but the mention of 'ready-made path for onshape_sweep' gives sufficient guidance for an agent to select it when building a candy-cane sweep path.

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