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

With no annotations, the description carries the full behavioral burden and does well: library appearances are copied into the design, the source library is never changed, and the operation affects only visual appearance. It also discloses the return shape including previous and copied. It does not explain failure behavior or permissions, which keeps it below 5.

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 description is compact and front-loaded: purpose first, caveats second, return shape third, and an example last. Every sentence contributes useful information and no space is wasted.

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 mutation tool with no annotations and no output schema, the description is unusually complete. It covers allowed targets, the component restriction, the library-copy behavior, the distinction from material assignment, and the return structure, leaving little an agent needs to infer before calling it.

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 100%, so the schema already explains target, library, and appearance. The description adds a usage example and reinforces that appearance should come from appearance_list, but it does not add new meaning beyond the schema, especially for the library parameter. Baseline 3 is appropriate.

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 first sentence gives a specific verb and resource: assign an appearance to a body, face, or occurrence. It distinguishes the tool from material_assign by stating that it changes only the look, not the physical material. The target scope is clearly bounded.

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 description gives clear usage context: components have no appearance, so assignment must go to bodies or an occurrence, and material assignment is explicitly routed to material_assign. It does not compare against appearance_set_color or otherwise enumerate all sibling alternatives, so it stops short of a full 5.

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

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

With no annotations present, the description carries the full burden and does disclose the return envelope (items/total/truncated) and default scope behavior, which are the traits an agent most needs here. It stops short of stating read-only guarantees or any permission/precondition context.

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?

Scope statement is front-loaded in the first sentence, followed by the return shape and a single compact example. No filler, and each sentence contributes distinct information.

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, so describing the returned fields and the truncation flag is essential and is done here. All five parameters are covered by schema plus description, and the default-scope semantics are spelled out, leaving nothing an agent needs before calling.

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 the schema already documents each parameter; the description adds value by explaining the interaction between library and in_design (omitting library means all libraries) and by showing a concrete example call. It does not add format or edge-case detail beyond that.

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 (list) and resource (appearances / visual look) plus the three scoping modes: one library, all libraries (default), or the active design. This clearly separates it from siblings like appearance_assign and appearance_set_color, which mutate rather than enumerate.

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?

Explicitly states the default scope (every library) and the condition that switches to design-only results (in_design=true), plus points to material_list_libraries for resolving library names. It lacks an explicit 'not for assignment' note, but the read-only listing framing makes the boundary clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses that an identical copy made earlier is reused (returning "created": false), that library appearances are left untouched, and what the return payload contains. It does not cover permissions or whether the appearance is applied or only created/assigned beyond the implied assignment.

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-loads the action, then the reuse rule, then the non-mutation caveat, then an explicit return shape and a worked example. Slightly awkward phrasing ('with the RGBA colour is assigned') and the example is near-redundant, but there is no wasted content.

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?

No output schema exists, yet the description spells out the returned keys, the reuse flag, and the scope boundaries (design copies only, library untouched) — enough for correct invocation. What is missing is negligible: no note on how the assignment interacts with occurrence-level overrides.

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, but the description adds real semantics: `base` falls back to the target's current appearance, and the example shows the `target` ref plus a hex `color`. It does not explain the `name` default beyond the schema, but it does more than restate the schema.

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 and resource (assign a plain colour to a body/face/occurrence) and clarifies the mechanism: it creates a design copy rather than touching library appearances. The scope is clear, though the sibling `appearance_assign` is never named, so the distinction between the two has to be inferred.

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?

Usage is only implied: 'Library appearances are not changed' and 'a design copy of base' hint that this tool is for creating derived design appearances rather than assigning existing library ones. There is no explicit when-to-use or when-to-prefer-an-alternative statement.

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

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

No annotations are supplied, so the description carries the full burden — and it does disclose the key side effect (where new geometry goes) plus the exact return shape. It omits preconditions such as requiring an open/active document.

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 action and its effect, followed by the return contract and a concrete example. The example earns its place since there is no output schema, though it is slightly redundant with the prose.

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 one-parameter, no-output-schema tool this covers purpose, default behavior, and return values adequately. Error/failure behavior and document preconditions are the only notable gaps.

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 the schema already documents the single optional parameter; the description adds real meaning by explaining what omission does (activate root) and what activation implies for subsequent modeling operations.

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 (activate) and resource (an occurrence / the root component) and explains the practical effect — subsequent sketches and features land in that component. An agent can distinguish it from the sibling assembly_set_occurrence_state or document_activate.

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?

Explicitly covers the two calling modes: pass an occurrence to activate it, or omit the argument to return to the root component. It does not name alternatives or prerequisites (e.g., needing an occurrence ref from assembly_list), leaving some inference.

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

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

With no annotations, the description carries the burden and does well: it discloses the version prerequisite and error behavior for independent copies, the shared-edit semantics of instances (edits affect all instances), and the return shape. It omits things like undo behavior or what happens if `parent` is invalid, but the important behavioral traits are covered.

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 modes, then prerequisites and return shape, ending with a compact example. The example is useful but slightly redundant with the schema; overall it is tight and well ordered.

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 4-parameter mutation tool with no annotations and no output schema, the description supplies purpose, prerequisite, return shape, and an example. It lacks explicit guidance on picking this over sibling component-creation tools, but otherwise an agent has what it needs to call it 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 coverage is 100%, so the baseline is 3; the description adds value by clarifying that translate_mm is an offset in assembly space at this call, and the example concretely shows component/translate_mm usage. It doesn't elaborate on `parent` (e.g. how paths are formed) beyond what the schema already says.

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 and resource: insert another occurrence of an existing component, with the two modes (referenced instance vs independent copy) and placement (under root or `parent`, offset by translate_mm). This clearly distinguishes it from siblings like assembly_new_component and assembly_component_from_bodies, which create components rather than insert occurrences.

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 context: independent copies require a Fusion version with Occurrences.addNewComponentCopy, otherwise FUSION_API_ERROR, so the agent knows when the independent path is viable. It does not explicitly name the alternative tools (assembly_new_component / assembly_component_from_bodies) or state when to prefer them, so it stops short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does: it declares the operation is read-only in effect ('nothing is added to the design'), discloses a performance cost ('the full check is slow'), defines the default exclusion of merely-touching parts, and specifies the failure condition. That is a complete behavioral profile for a query tool.

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 purpose, then constraints, then return shape; each sentence carries information an agent needs to call it correctly. The inline return-shape block and the worked example overlap slightly, costing a bit of tightness, but neither is padding.

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?

No output schema exists, so the description supplies the full response contract — `checked`, `count`, and the interference entries with volume and bbox fields — plus a worked example. Combined with the parameter and cost guidance, an agent has everything needed to invoke and interpret it.

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, but the description adds real meaning: it explains that omitting `items` checks every occurrence plus root bodies, that `items` is the escape hatch for large assemblies, and that the minimum of two items is enforced with INVALID_PARAMS. It doesn't add format details on occurrence path syntax beyond what the schema already states.

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 and resource ('Check whether parts overlap') plus the exact payload returned (overlap volume in mm³ and bounding box in mm). It is clearly distinguishable from sibling measurement tools like measure_distance or inspect_bounding_box because it reports pairwise interference rather than single measurements.

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 when-to-use guidance: pass `items` on big assemblies because the full check is slow, and set include_coincident_faces=true only if touching parts matter. The error threshold (fewer than two items -> INVALID_PARAMS) is also stated. It stops short of naming a sibling alternative for simpler proximity questions, which is why it isn't a 5.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutation, position preservation, atomic failure behavior, and the critical fact that old body refs stop resolving. That is exactly the kind of post-call behavior an agent needs.

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-loads the purpose, then covers behavior and return shape, then a concrete example. The example and return block are somewhat redundant with each other, but both are useful for ref handling.

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?

