add_variant_to_level_variant_sets

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

With no annotations, the description carries the burden of exposing behavior. It clearly signals an additive mutation and explains the concept of property captures as snapshots applied on activation, which is useful. However, it does not disclose side effects such as persistence/asset modification, duplicate-variant behavior, or failure conditions when the LVS or variant set does not exist.

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 front-loaded with purpose, followed by a concise concept note, structured argument documentation, a KB pointer, and an example. It is well organized and not bloated, though the example is a bit superficial because all placeholders use the same 'ExampleName' string.

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?

The description covers the core operation, all parameters, the semantic model of variants, and a KB reference. Since an output schema exists, omitting return-value details is acceptable. The main gap is the lack of explicit preconditions and edge-case behavior, but overall an agent has enough to call the tool correctly in the common case.

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 0%, but the description fully compensates by documenting every parameter: lvs_name, variant_set_name, variant_name, and captured_properties. It even provides the item structure for captured_properties and the allowed property_type values ('Material', 'Visibility', 'Transform', 'Mesh'), which is exactly what the schema lacks.

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 opening sentence states a specific verb and resource: 'Add a Variant to an existing Variant Set in a Level Variant Sets asset.' This cleanly differentiates the tool from siblings like create_level_variant_sets or add_activate_variant_set_node, since it targets an existing set and creates a new Variant within it.

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 makes the use case clear through phrases like 'existing Variant Set' and explains when variant property captures are applied. It does not explicitly name alternatives or say when-not-to-use this tool, but the context is strong enough that an agent can infer the intended scenario.

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