production.animation_analyze_pose_silhouette

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

Annotations already declare non-readonly, non-destructive, non-idempotent, closed-world. The description adds real context beyond that: a dry-run default, an "explicit mapping and compatible body rig" prerequisite, retained source Actions, and concrete errors from unsupported adapters. However, the phrasing is opaque ("immutable plan.json reference", "M6 unit") so the value is present but hard to act on.

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?

Four dense, jargon-laden sentences that do not front-load the actual capability; the reader gets "high-level M6 unit" before learning anything about pose silhouette analysis. Tightening is not the issue — the content is compressed yet under-informative.

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 not be explained, and the description does cover the dry-run default and rig/mapping prerequisite. Still, key invocation unknowns remain: what brief/intent/object_name accept, and what distinguishes this analysis from the many other animation analyzers.

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% across 7 optional parameters, so the description must carry the full burden. It clarifies apply (default false), generation (a plan reference), and options (stage parameters/thresholds/visual review), but leaves brief, intent, object_name, and operation_id entirely unexplained.

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 never states what the tool actually analyzes: no verb+resource framing beyond the name, only cryptic taxonomy ("high-level M6 unit") and workflow jargon. "Silhouette" and "pose" appear only in the name, so the description largely restates the title rather than defining the operation. It also fails to distinguish itself from close siblings like animation_analyze_pose or animation_validate_pose.

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" implies a preview-then-apply workflow, which is genuine usage guidance, but no alternative tools are named and no when-not-to-use condition is given. With dozens of sibling animation analyzers (pose, arcs, timing, balance, motion quality), the absence of routing guidance is a real gap.

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