add_activate_variant_node

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

With no annotations, the description carries the full burden, but it only says the node is added and what it is used for; it does not state side effects, prerequisites (e.g., existing Blueprint, lvs_variable must exist), whether the graph is compiled or saved, or failure behavior. The mutation is implied by 'Add' but not characterized in terms of its effects on the Blueprint graph.

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 purpose is front-loaded, the Args list is terse, and the example is concrete. The Ch. 20 context and KB line are slightly redundant, but they add helpful framing rather than bloat.

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 a five-parameter mutation tool with no annotations and no parameter descriptions in the schema, the description covers every parameter, offers a KB pointer, and gives a minimal working example; the output schema is available for return-value details. It is complete enough to call correctly, though it would benefit from noting prerequisites and side-effect behavior.

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?

The Args section explicitly defines all five parameters, providing meaning the input schema's bare titles lack: lvs_variable is 'Variable holding the Level Variant Sets reference,' variant_set_name and variant_name are the set and variant to switch, and node_position is '[X, Y] graph position.' This fully compensates for the 0% schema description coverage.

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 a specific verb and resource: 'Add an ActivateVariant node to switch variants via Blueprint,' and reinforces it with the BP_Configurator context. It does not explicitly contrast itself with the similarly named sibling add_activate_variant_set_node, so it stops short of a 5.

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 Ch. 20 note and example imply this is for product-configurator Blueprints that switch variants on button presses, and the example shows a concrete call. However, there is no explicit when-to-use/when-not-to-use guidance or named alternative, leaving the agent to infer the appropriate context from the example.

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