No output schema exists, so the description compensates by specifying the exact return keys and showing body refs in '<token>@<occurrence path>' form. Combined with the atomicity and ref-invalidation notes, it is complete enough to call 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 coverage is already 100%: the schema documents that name is unique in the design and bodies must be owned by the same component. The description mostly repeats those constraints and adds an example, but does not add substantial parameter semantics beyond the schema.

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 and resource: turn existing bodies into a new component. It is distinguishable from siblings like assembly_new_component and assembly_add_occurrence because it explicitly consumes existing body refs and creates one occurrence in their current owner.

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 a clear condition for use and a hard precondition: all bodies must belong to the same component, otherwise INVALID_PARAMS and nothing moves. It does not explicitly name a competing sibling or say when not to use it, so it stops short of a 5.

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

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

With no annotations, the description carries the burden and does well: it discloses that no geometry is moved (the defining behavior of an as-built joint), that both occurrences must live in the root component, and that geometry is optional only for rigid joints. It omits failure modes — duplicate or conflicting joints, permission/activation preconditions, and whether an existing joint blocks creation.

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?

Four short, front-loaded sentences plus a compact worked example — the key constraint ('nothing moves') and the rigid/geometry rule come first. The telegraphic style ('refs inside occurrences look like...') costs a little readability but contains 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 mutation tool with no annotations and no output schema, it supplies the missing return shape ('Returns {"joint": ...}') and a concrete end-to-end example, which is exactly the gap left by the absence of an output schema. What remains unstated — preconditions around document activation and error behavior — matters but is secondary for a straightforward creation call.

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 100%, so the schema already documents occurrence refs, the geometry union, and the type enum; a baseline of 3 applies. The description restates the rigid-joint exception and the '<token>@<path>' ref shape that the schema already covers, adding only the pointer that motion keys follow assembly_create_joint, which is genuine but marginal added meaning.

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 and resource ('Join two occurrences') plus the distinguishing behavioral trait ('where they already are (nothing moves)'), which separates it cleanly from assembly_create_joint, the sibling that positions components. The creation scope ('in the root component') further narrows it so an agent can select it without opening the schema.

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 phrase 'where they already are (nothing moves)' implicitly defines the use case versus assembly_create_joint, and it repeatedly cross-references that sibling for shared semantics (motion keys, return shape). It does not explicitly state the inverse condition ('use assembly_create_joint when you need to place/position an occurrence'), so the exclusion is inferable rather than spelled out.

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

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

With no annotations, the description carries the full burden and does well: it discloses root-component placement, that geometry_one's part moves, the failure behavior ('Nothing is left on failure'), and the INVALID_PARAMS case for ambiguous native refs. It does not discuss permissions or broader destructive impact, keeping it below a 5.

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 description is long but front-loaded with the core purpose and then organized into refs, motion keys, return shape, and an example. For an 8-parameter joint creation tool, the detail is largely justified, though it is dense enough that some tightening could improve scanability.

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 no annotations, so the description needs to carry return and failure behavior, which it does by documenting the returned joint object and failure cleanup. It also covers reference formats, ambiguous reference errors, and per-type motion requirements, making it complete for correct invocation.

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?

Although schema description coverage is already 100%, the description adds substantial meaning beyond the schema: it defines the motion keys and defaults for each joint type, explains axis semantics, and clarifies that geometry_one is the moving snap while geometry_two is the target. The worked example further anchors expected parameter usage.

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: create a joint joining two parts, with the important scope note that it is created in the root component. It also clarifies which side moves, distinguishing the join semantics clearly enough for an agent to understand the operation.

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 description gives clear context for using the tool and explains how to obtain valid references via inspect_query. It does not explicitly compare against sibling tools such as assembly_create_as_built_joint or assembly_create_joint_origin, so it lacks full alternative routing guidance.

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

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

With no annotations, the description carries the burden and does well: it discloses the non-obvious storage semantics (origin is created in the owning component, so it moves with the part) and that occurrence-scoped refs like '<token>@Lid:1' are accepted and normalized. It omits mutation side effects, whether creation is idempotent, and what happens on failure, so it is not fully transparent.

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 purpose and the key structural behavior, then supporting detail. The return-value JSON and the worked example are somewhat verbose but both convey information an agent needs; little is wasted.

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?

No output schema exists, and the description compensates by spelling out the return shape (ref, native_ref, name, component) and the distinction between occurrence-context and in-component refs. Combined with the example and the downstream usage note, an agent has everything needed to call and consume 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 already 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by explaining how entity refs are interpreted across occurrence context and by walking through a concrete call with geometry, key_point, and offset_mm. It does not elaborate on flip/angle/name beyond the schema, so it is incremental rather than comprehensive.

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 and resource ('Create a joint origin') and immediately defines what it is ('a reusable snap point for joints') and where it lives (component that owns the geometry). It explicitly distinguishes itself from the sibling assembly_create_joint by describing the downstream consumption pattern.

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?

Explains the intended lifecycle: create here, then reference as {"kind": "joint_origin", ...} in assembly_create_joint. That is clear guidance on when this tool is the right one. It does not state exclusions or when-not-to-use (e.g., why not create the joint directly), so it stops short of full alternative routing.

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

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

Without annotations, the description carries the behavioral burden and does so well for core behavior: it explains that occurrences move as one, requires different occurrence refs, and states 'Nothing is left on failure,' which discloses atomic failure behavior. It does not cover permissions or all side effects, but the main behavior is transparent.

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 and prerequisite are front-loaded, followed by failure behavior and return shape. The example is useful and does not obscure the key call requirements.

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 no annotations and no output schema, the description compensates by stating prerequisites, failure semantics, return object shape, and a concrete example. That is sufficient for an agent to call the 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 coverage is 100%, so the schema already documents occurrences, name, include_children, and even the occurrence path example. The description reinforces the two-occurrence minimum and assembly_list source, but mostly repeats schema content rather than adding substantial new parameter meaning.

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: 'Lock occurrences together so they move as one (a rigid group in the root component).' This clearly distinguishes the tool from assembly joint creation and timeline group tools by specifying the rigid-group concept and root-component scope.

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 concrete usage conditions: at least two different occurrences, using 'occurrence:<path>' refs from assembly_list, with INVALID_PARAMS otherwise. It lacks explicit routing to alternatives such as assembly_create_joint or timeline_create_group, but the context for when this tool applies is clear.

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

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

