set_usd_variant_selection

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

Annotations already declare the safety profile (readOnly=false, idempotent=true, destructive=true), so the description's job is to add context — and it does, explaining the HasVariantSet guard prevents the underlying FUsdVariantSet from going invalid when the set is missing, which is genuine error-handling behavior not derivable from annotations. It stops short of explaining what the destructive flag actually replaces (the prior variant selection).

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?

Two sentences: the mutation is front-loaded and the guard behavior is appended, followed by a compact Returns block. The single internal identifier 'FUsdVariantSet' is jargon but carries real meaning, so 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?

There is no output schema, so documenting the returned object (prim_path, variant_set_name, variant_name, set) is valuable and appropriately included. However, for a tool that mutates a stage, the description omits the missing-set failure/return behavior in detail and gives no indication of which stage is targeted when the optional stage_name is omitted.

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 all four parameters are already documented, including the important 'must already be present' note on variant_name. The description only echoes the parameter names in its return block and adds no format, scoping, or stage_name guidance of its own; 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?

The description states a specific verb+resource ('Set the active variant for a variant set'), so the action is unambiguous. It does not distinguish itself from the closely related sibling clear_usd_variant_selection or reference add_usd_variant, so sibling differentiation falls to the schema text rather than the description.

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: the note that the HasVariantSet guard handles a missing set hints that the set may not exist, but the description never states when to call this versus clear_usd_variant_selection or add_usd_variant. The key precondition ('must already be present — use add_usd_variant first') lives in the schema, not the description.

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