plasticity_convert_curve_vertices_to_control_points

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

Annotations already mark this as destructive and non-read-only, but the description adds substantial behavioral context: the Wire path, segment structure, length, and topology all change, all old vertex and segment references must be discarded, and the returned Wire must be inspected before continuing. This is exactly the invalidation and mutation detail an agent needs beyond the annotations.

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 purpose is front-loaded in the first sentence, followed by prerequisites, exclusions, and the critical post-call warning. Every sentence adds operational value with no filler.

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 destructive, no-output-schema mutation tool, the description covers the source of references, current-revision requirement, unsupported inputs, topology-changing consequences, reference invalidation, and the need to inspect the returned Wire. Nothing critical is missing for correct invocation and safe follow-up.

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%, so the description must carry the burden. It meaningfully constrains the vertices and revision inputs by requiring current-revision references from plasticity_list_curve_vertices and excluding open endpoints, but it says nothing about the optional intent parameter or the bodyId/vertexId shape beyond what the schema itself defines.

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 verb and resource: converting exact current interior or closed Wire vertices into native B-Spline control vertices. It also distinguishes the operation from adjacent curve tools by requiring references from plasticity_list_curve_vertices and excluding open endpoints.

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 gives clear preconditions: references must come from plasticity_list_curve_vertices at the current revision, and open endpoints are not convertible. It does not explicitly name an alternative conversion tool, but the when-to-use context is strong and unambiguous.

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