With no annotations, the description carries the burden and discloses important behavior: invalid inputs are refused, and deleting the last occurrence of a component removes the component from the design. It also describes the return shape. It does not discuss irreversibility, permissions, or undo behavior, so it is strong but not complete.

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 description is short and front-loaded around the deletion scope and alternatives. The return shape and example are included without unnecessary 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 one-parameter delete tool with full schema description coverage and no output schema, the description covers scope, alternatives, refusal behavior, side effect, return shape, and an example. Nothing essential for correct invocation is missing.

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 the schema already documents the single item parameter. The description adds useful meaning with an example reference format, occurrence:Box:2, though it does not fully document reference syntax beyond that example.

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 precisely enumerates the resource types it deletes: occurrences, joints, as-built joints, joint origins, and rigid groups. It explicitly distinguishes itself from siblings by naming body_delete, sketch_delete, and timeline_delete for other entity types.

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 clearly states when to use this tool by listing accepted entity types and when not to use it by saying other entities are refused with INVALID_PARAMS. It also names the alternative sibling tools for those refused cases.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that Fusion clamps values to joint limits, reports offending dofs in 'clamped', and that values are restored if Fusion fails. It also explains the capture_position side effect (a timeline 'Position' snapshot) and the complete return shape.

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?

Purpose is front-loaded in the first clause, followed by behavioral caveats, return shape, and a worked example — every block earns its place. The parenthesized return-shape enumeration is dense but functional; structure could be slightly tighter.

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 mutation tool with no output schema and no annotations, the description supplies everything an agent needs: what it does, limit-clamping semantics, failure rollback, the exact return keys, and a worked call/response pair. Nothing essential is missing.

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 the baseline is 3, but the description adds meaning beyond the schema by explaining the clamped/requested relationship and by showing in the example how the request key 'rotation' surfaces as 'rotation_deg' with the actual applied value. It does not add much on capture_position beyond what the schema states.

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 and resource ('Move a joint to the given values') and immediately grounds it with a concrete example ('open a hinge to 90 degrees'). This is clearly distinguishable from assembly_create_joint, assembly_set_joint_limits, and assembly_list_joints, which each operate on different aspects of joints.

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?

Usage is only implied by the verb 'move' and the hinge example; there is no explicit statement of when to prefer this over siblings like assembly_set_joint_limits or assembly_create_as_built_joint. Useful behavioral context (limit clamping, rollback on failure) is present but is not framed as guidance on choosing the tool.

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

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

With no annotations present, the description carries the full disclosure burden. It does well by publishing the complete return shape, including a 'truncated' flag, which signals that results can be capped. It never explains the truncation rule, what happens on a non-assembly document, or that the call is a read-only snapshot, so meaningful behavioral gaps remain.

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 sentence is front-loaded and the return documentation is dense but genuinely informative given the absence of an output schema. The final 'Example' line largely restates the schema-of-return already given, so a small amount of the length is redundant.

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?

Because there is no output schema, the description takes on the burden of describing returns and does so thoroughly, down to the occurrence object's fields. It falls short only on truncation/limit behavior and preconditions (e.g. requiring an active assembly context), which an agent would need to call it confidently.

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?

There is one parameter and schema coverage is 100%, with the schema itself describing it as 'Max components and max occurrences', so baseline 3 applies. The description never mentions the limit at all, so it adds nothing beyond the schema and does not connect the limit to the 'truncated' return field.

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 opens with a specific verb and resource ('List the assembly structure of the active design') and then enumerates exactly what is included: components, nested occurrences by path, transform, grounded/visibility flags and joint counts. That level of specificity lets an agent distinguish it from inspect_tree or assembly_list_joints without consulting the schema.

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?

Usage is implied by the scope ('active design') and the listed return fields, so an agent can infer this is the structure-inspection call. However, there is no explicit when-to-use statement, no exclusion, and no routing to alternatives such as assembly_list_joints for joint detail or inspect_tree for the general model tree.

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

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

No annotations are provided, so the description must carry the behavioral burden. The verb 'List' and the detailed return contents make the read-only diagnostic purpose clear, but it does not explicitly state side effects, permissions, or active-document requirements.

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 description is front-loaded with purpose and usage, then justifies its length with detailed return-object documentation and an example because no output schema exists. Every section adds useful information without 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 no-parameter list tool with no output schema and no annotations, the definition is complete: it explains what is listed, when to use it, and the exact shape of the returned joints, joint origins, and rigid groups.

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?

There are zero parameters, so there is no parameter semantics to document. The empty input schema is sufficient, and the baseline for zero-parameter tools applies.

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 and resource set: 'List the joints, as-built joints, joint origins and rigid groups of every component', with the exact data returned (values, limits, suppression, health). It is clearly distinguishable from sibling tools like assembly_drive_joint and assembly_create_joint because it is a read/list operation.

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 a clear use case: 'Use it to check a mechanism after assembly_drive_joint.' However, it does not name exclusions or alternatives such as assembly_list for components, so it stops short of full when/when-not guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It discloses that the new component is empty, that exactly one occurrence is created, that parent defaults to root, and that the whole call is undone on failure. It also documents return shape, which is important because there is no output schema.

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 core action is front-loaded and the description is generally efficient. The return-shape details and example are useful given the lack of an output schema, though they add some length and slight redundancy.

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 mutation tool with no annotations and no output schema, the description is complete enough: it explains the created objects, parent behavior, offset semantics, failure atomicity, and expected return structure.

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 100%, so the schema already documents all three parameters. The description reinforces parent placement and translate_mm units, but it adds little beyond what the schema provides.

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: create an empty component with one new occurrence. It also specifies scope (under root or inside the parent component) and optional offset, which clearly distinguishes this from sibling tools that add occurrences or create components from bodies.

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 description gives clear usage context: create the component first, then build geometry after activating it via assembly_activate or by targeting the component. It does not explicitly contrast with sibling alternatives such as assembly_add_occurrence or assembly_component_from_bodies, but the intended workflow is clear.

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

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: it discloses the non-obvious side effect that occurrence paths embed the component name, that dependent refs break with ENTITY_NOT_FOUND, the exact failure mode for the root component, and the return payload shape.

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 purpose followed by a clearly marked WARNING, then return shape, then a compact example. Every block (constraint, side effect, return, example) earns its place and nothing is redundant.

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 two-parameter mutation tool with no annotations and no output schema, the description supplies the return structure, error codes, and the downstream ref invalidation an agent could not infer. Nothing needed to invoke or recover from the call is missing.

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 100%, so both parameters are already documented, which sets the baseline at 3. The worked example ('component="component:Box", name="Case"') does illustrate the ref format and expected emission, but adds only marginal meaning beyond the schema.

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 and resource ('Rename a component') and its scoping constraint (root component cannot be renamed). The 'component:<name>' ref vocabulary and the occurrence-path discussion separate it from sibling renames such as body_rename or timeline_rename, though those siblings are never named 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 a clear exclusion ('the root component cannot be renamed (INVALID_PARAMS)') and actionable follow-up guidance ('use the returned paths' because old occurrence and proxy refs stop resolving). It stops short of naming an alternative tool to use when a rename is not appropriate.

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

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

With no annotations, the description carries the full burden and does well: it discloses mutation semantics (omitted keeps the existing limit), validation failure mode (INVALID_PARAMS), and the return payload shape with a worked example. It omits permission/undo considerations, but the critical behavioral facts for correct invocation are present.

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 action and units, then constraints, then return shape and example — dense and mostly waste-free. Some unit/'off' semantics duplicate the schema text, a minor redundancy in an otherwise efficient block.

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?

