production.animation_generate_blocking

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

Beyond the annotations (destructiveHint=false, readOnly=false), the description adds meaningful behavior: apply defaults to false (dry-run/plan mode), the generation reference is an immutable plan.json, source Actions are retained, and unsupported adapters return concrete errors. These are genuinely useful operational facts not captured by the annotations. It stops short of describing what a real apply mutates or its reversibility.

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?

It front-loads a restatement of the tool name and a cryptic 'M6 unit' phrase before the actionable content. The remaining sentences are dense but each carries some information; the issue is opacity and ordering rather than padding.

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?

An output schema exists so return values need no explanation, and the description covers the key workflow (plan first, dry-run default), prerequisites, and error behavior. But four of seven parameters are unexplained and the 'M6' framing is undefined, leaving gaps for a mutation-capable tool with no required params.

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 coverage is 0% across 7 params, so the description carries the burden. It does explain apply (default false), generation (immutable plan.json reference), and options (declared stage parameters/thresholds/visual review), but leaves brief, intent, object_name, and operation_id entirely undocumented. Partial compensation for a zero-coverage schema.

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 name implies 'generate blocking animation' and the description hints at a plan-then-generate workflow, but the opening 'high-level M6 unit' is internal jargon that does nothing to explain purpose. It never plainly states what blocking output is produced or how it differs from animation_generate, animation_generation_plan, or animation_validate_blocking. A reader can infer a generation tool but not its distinct scope.

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?

'Plan first, apply=false by default' and 'Explicit mapping and compatible body rig required' give real prerequisites and a workflow ordering. However, no sibling tool is named as the plan step or the validation follow-up ('technical QA and temporal artistic review are distinct' implies tools exist but does not name them). Usage is implied rather than explicitly routed.

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