catia_create_sketch

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

Annotations only say readOnly=false and destructive=false, which are thin. The description adds the crucial behavioral fact that the tool both creates and opens an active sketch context, and that subsequent sketch calls target this sketch until closed or replaced. This stateful behavior is exactly the kind of side effect an agent needs to know.

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?

Two sentences carry all the essential information: the purpose, the support syntax, and the stateful behavior. There is no filler or redundant restatement of the schema.

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 creation tool with no output schema and sparse annotations, the description covers the main invocation workflow and the active-sketch lifecycle. It does not mention prerequisites such as an open document or existing body, but the schema's body default and support descriptions fill in most gaps.

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?

The schema already documents all five parameters with descriptions, so the baseline is 3. The description goes beyond the schema by explaining the support token semantics: origin planes, face references ('face#3', 'face@x,y,z') for faces of the solid, and construction-plane names. It does not add detail for origin or horizontal_direction, but the schema handles those.

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 first sentence names the exact action ('Create a sketch'), the target ('on a plane or a planar face'), and the mode ('open it for drawing'). It also references the sibling family 'catia_sketch_*' as downstream consumers, so an agent can distinguish this entry-point tool from the individual sketch-drawing tools.

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 gives clear sequencing: create a sketch, then draw with catia_sketch_* until you close it or create another. This tells an agent when this tool is the right entry point, though it never names the explicit alternative catia_close_sketch or warns against creating a new sketch while one is already being drawn on.

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