No output schema exists, yet the description supplies the return structure, an example response, the error code on invalid input, and full DOF validity rules. An agent has everything needed to call it correctly in one read.

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 would be 3, but the description adds real meaning: the enable/disable/keep semantics of null vs number vs 'off', the per-joint-type valid DOF mapping, and the min<=max constraint. This goes beyond the terse schema descriptions.

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 and resource ('Set the motion limits of one degree of freedom') and immediately enumerates the DOF vocabulary in units, so the agent knows exactly what is being modified. It is clearly distinguishable from sibling joint tools (assembly_create_joint, assembly_drive_joint, assembly_list_joints).

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 preconditions — dof must exist for the joint type (with a per-type mapping) and min must not exceed max — plus the value convention (number enables, 'off' disables, omitted keeps). It does not explicitly compare against alternatives such as assembly_create_joint, which may also accept limits, so no exclusion guidance.

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

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

Since no annotations are provided, the description carries the full burden. It successfully communicates the operational behavior (ground/visibility change) and provides the precise return structure, which adds valuable behavioral context beyond the input schema.

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 definition is brief and efficient. It uses two concise sentences and an example to convey the core functionality, constraints, and expected output without unnecessary fluff.

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?

Given the lack of annotations, the description is highly complete. It covers the primary actions, the required arguments, and the expected response format, leaving no ambiguity for the agent.

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?

The input schema provides 100% coverage with clear descriptions for all parameters. The description does not add new semantic meaning beyond what the schema already documents, though it correctly notes which properties are actionable.

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 clearly defines the action (Ground/unground/switch light bulb) and the resource (an occurrence). It is specific enough to distinguish this state-setting tool from generic assembly modification tools in the sibling list.

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 phrase 'Pass at least one of grounded, light_bulb' serves as a mandatory usage constraint, preventing the agent from calling the tool without necessary parameters. The provided example also clarifies correct usage.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses mutation semantics, grounded-occurrence refusal behavior, joint-recompute override behavior, position-capture behavior, and the exact return keys including constrained_by_joints. It also provides a concrete example with expected response shape.

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 definition is front-loaded with the core operation and mode distinctions, then failure cases, then return shape, then a compact example. Every sentence contributes actionable information with no wasted framing.

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 mutation tool with no annotations and no output schema, the description is complete: it covers operation modes, constraints, error behavior, required ungrounding workflow, joint-related caveats, and return-value structure. An agent has enough information to call it correctly and interpret common outcomes.

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 100%, so the baseline is 3. The description adds useful semantic context beyond the schema: it explains relative versus absolute modes, the order of rotate then translate, units of mm/degrees, and gives an example of rotate and translate values. It does not add much beyond the already detailed nested schema, so a 4 rather than 5 is appropriate.

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 starts with a specific verb and resource: 'Move an occurrence in assembly space.' It distinguishes the two supported modes, relative and absolute, and names the exact sibling needed to unground an occurrence, so an agent can identify the tool without opening its schema.

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 explicitly states when the tool refuses to operate (grounded occurrences, with INVALID_PARAMS), what to do instead (use assembly_set_occurrence_state first), and how to handle joint-controlled occurrences (drive joints instead). These are concrete when/when-not guidance with named alternatives.

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

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

With no annotations, the description carries the full burden and does well: it discloses failure modes (INVALID_PARAMS with nothing changed, FUSION_API_ERROR with rollback) and the resolution path via details.cells center/volume. It does not spell out the side effect on tool bodies when remove_tools is left at its default, which keeps it off a 5.

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-loads the one-line purpose, then scope rules, ref provenance, errors, return shape and an example in tight blocks. Dense but nearly every line earns its place; the error sentence is slightly overloaded.

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?

No output schema exists, yet the description supplies the return keys (feature, health, created/modified/removed_bodies), the error contract, and a concrete example. An agent has everything needed to invoke this correctly on the first try.

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 3 is the baseline, but the description adds genuine meaning: cell_points selects by containment rather than index, omitted means every cell, tools are entity refs sourced from inspect_query/origin prefixes. Units behavior for the point coordinates is only partly covered.

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?

Names a specific verb+resource (boundary fill producing solids from closed cells) and states the exact precondition — cells enclosed by tool bodies, faces and planes. It is clearly distinguishable from adjacent body tools such as body_combine or body_split.

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?

Explains how cells are selected (points, never index; all cells by default), where refs come from (inspect_query for bodies/faces, origin:*/construction_* for planes) and gives a worked example call. It stops short of explicitly contrasting with sibling tools like body_combine, so it is strong context rather than full when/when-not routing.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses mutation of the target, consumption of tools, component creation, ref token invalidation after the feature, and specific error behaviors (INVALID_PARAMS with nothing changed, FUSION_API_ERROR with rollback). This is unusually complete for a mutation tool.

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 description is front-loaded with the core action, then behavior, refs, errors, returns, and an example — a logical progression with no filler sentences. The parenthetical asides are dense but each carries load.

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, but the description explicitly lists the return keys (feature, health, created_bodies, modified_bodies, removed_bodies, plus component), and covers error cases and ref lifecycle. An agent has everything needed to invoke and interpret the call.

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 the baseline is 3, but the description adds meaning beyond the schema: how keep_tools affects removed_bodies, that new_component yields a 'component' key in the result, and what target vs tools mean semantically. It stops short of documenting the ref token format that the schema's item description covers.

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 opens with a specific verb+resource (boolean combination of bodies) and enumerates the three operations (join, cut, intersect) against a target body. This is clearly distinguishable from siblings like body_split or surface_stitch.

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 sets clear context: the target receives the result, tools are consumed unless keep_tools is true, and refs must come from inspect_query or earlier results. It does not explicitly name alternatives or exclusion conditions (e.g. when to prefer body_split or surface_stitch), keeping it below a 5.

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

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

With no annotations, the description carries the load and does it well: it discloses automatic gap healing, two distinct error modes with their error codes and whether state is preserved or rolled back, and the shape of the returned payload. The remaining gap is undo/timeline-editability context for a destructive operation.

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 purpose followed by input provenance, error behavior, return keys, and an example — each line performs a distinct job with no filler or repetition of the schema.

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?

No output schema exists, so documenting the return keys is necessary and done here; combined with error codes, rollback behavior, prerequisite sourcing, and an example, an agent has everything needed to invoke this 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 coverage is 100%, so baseline is 3; the description adds real value by telling the agent where the refs must come from (inspect_query on the latest body) and warning to re-query after subsequent features. The example also shows multiple faces accepted at once, which the schema does not convey.

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 ('Delete faces from a body') and immediately clarifies the distinctive healing semantics (e.g. remove a fillet or a boss), which separates it from body_remove (whole body) and body_replace_face without needing the schema.

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 a concrete prerequisite ('Faces from inspect_query on the latest body') and a worked example call, plus the caveat to re-query after later features. It stops short of naming alternatives such as body_remove or timeline_edit_fillet, so it does not reach the top band.

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

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

With no annotations, the description carries the full burden and does so: it discloses failure modes (INVALID_PARAMS for non-rigid matrix or wrong ref kind, with nothing changed; FUSION_API_ERROR for legacy expressions/component-space moves) and exactly which bodies move or are copied. It also describes the return payload, including the 'copy' field when keep_original is set.

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-loads the one-line purpose, then organizes transforms, refs, errors, returns, and examples into scannable chunks. Dense but each paragraph carries information; slightly long for a single tool.

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 mutation tool with no output schema and no annotations, it covers transforms, ref sources, error taxonomy, mutation semantics (copy vs move), return shape, and concrete examples. An agent has everything needed to call it 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 coverage is 100%, so baseline is 3; the description adds value by explaining transform variants that the schema only enumerates: design_space=false uses component axes, matrix must be rigid row-major with translation in `units`, translate_along takes a straight edge/axis plus distance, and rotate_about takes a point plus direction. Some overlap with existing schema descriptions keeps it from 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 (move/copy) and resource (bodies) and explains that it creates a Move feature in the timeline. It distinguishes itself from pattern_* (associative copies) and body_scale (scaling), so the agent can separate it from siblings at a glance.

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?

