plasticity_loft_faces

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

Annotations already flag this as a non-readonly, destructive, closed-world mutation. The description adds real value beyond that: it clarifies that sources are preserved, that the operation produces an independent native capped solid, how the two ends are controlled by end conditions, and warns to verify the returned B-Rep rather than trusting magnitude as a distance. That magnitude caveat is exactly the kind of behavioral context annotations cannot convey.

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 dense sentences, front-loaded with the action and resource, then constraints, then end-condition semantics. Domain jargon is heavy but each sentence earns its place; nothing is redundant 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?

There is no output schema and only partial annotation coverage, so the description must stand in for return and mutation semantics. It does address source preservation and the verify-the-B-Rep warning, but omits the meaning of the required revision parameter and the simplify/trimGuides toggles, which matter for calling a destructive tool correctly.

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 carries the full burden, and it partially does: it covers faces (ordered planar profiles), guideIds (wire guides intersecting every profile), and both end/start condition+?magnitude pairs. However it says nothing about revision (the required concurrency/state token), intent, simplify, or trimGuides, leaving four of ten parameters semantically opaque.

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: creating a capped loft Solid from an ordered list of planar faces drawn from existing Solid/Sheet bodies. The 'faces' framing implicitly distinguishes it from the sibling loft_curves and loft_regions, but it never names those siblings explicitly, so differentiation relies on inference.

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 offers a constraint ('optional guides must intersect every profile') and a verification caveat, which implies context of use, but it does not state when to choose this tool over loft_curves, loft_regions, or bridge_surface. The when-to-use guidance is only implied.

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