surface_extend

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 so well: it discloses unit resolution (plain number vs Fusion expression), identity retention with possible ref change plus the modified_bodies remedy, and two specific failure modes with codes and the note that a FUSION_API_ERROR leaves nothing changed. That is unusually complete side-effect and error disclosure.

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?

Labeled sections (Units, Refs, Errors, Returns, Example) front-load the core purpose and pack only actionable detail. No sentence is expendable given the domain vocabulary involved.

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?

With 6 parameters, no annotations and no output schema, the description supplies what is missing: the return structure including health and created/modified/removed bodies, plus an invocation example. An agent has everything needed to call it and interpret the result.

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 100%, so baseline is 3; the description still adds meaning beyond the schema by explaining units resolution (number vs string expression), that distance 0 is invalid, and that alignment='align' depends on API availability. It omits explicit discussion of chain and extend_type, so not a 5.

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+scope: 'Extend a surface body beyond its free edges by a distance (Extend feature)'. The surface-body/free-edge constraint cleanly separates it from sketch_extend, body_thicken, surface_offset and surface_ruled even without naming them explicitly.

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 concrete prerequisites and routing: refs come from inspect_query, and 'edges of a solid have no free side' tells the agent when this tool cannot apply. It also directs the agent to modified_bodies when refs change. It does not name competing siblings (surface_offset, surface_ruled) or state when-not conditions beyond that caveat.

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