Explicitly routes the agent: use pattern_* for associative copies, body_scale for scaling, inspect_query for body/edge/vertex refs, and origin:*/construction_* for axes and points. keep_original semantics (copies are non-associative) are stated outright.

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

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

With no annotations present, the description carries the full burden and does so thoroughly: it discloses reversibility per mode, the direct-design override with mode_used='delete', and the partial-failure caveat that a later failure cannot restore earlier deleted bodies. It also documents error behavior (non-body ref -> INVALID_PARAMS, nothing removed) and the return shape, which is more than most mutation tools provide.

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 text is front-loaded with the core action and then layered as mode semantics, errors, returns, and an example, with no filler sentences. The trailing example ('body_remove(bodies=[<tool body>])') is largely redundant given the required-parameter schema and is the only part that does not earn its space.

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 the description compensates by enumerating the returned keys (removed, features, mode_used). Combined with the mode semantics and the documented error case, an agent has everything needed to call this mutation safely without further probing.

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 would be 3, but the description adds real meaning the schema alone does not: it explains what happens downstream in the timeline for each mode and the special direct-design case where mode is ignored. The bodies parameter is explained mainly by reference to inspect_query, which is adequate given the schema's own item-level ref documentation.

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 opens with a specific verb+resource ('Remove bodies from the design') and immediately splits the operation into two well-defined modes, so the agent knows exactly what the tool does. It stops short of differentiating itself from nearby siblings such as body_delete_faces, body_split, or assembly_delete, so an agent still has to infer the boundary from names alone.

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 conditional guidance for the key decision: mode=remove keeps a timeline feature that can be suppressed/deleted to restore bodies, mode=delete removes them, and direct designs always delete regardless of mode. What's missing is any statement of when to reach for this tool instead of the adjacent body-editing or assembly-deletion tools.

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

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

With no annotations present, the description carries the burden and does well: it declares the exact return payload ({"body": {ref, type, name}, "previous_name": str}) and the failure modes (empty name, non-body ref -> INVALID_PARAMS). It omits whether renaming affects downstream references or is reversible, which would matter for a mutation.

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 core constraint is front-loaded in the first line, followed by return shape, error modes, and one compact example. Every line earns its place 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 two-parameter mutation with no annotations and no output schema, the description supplies the return shape and error contract that structured fields would otherwise provide. Only side-effect scope (impact on dependent features/references) is left unstated.

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 100% and both parameters are documented in the schema ('Body ref', 'New name (trimmed)'). The description's example confirms the parameter shape but adds no semantics beyond the schema, so baseline 3 applies.

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 and resource ('Rename a body') and immediately scopes it with '(not a timeline feature)', which separates it from the sibling timeline_rename. An agent can pick this tool without opening either schema.

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 parenthetical exclusion implicitly routes timeline feature renaming to timeline_rename, giving the agent a clear decision boundary. It stops short of naming that sibling outright or describing prerequisites (e.g. body must exist in the active design).

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

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

With no annotations, the description carries the behavioral burden well: it discloses the body-growth/shrink effect, invalid-target behavior with INVALID_PARAMS and no changes, and FUSION_API_ERROR with rollback. It does not cover permissions or idempotency, but mutation and failure semantics are substantially explained.

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-loads the core operation, then organizes refs, errors, return keys, and an example into compact sections. Every line contributes actionable information without unnecessary prose.

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?

No output schema exists, so the description usefully names the return keys and error cases, and the example clarifies invocation. It could further clarify return-value meanings such as health, but is otherwise complete for this CAD mutation tool.

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 all three parameters are already documented in the schema, including tangent_chain's default. The description reinforces ref sources and target validity but adds little parameter-level meaning beyond the schema, matching the baseline for high schema coverage.

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 and resource: replace faces of a body with a target face, plane, or surface body, and describes the geometric effect (body grows or shrinks). This clearly distinguishes it from face-deletion or offset operations.

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?

Provides valid sources for face refs, planes, and surface bodies, and explicitly says a solid body is not a valid target. It stops short of naming when to choose sibling tools like body_delete_faces or feature_offset_faces, but the usage context is clear.

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

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

With no annotations provided, the description carries the full burden and does well: it specifies that factors are unitless with no unit conversion, that exactly one of factor or factors should be passed, and that INVALID_PARAMS errors leave nothing changed. It also lists return fields, though it does not discuss permissions, reversibility, or whether bodies are modified in place versus creating new bodies.

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 description is front-loaded with the core operation, then compactly covers constraints, references, errors, return shape, and examples. Every sentence adds useful information for correct invocation.

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 mutation tool with no annotations and no output schema, the description is quite complete: it covers parameter usage, validation errors, return fields, and examples. Minor missing context includes how the operation affects the timeline or whether it always creates a feature versus modifying bodies in place.

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 the baseline is 3. The description adds meaningful semantics beyond the schema: it clarifies that factors are unitless and > 0 or Fusion expressions, that factor and factors are mutually exclusive, and where valid body and point references originate.

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: scaling bodies about a base point, with uniform and per-axis modes. It is clear what the tool does, though it does not explicitly differentiate itself from other body transformation siblings such as body_move.

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 description explains how to choose between factor and factors and where body and point references come from, which implies usage context. However, it does not state when to use this tool versus alternatives like body_move or when scaling would be inappropriate.

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

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

With no annotations provided, the description carries the full burden and does so well: it discloses atomic rollback behavior, the meaning of is_visible versus light_bulb, hidden-component inheritance, error conditions, and the return shape. That is substantial behavioral context beyond the schema.

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 description is front-loaded with the core action, then layers atomicity, effective visibility, errors, return shape, and an example. It is appropriately sized and every section adds useful information.

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?

Although there is no output schema and no annotations, the description compensates by documenting the result object, error behavior, atomicity, and effective visibility semantics. An agent has enough information to call it 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 coverage is 100%, so the baseline is 3, but the description adds important parameter interplay: at least one of visible or opacity must be supplied, and opacity must be within 0..1. It also clarifies that visible controls the light bulb while opacity controls transparency.

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 clearly states a specific verb and resource: show/hide bodies via light bulb and/or set opacity. It is distinct in meaning, though it does not explicitly contrast itself with nearby body/appearance tools, so it falls short of full sibling differentiation.

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?

Usage is implied by the stated capability, but there is no explicit guidance on when to choose this tool over related tools such as appearance_set_color or body tools. The description gives operational behavior, not selection guidance.

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

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses mutation outcomes (created_bodies, modified_bodies, removed_bodies), error modes, and rollback behavior for failed splits. It also documents the return keys, giving the agent a clear picture of side effects and failure handling.

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 description is front-loaded with the core operation and then compactly covers references, errors, returns, and an example. Every section earns its place, and the example reinforces correct invocation without bloat.

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?

