production.facial_render_preview

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

Annotations declare non-readOnly, non-destructive, non-idempotent, closed-world, so the safety profile is already given. The description adds real value beyond that: 'the body Action is never modified' and 'Candidates are new Actions evaluated through NLA tracks' explain exactly what mutation happens and what is left untouched, which the annotations alone cannot convey.

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 workflow constraint is front-loaded and several sentences carry weight (immutability, speech timing requirement). But the prose is telegraphic and jargon-dense ('Evidence-based semantic mapping (never names only)', 'M7 facial unit'), forcing the reader to parse rather than absorb.

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 described, and the description does supply workflow and immutability context. But with seven undocumented parameters and no plain statement of the render operation itself, an agent still lacks enough to invoke it confidently.

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 seven parameters, so the description carries the burden. It only clarifies two: apply defaulting to false and 'facial is the immutable plan.json reference'. brief, intent, options, object_name and operation_id are left completely unexplained in both schema and description.

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 text opens with 'facial_render_preview: M7 facial unit' and then talks about plan/apply, candidates and NLA tracks, but never states in plain terms that this renders a facial animation preview. 'M7 facial unit' is internal shorthand an agent cannot decode, and nothing separates it from siblings like facial_render_closeup or qa_render_preview.

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' gives a clear workflow ordering, and 'Speech needs explicit timed phonemes/visemes (TIMING_INPUT_REQUIRED otherwise)' is a concrete precondition. However, no alternative tool is named and there is no explicit when-not guidance for choosing this over facial_render_closeup or the body integration tools.

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