set_camera_rig_root_node

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

Annotations declare destructiveHint=true and idempotentHint=true, but the description goes well beyond them: it discloses that the prior root and all descendants and parameter values are dropped, that the operation runs in an undo transaction with a save, and precise failure semantics (saved=false plus save_error, change left in memory). This is exactly the kind of consequence detail a mutation caller 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?

Long but dense and front-loaded: the destructive replace action comes first, then save/failure behavior, then the alternative-tool routing and valid-value source, then the return shape. Every clause carries information an agent must have; none 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?

There is no output schema, yet the description spells out the response fields (camera_rig_path, node_type, node_class, root_set, saved, save_error) and the failure path. Combined with the destructive-behavior and dependency disclosure, an agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and already gives node_type examples, so the baseline is 3. The description adds genuine value on top by specifying where valid names come from (list_camera_node_types) and the add_camera_node_child relationship for ArrayCameraNode roots, which clarifies how the node_type choice drives downstream calls.

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 ('Replace the RootNode of a Gameplay Cameras UCameraRigAsset') and immediately scopes it further by naming what is destroyed ('the previous root and everything under it'). It distinguishes itself from siblings like build_camera_rig and set_camera_node_parameters without the agent needing to open 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?

Explicit routing to alternatives: valid node_type names come from list_camera_node_types, configure with set_camera_node_parameters, add children with add_camera_node_child for ArrayCameraNode, and read back with get_camera_rig_nodes. It also carves out when NOT to use it ('Does not build the rig (build_camera_rig does)'). Nothing is left to inference.

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