Given the tool's mutation complexity, the lack of annotations, and no output schema, the description is complete: it covers purpose, valid inputs, error behavior, rollback semantics, return fields, and an example. An agent has enough information to invoke it 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 100%, so the input schema already documents all three parameters, including extend_tool. The description adds useful reference provenance for bodies and tool but does not explain extend_tool behavior, so it provides only marginal value beyond the schema.

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: split bodies into parts using a plane, face, or another body. It clearly identifies the operation and tool types, but does not explicitly distinguish itself from the sibling body_split_face, which could cause ambiguity.

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 provides practical usage context: valid references come from origin/construction planes, inspect_query, or earlier results, and it includes a concrete example. It does not explicitly state when to choose this tool over alternatives such as body_split_face, so it stops short of full guidance.

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

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

No annotations are provided, so the description carries the full burden, and it does: it names error codes and their causes (INVALID_PARAMS with no change, FUSION_API_ERROR for unsupported split types), gives the default of extend_tool, and enumerates the returned keys including health and created/modified/removed bodies. This is well beyond a bare purpose statement.

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 purpose, then a compact mode list, a refs line, an errors line, a return shape, and one concrete example — every line carries distinct information 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 5-parameter mutation tool with no annotations and no output schema, the description covers what it does, valid inputs, failure modes, and the return payload, which is everything an agent needs to call it 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 coverage is 100%, so the baseline is 3, but the description adds the cross-parameter constraint (along_vector requires direction; direction with any other type is an error) and clarifies extend_tool's role in relation to the tool. Marginal gain is real, though the per-parameter meanings themselves are already in the schema.

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 and resource ('Split faces of a body with a tool') plus the reason (separate faces for draft, offset, colors), which distinguishes it from body_split, body_delete_faces, or surface_trim. An agent can tell what it produces — new faces — without opening anything.

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?

Explains the three split modes (intersection along the tool, along_vector projecting along direction, closest_point) and where to obtain valid refs (inspect_query, origin:*/construction_*, sketch_* results). It doesn't explicitly route the agent between this and body_split or body_delete_faces when the goal is ambiguous, but the operational conditions for each mode are clear.

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

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

No annotations exist, so the description carries the full burden, and it does real work: it declares the failure modes and their atomicity ("INVALID_PARAMS (nothing changed)", "FUSION_API_ERROR, rolled back") and the exact return payload. It omits permission/selection preconditions, but the mutation semantics are unusually well disclosed.

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?

Purpose is front-loaded, followed by units, errors, return shape and an example, in a scannable labelled layout. Minor redundancy in restating the units default already present in the schema.

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 no output schema, the description correctly supplies the return payload, and it covers error behavior and the thickness/unit semantics for a 6-parameter mutation tool. It leaves the `operation` modes (join/cut/intersect) unaddressed in prose, which matters for predicting whether existing bodies are altered.

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 the baseline is 3; the description still adds meaning by clarifying that thickness may be a plain number in `units` or a Fusion expression, plus a concrete invocation example. `chain`, `symmetric`, `operation` and `faces` semantics are left entirely to the schema.

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 and resource ("Thicken faces ... into a solid") with a scope qualifier ("usually of a surface body") that separates it from surface tools. It never names a sibling it supersedes or replaces, so the differentiation is implied rather than explicit.

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?

"Faces from inspect_query" gives a workflow link and the input provenance, and the schema adds the re-query-after-later-features caveat. It does not say when to use this over feature_offset_faces, body_boundary_fill or a surface route, so usage is only implied.

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

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

With no annotations, the description carries the full burden and does so: it discloses the two distinct failure modes (INVALID_PARAMS with a structured details payload for wrong entity kinds, FUSION_API_ERROR for unbuildable geometry) and states that a failed build leaves the timeline unchanged. It also spells out the return payload inline, so the agent knows what it gets back.

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 a compact table for the branching logic, then error behavior, then two concrete call examples. Dense but every block carries distinct information; no sentence is redundant with the schema.

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 9-parameter tool with one required discriminator, no output schema, and no annotations, this covers everything an agent needs: method selection, ref syntax, failure semantics, mutation-on-failure guarantee, and return shape. There is no meaningful gap left.

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 would be 3, but the description adds something the schema structurally cannot express: the per-method field requirements in the table, including how many points 'two_points' needs and the constraint that the 'perpendicular_at_point' point lies on the given face. It also documents the ref-string vocabulary and points at inspect_query for deriving face refs.

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?

Opens with a specific verb+resource ('Create a construction axis') and immediately names the downstream consumers (revolve, circular patterns, joints). An agent can distinguish this from construction_plane and construction_point without inspecting either schema.

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 method table is effectively a decision guide: it tells the agent which geometric situation maps to which method (two points, straight edge, cylindrical face, face+point, two planes). What is missing is sibling-level routing — nothing says when to reach for construction_plane or construction_point instead — so it stops short of explicit when-not guidance.

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

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

With no annotations, the description carries the full burden and does: it discloses that mismatched fields yield INVALID_PARAMS with the accepted field list, that wrong entity kinds return details {param, expected, got}, and that a Fusion failure raises FUSION_API_ERROR and leaves the timeline unchanged. It also notes units (mm/degrees) and that string expressions keep the plane driven by that expression — genuine behavioral context not available in the schema.

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?

One-line purpose, then a compact table, then ref/units/error notes, then return shape and three examples. Front-loaded and dense with no filler sentences; the table replaces what would otherwise be paragraphs of prose.

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 14-parameter, single-required-parameter tool with no output schema, the description supplies the method matrix, ref formats, error contracts, and the return object shape (ref, type, name, origin_mm, normal, health, warning), which is exactly what an agent needs to call it 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 coverage is 100%, so the baseline is 3; the description goes beyond it by documenting cross-parameter constraints (method → exactly its fields) and the ref grammar `origin:XY|XZ|YZ|X|Y|Z|O`, which the per-property descriptions only partially cover. Units and expression-string semantics reinforce this.

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?

Opens with a specific verb and resource ('Create a construction plane') and immediately states its role ('a reference for sketches, mirrors, splits'). Alongside siblings construction_axis and construction_point, the plane/axis/point distinction is clear from the name plus this gloss.

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 method table is effectively usage guidance: each row tells the agent which defining fields a given construction mode requires, with inline qualifiers ('midway between them', 'coplanar straight edges', 'cylinder/cone'), and it warns that extra fields are refused. It lacks explicit 'when to use this instead of constructing a sketch plane' or exclusions versus siblings, so it stops short of a 5.

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

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

With no annotations, the description carries the burden and does so well: it discloses the two failure modes (INVALID_PARAMS with details{param, expected, got} for wrong entity kinds; FUSION_API_ERROR for unbuildable definitions), states that failed builds leave the timeline unchanged, and previews the return payload including a possible warning. It stops short of mentioning permissions or how the point appears in the timeline on success.

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 verb, then a compact decision table, then pitfalls, return shape and two short examples — every block earns its place. The closing examples overlap somewhat with the table's method list, which is the only waste.

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 10-parameter mutation tool with no annotations and no output schema, the description covers the conditional parameter contract, accepted ref syntax and provenance, error behavior, and the return fields. An agent has everything needed to call it correctly without opening anything else.

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 genuinely new meaning the schema cannot express: the conditional mapping of each `method` value to exactly which of the 10 optional fields must be supplied, plus the intersection/center semantics of each method. It also names accepted ref forms and the source tool for them.

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?

