production.animation_analyze_motion_quality

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

The annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, which is the surprising part here (an 'analyze' tool that is not read-only), and the description does not explain why — no mention of an artifact, cache, or report being written. What it does add is a genuine scoping disclosure ('No artistic quality score') and the schema-versioning behavior of the response, both of which are useful and not in the structured fields.

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?

One dense sentence plus a short negative clause — no filler, and the metric list is front-loaded. The density of schema identifiers (production.motion_quality.rig.v1 / limb_chains.v1) makes it slower to parse than it needs to be, but nothing is wasted.

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, but the input side is unaddressed: a free-form `options` object with zero documented coverage governs which of the two analysis shapes is produced. Combined with an unexplained readOnlyHint=false on an analysis tool, an agent cannot complete the picture from this definition.

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%, so the description must compensate and largely does not: `object_name` is never explained, and `options` is a free-form object with `additionalProperties: true` that is a black box in both schema and description. The description hints that whole-rig vs limb-chain mode and a schema identifier exist, but never says that these are selected via `options`, leaving the only meaningful parameter undiscoverable from the text.

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 names the specific metrics produced (velocity/acceleration/angular/contact indicators) and the two analysis shapes (whole-rig vs explicit limb chains), which distinguishes it from metric siblings like animation_analyze_spacing, animation_analyze_timing, or animation_analyze_arcs. It does not explicitly route against those siblings, but the measurement vocabulary is concrete enough that an agent knows what it gets.

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?

Usage is only implied: it states there are two modes and that the 'schema' field in the result says which was used, so an agent can infer mode selection follows the input. There is no when-to-use statement, no when-not, and no named alternative among the many analyze_* siblings (arcs, spacing, timing, balance, foot_phase) that an agent must choose between.

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