create_reference_point

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

No annotations exist, so the description carries the full burden and does materially: it discloses that the coordinate is resolved by a SolidWorks coordinate pick and that InsertReferencePoint always returns a feature, so success is confirmed by the feature tree growing. It stops short of covering failure modes or required document state.

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 core action, then cleanly organized by mode; every sentence earns its place. The closing note about InsertReferencePoint is slightly at odds with the existence of an output schema but still conveys useful success-signal context.

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 nested-object tool with an output schema present, the description covers mode semantics, coordinate requirements and the success signal. Minor gaps remain around preconditions (active document/part must be loaded) and failure behavior.

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 already 100%, so the baseline is 3, but the description adds genuine meaning beyond the schema: the mutual exclusivity of distance/percent and the rule that the coordinate must lie on the referenced edge/face.

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+resource ('Create a reference point on the active part') and then unpacks it into the two distinct modes (along_curve, face_center), which cleanly differentiates it from siblings like create_reference_plane and create_axis.

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?

Gives clear mode-selection rules and an explicit constraint ('Give exactly one of distance / percent') plus the requirement that the coordinate lie on the target edge/face. It lacks an explicit statement of when to prefer this tool over create_reference_plane/create_axis, but the context is strong.

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