modify_anim_state_graph

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

Beyond the annotations, the description discloses important behaviors: the operation runs as one undoable transaction, add operations can omit ids, state deletion cascades to attached transitions, and parameter deletion is rejected while conditions reference it. These are meaningful edge-case behaviors that an agent could not infer from the schema alone and that materially affect invocation.

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 packed with useful information and no filler. Each sentence earns its place: transactionality, id allocation and return behavior, cascading deletion, and a specific layer default workflow. The core purpose is front-loaded before edge cases.

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?

Given the tool's complexity and the absence of an output schema, the description covers the key return value (generated ids plus resulting graph) and several critical constraints. It does not enumerate all operation kinds or describe validation failure behavior, but those are largely captured in the detailed input schema and the high-level contract is sufficiently complete for correct invocation.

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 schema documents the operation kinds and their fields in detail, while the description adds semantic value by explaining that add operations may omit id to have one allocated and that generated ids plus the resulting graph are returned. It also clarifies the defaultStateId workflow. With only 50% schema description coverage, the description partially compensates for the gaps, though it does not fully explain every operation contract.

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 clearly states the tool's purpose: apply a validated batch of structural operations to an anim state graph as one undoable transaction. It specifies a concrete verb, resource, and scope, and goes beyond a simple restatement by mentioning returned generated ids and the resulting graph. This is easily distinguishable from read-only siblings like get_anim_state_graph.

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 gives concrete guidance on when to use this tool: for validated batch mutations that should be undoable. It also provides a specific procedural tip about using layer.update defaultStateId before removing an old default state. It does not explicitly say when not to use it or name alternatives, but the usage context is still sufficiently clear.

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