production.facial_validate_expression

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

Beyond annotations (idempotent, non-destructive, not read-only), it discloses that the body Action is never modified, that 'facial' is an immutable plan.json reference, that candidates are staged as new Actions, and that speech without explicit timed phonemes fails with TIMING_INPUT_REQUIRED. That is meaningful behavioral context including a failure mode. It does not explain what apply=true changes on disk, so it stops short of a 5.

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?

Dense and front-loaded with a redundant name restatement, then packed with semicolon-separated clauses heavy on internal jargon ('M7 facial unit', 'NLA tracks'). Every clause carries some information, but the structure makes the core action hard to extract quickly.

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 6-parameter mutation-capable tool with zero schema descriptions, the description leaves most parameter semantics unexplained and never states what 'validation' operates on or requires. An output schema exists, so return values needn't be covered, but the input side is far too thin for this complexity.

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 6 optional parameters, so the description must carry the load. It adds meaning only for 'apply' (default false, plan-first) and 'facial' (immutable plan.json reference); 'brief', 'intent', 'options', and 'object_name' are left entirely undocumented in both places.

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 opens by restating the name ('facial_validate_expression: M7 facial unit') and then describes mechanism ('Evidence-based semantic mapping', 'Candidates are new Actions evaluated through NLA tracks') rather than plainly stating that it validates a facial expression candidate against brief/intent. An agent can infer it is a validation step, but the verb+resource statement is buried in jargon and does not distinguish it from siblings like facial_review or facial_validate_lipsync.

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 real workflow guidance for the dry-run-then-apply pattern, and 'Technical QA and artistic review stay separate' hints this is the technical QA pass. However, no sibling alternative is named and no explicit when-not-to-use condition is given, so routing relies on inference.

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