add_state_machine

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

No annotations are present, so the description carries the full burden of behavioral disclosure. It states the operation (adds a state machine) and names the parameters, but it doesn't disclose prerequisites, side effects, whether an existing state machine with the same name is overwritten, or what happens inside the AnimGraph. This is a mutation tool with no safety annotations, so critical behavioral context is missing.

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 well-structured: a one-sentence purpose, a brief conceptual clarification, an Args list, a KB pointer, and an example. It is front-loaded and free of filler, though the conceptual sentence about state machines could be shortened without much loss. Overall it earns its place by aiding sibling differentiation.

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 tool is moderately complex and the description includes an example and a KB reference, which helps an agent find deeper guidance. However, it omits important operational context such as whether the Animation Blueprint must already exist, whether default states are created, or how the new state machine node connects to existing AnimGraph content. The presence of an output schema reduces the need to describe return values, but mutation behavior still needs more disclosure.

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 compensates with an Args section explaining both parameters: anim_blueprint_name is 'Animation Blueprint name' and state_machine_name is 'Name for the state machine node.' The example uses a full asset path, giving concrete format guidance. This adds real value beyond the bare schema titles and default.

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 a State Machine to an Animation Blueprint's AnimGraph." It explains that state machines define animation states and transitions, which conceptually distinguishes it from sibling tools like add_animation_state and add_state_transition. However, it never names those siblings explicitly, so differentiation is implicit rather than direct.

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 usage context is implied by the description: if you need to add a state machine container to an AnimGraph, this is the tool. It doesn't provide explicit when-to-use vs alternatives, nor does it mention exclusions like 'use add_animation_state for individual states.' The example shows a typical call but no routing guidance.

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