add_sketch

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

With no annotations, the description carries the full burden and does substantial work: it discloses the automatic dimensioning scheme (tangent relations, x<i>/y<i>, r<k>), the closing rule ('End on start_mm to close the outline'), and the fixed=True behavior of substituting Fix relations for dimensions. It stops short of stating failure modes, undo semantics, or that this is a mutating document operation.

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 summary sentence is front-loaded and every subsequent clause carries specification detail rather than filler. Density is justified by the complexity, though the plain-prose paragraph with mid-sentence line breaks is harder to scan than a structured segment list would be.

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 5-parameter, no-output-schema, no-annotation tool this is close to complete: it even previews return-value fields (origin_mm, x_axis, y_axis, points_mm) so the agent knows what comes back. The remaining gap is that the rest of the returned sketch object and error conditions are left unstated.

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 0%, so the description must compensate and largely does: plane enumerates the accepted values and coordinate mapping per plane, start_mm defines the origin convention, segments spells out each verb's object shape (line, arc with through/tangent, spline), and fixed explains the geometry mode. Only the optional trivial 'name' parameter is left implicit.

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 opening sentence gives a specific verb and resource ('Draw a sketch of lines, arcs and splines on a plane') and states the downstream intent ('to extrude or cut'). It is immediately distinguishable from sibling profile/primitive creators like add_extruded_profile or add_disc, which do not produce an editable sketch.

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 clearly routes the agent: 'Then extrude_sketch / cut_sketch the returned sketch', establishing the follow-up step. It also distinguishes the fixed=True mode as a variant for frozen geometry. What it does not do is state when to prefer this over a non-sketch primitive (add_box, add_disc) or a script-based path.

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