production.facial_generate_blink

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

The description adds real behavioral context beyond annotations: candidates are new Actions evaluated through NLA tracks, the body Action is never modified, facial is an immutable plan.json reference, and apply defaults to false. It does not fully explain what happens when apply=true or how operation_id/options affect execution, but the key non-destructive workflow is clearly disclosed.

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 description is compact but dense, using jargon like 'M7 facial unit' and semicolon-separated clauses that reduce readability. The speech-timing sentence may be relevant to facial work generally but is not clearly tied to blink generation, making parts feel less targeted.

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?

For a 7-parameter mutation tool with an output schema and annotations, the description covers the workflow and non-destructive candidate model well. It is incomplete on parameter semantics and does not help the agent choose between this generator and related facial planning/generation tools.

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 parameters, so the description must compensate. It only clarifies apply's default and the meaning of facial as an immutable plan.json reference, leaving brief, intent, options, object_name, and operation_id 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 relies heavily on the tool name and the vague label 'M7 facial unit' rather than explicitly stating that it generates blink animation/candidate Actions. The later sentence about candidates being new Actions gives some outcome context, but there is no clear sibling differentiation from tools like facial_plan_blinks or facial_generate_lid_follow.

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?

It gives workflow guidance such as 'plan first, apply=false by default' and separates technical QA from artistic review, which implies usage context. However, it never explicitly says when to use this tool instead of facial_plan_blinks, facial_generate, or other facial generation siblings.

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