set_rig_control_value

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

Annotations already declare destructive=true and idempotent=true, but the description adds genuinely non-obvious behavior: values are clamped against enabled limits via SetControlValue, and the result is verified by read-back. It stops short of explaining what 'destructive' means here (e.g., overwrites prior Initial/Current pose values), which is the one trait an agent would want flagged.

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 constraints, then the return shape; each sentence carries weight and the inline Returns block is compact. The opening sentence is dense, packing scope, both pose targets, and type-correctness into one line, which slightly taxes 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?

With no output schema, the description supplies a full return-shape block (asset_path, control_name, control_type, value, saved, save_error). Combined with the clamping, limit-ordering, and PIE caveats carried in the schema, an agent has everything needed to call this mutation 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 schema already documents all four parameters, including the per-type value mapping and the detailed PIE/force behavior. The description only restates the type-correctness framing for 'value' and adds no syntax or format detail beyond the schema, so the baseline of 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 ('Set a Control Rig control's pose value (Initial + Current)') and pins down the write semantics (type-correct per ERigControlType). It explicitly distinguishes itself from the look-alike sibling by noting 'add_rig_control only seeds the identity value', so an agent can pick correctly without opening schemas.

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?

Routes the agent to two alternatives with explicit conditions: use add_rig_control only for seeding the identity value, and 'set limits first with set_rig_control_limits' before relying on min/max clamping. This is exactly the when/when-not/alternative guidance needed in a rig with several set_rig_control_* siblings.

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