assembly_add_occurrence

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.