Opens with a specific verb+resource ('Create a construction point') and immediately scopes it with concrete use cases (joint origin, hinge center, sketch anchor). It also explicitly draws the boundary against the nearest confusable operation, sketch points made by coordinates via sketch_draw.

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 method table tells the agent exactly which case applies and which fields go with it, and it routes the coordinate-based case to sketch_draw and points the agent at inspect_query for refs. It doesn't address the neighboring construction_axis/construction_plane tools or assembly_create_joint_origin, but for this resource the guidance is clear.

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

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

With no annotations, the description carries the full burden, and it does disclose the return contract including the direct-design null case for timeline_count. However it omits operational behavior: what happens if no document is active, whether it requires an open/linked document, and confirmation that it is non-mutating.

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 one-line purpose followed by a compact, well-structured return schema; every element listed is distinct and informative. Slightly dense formatting but no redundant text.

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, so the description must define the return value, which it does thoroughly (design_type, units, document, root_component, counts, and the direct-design null case). The only gap is the precondition around needing an active design and error 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?

Zero parameters, so there is nothing to disambiguate; the baseline of 4 applies. The description correctly implies the call is parameterless.

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 the resource (settings of the active design) and enumerates exactly which settings are returned, so an agent knows precisely what it gets. The read intent is implied by 'Returns' rather than an explicit verb, and it doesn't contrast itself with the design_set_units/design_set_type siblings, but the purpose is unambiguous.

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?

No when-to-use guidance, no mention of prerequisites (an active design/document must exist), and no pointer to design_set_units or design_set_type as the mutating counterparts. The agent must infer that this is the read-side twin of those setters.

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

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

With no annotations, the description carries the full burden and does so: it discloses that the operation deletes the entire feature history and parameters, that this is irreversible with no rollback, the exact guard parameter and its failure mode, and the returned fields ('changed', 'history_discarded'). This is exactly the destructive-operation context an agent needs.

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-loads the destructive consequence in the first paragraph, then preconditions, then return values, then a one-line example. Capitalized warnings and arrow notation make the two directions scannable, and no sentence is 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 two-parameter, no-annotation, no-output-schema tool, everything an agent needs is present: mode semantics, destructive side effects, guard requirement, error outcome, no-op case, return fields, and a usage example.

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 the baseline is 3; the description earns an extra point by explaining the consequence behind confirm_discard_history (what is actually discarded and that the user must agree) and by framing design_type as a mode switch rather than a plain enum. Some of the flag's wording overlaps the schema description, keeping it from 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 and resource: 'Switch the active design between parametric (timeline) and direct modelling,' with both enum states named. This clearly distinguishes it from read-only siblings like design_get_settings and from design_set_units, which changes unit preferences rather than modelling mode.

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?

Explicitly covers each direction (parametric -> direct, direct -> parametric, and same-type no-op), states the precondition (confirm_discard_history=true), instructs the agent to ask the user first, and names the failure behavior (INVALID_PARAMS, nothing changes). No inference is required.

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

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

With no annotations, the description carries the full burden and does well: it discloses the mutation's limited blast radius (display only, tool inputs unchanged) and states the return value references design_get_settings. It does not mention persistence with the document, undo behavior, or whether an active design is required, which keeps it from a 5.

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, followed by the critical caveat and return note in two short sentences. The example line is mildly redundant given the schema enum, and the odd line wrapping costs a little polish, but nothing is wasted.

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 single-parameter tool with no output schema, it covers purpose, the key semantic caveat, and where the return value is documented (design_get_settings). Missing only edge-case handling such as requiring an active design or persistence behavior, which are minor for this operation.

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% and the enum already constrains values to mm/cm/m/in/ft, so the schema does most of the work. The description adds real meaning by explaining what the parameter governs (display units and units for unitless expressions) and gives a concrete call example, going slightly beyond the schema's terse 'Distance display units'.

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 and resource ('Change the distance units Fusion displays and uses') and scopes it to the active design, plus explicitly clarifies what the change does NOT affect (numbers passed to tools stay in mm). This distinguishes it cleanly from the related design_get_settings, which it names as the return-value reference.

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 description gives clear context for use (changing display units / unitless expression units in the active design) and pre-empts the most likely misuse by stating that numeric values in tool calls are unaffected. It lacks an explicit 'use X instead when...' exclusion, but the scope is unambiguous.

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

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

With no annotations, the description carries the full burden and does so: it discloses the global side effect on all other tools, two specific error outcomes (INVALID_PARAMS with details.candidates for duplicate names, ENTITY_NOT_FOUND for unmatched refs), and the return shape including is_active. This is unusually complete behavioral 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?

The core purpose is front-loaded in the first clause, followed by error semantics, return value, and a single example with no filler. Every sentence earns its place.

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?

Although there is no output schema, the description documents the return value (document info as in document_list with is_active: true), the single parameter's format, and both failure modes, leaving nothing an agent needs in order to invoke it 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 coverage is 100%, so baseline would be 3; the description adds value by giving a concrete ref example ('document:file:urn:adsk.wipprod:dm.lineage:abc') and explaining what happens when the ref is ambiguous or unmatched, going beyond the schema's format note.

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 and resource (make an open document the active one) and immediately adds the consequence that all other tools operate on it, which separates it from document_list/document_open/document_save siblings. An agent knows exactly what state change occurs.

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 clause 'every other tool then works on it' tells the agent when this tool is needed (before any per-document operation), and the ambiguity/no-match failure modes describe edge conditions. It does not explicitly compare against siblings like assembly_activate, but the usage context is clear.

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

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

With no annotations, the description carries the burden well: it discloses the validation rule (exactly one of save_changes/discard_changes), the failure mode (INVALID_PARAMS, document stays open), and the prerequisite that save_changes requires a previously saved document. It stops short of saying what happens when closing the last open document or that discard is irreversible.

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 invoking condition is front-loaded in the first sentence, followed by the constraint, the return shape, and a one-line example. Every line serves a purpose, though the example is marginal and the return shape partially repeats the schema's semantics.

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?

No output schema exists, so spelling out the return payload is appropriate and useful for chaining (the new active document). Failure semantics and the save precondition are covered; only edge cases like closing the final document are unaddressed, which is minor for a 3-optional-parameter tool.

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 per-parameter meaning is already documented. The description adds a genuine cross-parameter constraint not expressible in the schema — exactly one of the two boolean flags must be true — plus the saved-document precondition for save_changes, which is real value beyond the schema.

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?

Names a specific verb and resource ('close the document') and makes the triggering condition unambiguous. It implicitly separates itself from document_save by routing saving to that tool first, but does not explicitly contrast with document_activate or document_open.

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?

States an explicit gate ('Call ONLY when the user explicitly asked to close the document'), names the alternative to use first ('call document_save with a name first'), and gives the failure outcome if flags are misused. An agent has no ambiguity about when to reach for this versus its siblings.

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

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

With no annotations, the description carries the behavioral burden and does well by describing the returned item shape, the ref format for saved versus unsaved documents, and the important rule that other tools work on the active document. It does not explicitly state read-only or side-effect behavior, but the list semantics are clear.

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 definition is front-loaded with the core action and then efficiently provides the returned item shape and ref semantics. Every sentence contributes useful information, especially because there is no output schema.

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?

No output schema exists, so the description compensates by documenting the returned object structure and the meaning of key fields such as ref, is_active, is_saved, and design_type. It is complete enough for an agent to call and use the result 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?

