production.facial_mocap_map

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description discloses meaningful behavior: candidates are new Actions evaluated through NLA tracks and the body Action is never modified, and 'facial' is an immutable plan.json reference. Those are non-obvious safety/scope facts an agent needs. The trailing 'Technical QA and artistic review stay separate' is too vague to add much.

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 short and front-loads the planning/default rule, but it opens by restating the tool name and includes cryptic fragments like 'M7 facial unit' and 'Technical QA and artistic review stay separate' that don't earn their place. Dense parenthetical jargon makes it slower to parse than its length suggests.

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 six parameters at 0% schema coverage and only some of them touched in prose, an agent cannot know what to put in brief, intent, options, or object_name. An output schema exists so return values need not be described, but the input-side gaps are substantial for a planning/apply tool.

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 carry parameter meaning, and it only covers two of six: apply (default false) and facial (immutable plan.json reference). brief, intent, options, and object_name are entirely unexplained in both schema and description, leaving half the surface undocumented.

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 resource (facial mocap semantic mapping) and implies a verb, but the framing 'Evidence-based semantic mapping (never names only)' and 'M7 facial unit' are internal jargon that don't clearly state the operation. It never distinguishes itself from close siblings like facial_mocap_analyze, facial_mocap_cleanup, facial_mocap_retarget, or facial_map_visemes, so an agent cannot confidently pick it over them.

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 one real operational rule — 'plan first, apply=false by default' — and a precondition ('Speech needs explicit timed phonemes/visemes, TIMING_INPUT_REQUIRED otherwise'). But there is no statement of when this tool applies versus the adjacent mocap_analyze/cleanup/retarget tools, leaving the routing decision implicit.

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