production.facial_refine

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

Beyond annotations (readOnly=false, destructive=false), the description adds real behavioral context: candidates are new Actions through NLA tracks, the body Action is never modified, and speech requires explicit timed phonemes or returns TIMING_INPUT_REQUIRED. These clarify what is created, what is preserved, and an error precondition – consistent with destructiveHint=false.

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 single dense paragraph carries useful content but front-loads with the opaque 'M7 facial unit' rather than the actual purpose, and several clauses are terse jargon. It's compact with little waste, but the ordering buries the most agent-relevant information (plan-first, non-destructive, speech timing) behind an unexplained code.

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?

With an output schema present, return values needn't be explained, and the behavioral side (plan-first, non-destructive candidates, timing precondition) is reasonably covered. But for a 7-parameter, 0%-coverage tool with many near-sibling facial tools, the missing parameter meanings and lack of sibling routing leave clear gaps.

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%, so the description carries full burden across 7 params, yet it only meaningfully explains two: the apply default (false/plan-first) and that facial is the immutable plan.json reference. The intent, brief, options, object_name, and operation_id parameters are left entirely undocumented 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 description conveys that this refines a facial setup by producing candidate Actions evaluated through NLA tracks, but 'M7 facial unit' is opaque internal jargon and the core verb+resource ('refine facial animation') is only inferable. It never distinguishes itself from siblings like facial_generate, facial_polish_curves, or animation_refine_generated, so an agent can't tell them apart from the description alone.

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 order, and 'Technical QA and artistic review stay separate' is a soft exclusion deferring to facial_review/QA tools. However, no alternative is named explicitly and there's no affirmative 'use this when...' routing versus the many facial_* siblings.

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