The tool takes zero parameters, so there are no parameter semantics to document. The description appropriately focuses on returned fields and ref usage instead.

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: list the documents open in Fusion. It also distinguishes this tool from document_activate, document_save, and document_close by explaining how to use the returned ref with those tools.

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 description gives clear usage context: pass each ref to document_activate, document_save, or document_close, and note that other tools operate on the active document. It does not explicitly state when not to use the tool, but the intended workflow is clear.

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

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

With no annotations, the description carries the burden and does a good job: it discloses the active-state effect, the persistence gap (not saved until document_save), and the display-vs-model unit gotcha. It omits what happens to the previously active document and whether unsaved work is at risk, which for a document-lifecycle tool would be useful.

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 and side effect, then the save caveat, then the units caveat, then return value. Every sentence adds a distinct fact; the worked example is short and reinforces defaults.

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?

No output schema exists, and the description compensates by pointing to document_list for the returned shape. Combined with the save and units guidance, an agent can call this correctly; only the fate of the previously active document is unaddressed.

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 the baseline is 3, but the description earns above baseline by clarifying that `units` affects only display while tool inputs stay in mm — a non-obvious behavior the schema text ('Distance display units of the design') does not convey. `design_type` is left entirely to the schema, which already explains parametric vs direct.

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 and resource ('Create a new design document') plus the side effect ('make it active'), which distinguishes it from document_open/document_activate. The agent knows exactly what it gets without reading the schema.

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?

Explicitly routes the agent: the document is NOT saved, and document_save should be called only when the user asks to save. This is a real when/when-not rule tied to a named sibling. It stops short of contrasting with document_open or document_activate, which remain inferable only from the name.

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

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

With no annotations, the description carries the behavioral burden well: it discloses the active-document side effect, the already-open activation behavior, the `already_open` flag, and the accepted input types. It does not cover permission/auth requirements or what happens to an unsaved current document, which keeps it below the top score.

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 description is front-loaded with the core action, then adds the key constraint, already-open behavior, return note, and examples. Every part earns its place and the examples are compact.

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 two-parameter tool with no annotations and no output schema, the description is nearly complete: it explains inputs, side effects, and return values. The main remaining gap is explicit comparison to sibling tools such as document_activate and document_new.

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. The description adds meaningful semantics beyond the schema by requiring exactly one of the two parameters and clarifying that `local_path` must be an existing local `.f3d` file.

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: "Open a document and make it active." It distinguishes cloud files from local .f3d files and explains the already-open case, which helps separate it from document_activate and document_list.

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 usage constraints: pass exactly one of `file_id` or `local_path`, and other formats such as STEP are not opened here. It does not explicitly name document_activate or document_new as alternatives, so it falls short of fully explicit routing guidance.

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

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

With no annotations provided, the description carries the full burden and does well: it discloses versioning, rejected parameters on an already-saved document, ENTITY_NOT_FOUND for missing folders, and background upload with "upload": "pending". It does not discuss permissions, undo/reversibility, or concurrent-save behavior, so it is not fully exhaustive.

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 description is dense and front-loaded, starting with the critical invocation rule. Every sentence contributes operational detail about saving, parameter behavior, error semantics, or return shape. The examples are compact and useful rather than redundant.

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 four-parameter mutation tool with no output schema and no annotations, the description covers the important behavioral surface: when to call, save/version semantics, parameter applicability, missing-folder behavior, background upload, and return shape. It could still be stronger with permissions or undo semantics, but it is substantially complete.

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 100%, so the baseline is 3. The description adds conditional meaning beyond the schema: name and folder_path are rejected for already-saved documents, a never-saved document needs name, and missing folders are never created. This meaningfully clarifies how the parameters behave in different save scenarios.

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 clear verb and resource: save the document. It adds meaningful scope about explicit user request and saved vs. never-saved documents. It does not explicitly contrast with sibling tools such as document_new or document_close, but the purpose is still unambiguous.

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 a strong usage rule: call ONLY when the user explicitly asked to save the document. It also distinguishes the saved-document path from the first-save path and explains what parameters apply in each case. It stops short of naming alternative sibling tools for creating or closing documents.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: main-thread execution, unit conversions, return shape, stdout/stderr truncation, and error handling with timeline rollback. These are exactly the operational details an agent needs before calling a powerful code-execution tool.

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 description is front-loaded with purpose and usage guidance, then organized into scope, units, return behavior, and an example. Despite its length, every section carries actionable information for safely invoking the tool.

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 complex code-execution tool with no annotations and no output schema, the description covers invocation context, execution semantics, return values, error behavior, and rollback behavior. It leaves no significant operational gap for an agent deciding whether and how to call it.

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 the baseline is 3, but the description adds real meaning beyond the schema by explaining how `params` is exposed to code and clarifying unit conventions for Fusion API values. It does not elaborate on `timeout_s` beyond the schema, which keeps it from 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 action and environment: running Python inside Fusion 360 on its main thread. It explicitly distinguishes itself from the many dedicated sibling tools by saying to use it only when no dedicated tool can do the job.

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 a clear when-to-use rule: only when no dedicated tool can handle the task. It also defines the available execution context (`adsk`, `app`, `ui`, `design`, `root`, `params`) so the agent knows what can be done before invoking it.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the destructive overwrite semantics ('the old file is deleted first, so a failed export loses it'), the precondition that the directory must exist, the extension/format coupling, and that exporting does not save the document. It even documents the return payload.

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 action and formats, followed by preconditions, then the overwrite caveat, then return shape and a concrete example. Every sentence earns its place 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?

No output schema exists, yet the description supplies the return structure ({files, format, scope}), covers all four parameters' preconditions, and gives a usage example — an agent has everything needed to call it 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 coverage is 100%, so the baseline is 3; the description adds meaning beyond it by explaining the format/extension fallback, the overwrite-before-write risk, and what scope resolves to in the return value. It does not restate everything, which is appropriate.

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 and resource ('Export the design, a component or an occurrence') and enumerates every supported format (STEP, IGES, SAT, SMT, F3D, USDZ). An agent can distinguish this from export_mesh or export_sketch_dxf without opening any schema.

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?

Explicitly routes away from document_save ('Exporting does not save the document (document_save does)') and the schema notes bodies are not allowed here, use export_mesh. It also states the path/extension preconditions. Missing an explicit statement of when not to export at all, so not a full 5.

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

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

With no annotations, the description carries the full burden and does so well: it discloses that an existing file is deleted first when overwrite=true, that the document is not saved afterward, that OBJ emits a sidecar <name>.mtl file, and that file_units is ignored for 3MF. It also documents the return payload and warnings, so the agent knows both side effects and results.

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 scope and formats, then constraints, then return shape, then a concrete example — a well-ordered structure with little wasted text. The parenthetical asides (OBJ sidecar, file_units warning) are dense but each carries real information.

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 12-parameter mutation tool with no annotations and no output schema, the description still covers preconditions, destructive overwrite semantics, the unsaved-document caveat, the return structure, and an example call. Nothing an agent needs to invoke it correctly is missing.

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; the description earns above that by adding a cross-field constraint the schema cannot express (deviation/aspect-ratio numbers are an error unless refinement='custom') and by noting the format/extension coupling. It does not add meaning for units vs file_units beyond what the schema titles/descriptions already say.