Create moving-head fixture control + 3D previz

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

The description goes far beyond the annotations by detailing the internal structure created: a Constant CHOP, dmxoutCHOP, Geometry COMP with a tube-cone beam, and a Render TOP. It explains the expression-driven rotation mapping (pan→ry, tilt→rx) and how DMX values map to degrees. These specifics align with readOnlyHint=false (write operation) and openWorldHint=true (creates multiple nodes) without any contradiction.

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 but well-structured: it is front-loaded with the main purpose, then details the per-fixture construction, then closes with a comparison to the sibling and a usage example. Every sentence adds operational detail, though it is a single long paragraph that could benefit from light segmentation for readability.

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 an 11-parameter tool with nested fixture objects, the description provides a comprehensive mental model of the resulting network, including the dmxoutCHOP and previz components. It gives a concrete usage example (op('rig_out')['fix1/pan']) that helps agents understand how to interact with the outputs. The main gap is not explicitly stating what the function returns (e.g., the path to the created rig), but given the openWorldHint and detailed creation steps, this is a minor omission.

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?

With 100% schema description coverage, the baseline is 3. The description adds value by showing how parameters connect to implementation, e.g., 'padded and merged into a dmxoutCHOP (interface, universe, netaddress, rate)' corresponds to net/universe/host/fps, and '0-255 mapped across pan_range/tilt_range degrees' directly references pan_range and tilt_range. It also references the 'id' field via '<id>/…', adding relational context beyond individual parameter 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?

The description opens with 'Build a moving-head lighting rig with BOTH a DMX/Art-Net output chain AND a 3D visual previsualization,' clearly stating the verb and resource. It also explicitly differentiates from the sibling create_dmx_fixture_pipeline by noting it adds 'the live 3D preview on top of what create_dmx_fixture_pipeline (DMX-out only) does,' making the tool's unique role unmistakable.

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 explicitly references create_dmx_fixture_pipeline as the DMX-only alternative, telling users when to choose this tool (when 3D previz is needed). It also provides post-creation guidance: 'Bind individual channels later with bind_to_channel / animate_parameter on op('rig_out')['fix1/pan']', showing how to use the created rig. This combines an explicit alternative with concrete usage context.

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