plasticity_offset_vertices

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

Annotations already flag this as a mutating, destructive, closed-world operation, so the bar is lower. The description goes beyond them by stating the consequence profile (outer shape and volume preserved while topology is rebuilt) and the crucial side effect that all topology references go stale and must be re-read after success. It stops short of describing failure modes or whether the operation is reversible.

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?

Three sentences, front-loaded with the operation, then the semantic guarantee, then the required follow-up. No filler and every sentence carries information an agent needs.

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 topology-rebuild operation with no output schema, the description supplies the shape-preservation guarantee and the mandatory reference re-read, which are the details most likely to cause agent error. It is only incomplete in not clarifying the revision parameter (concurrency/optimistic-locking semantics) and the intent field.

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 parameter burden. It partially does: 'one positive millimeter distance' matches distanceMm's exclusiveMinimum, and 'one or more current Solid or Sheet vertices from the same body' constrains the vertices array and its same-body requirement. But the required 'revision' parameter and the optional 'intent' parameter are never explained, leaving a required parameter undocumented in both schema and description.

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 names a specific verb (insert split vertices) and resource (Solid/Sheet vertices on a body) and pins down the exact manner of the operation (one positive mm along every incident edge). It also explicitly excludes what it is not (move/chamfer/fillet), which separates it from plasticity_fillet_curve_vertices and plasticity_move_edges without opening their schemas.

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 'does not move the corner, chamfer it, or fillet it' clause implicitly guides the agent away from alternative topology edits, and the closing sentence gives a required post-condition workflow step. However, no alternative tool is named and there is no explicit statement of when this tool should be chosen over e.g. plasticity_offset_edges, so usage is implied rather than directed.

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