generate_motion_from_video

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

Annotations are sparse (safety hints only), so the description carries the disclosure burden and earns it: credit consumption, the submit-once-then-poll async pattern, the 1–4 person capacity, and the requirement to preserve actor exports and MHR assets across calls are all non-obvious behaviors that a caller would otherwise discover by trial and error. No contradiction with the annotations; 'submit once' aligns with idempotentHint=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?

Purpose is front-loaded in the first sentence, followed by prerequisites, cost/workflow, and downstream usage — every sentence earns its place and no filler exists. The final sentence packs three ideas (preservation, retargeting routing, moveInPlace) into one dense block, so it is efficient but slightly bundle-heavy.

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 complex tool (7 top-level params, nested exportSettings with 13 sub-properties, no output schema, minimal annotations), the description supplies what matters most: purpose, prerequisites, async polling workflow, capacity limits, and sibling routing. Its main gaps are not describing what the submit response returns (e.g., the batch ID needed to poll get_batch) and never linking mediaIDs to the create_media_upload sibling.

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 only 14%, so the description must compensate and partially does: it grounds mediaIDs (uploaded IDs), numPeople (1–4), facialCapture (optional), and gives moveInPlace a purpose ('preserve interactions and shared world placement'). However, loop and batchName receive no semantic grounding, and the exportSettings object is only described as needing to be 'complete' without touching its many sub-fields.

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?

Opens with a specific verb and resource: 'Capture editable body, hand and optional face performance from uploaded videos using Comic 4.' It names the input (uploaded videos), the pipeline (Comic 4), the output (editable performance), and the capacity constraint (1–4 people). The 'from uploaded videos' qualifier clearly separates it from the sibling generate_motion, which handles the non-video path.

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?

Gives explicit prerequisites ('Requires uploaded media IDs and complete export settings'), a concrete workflow ('submit once, then poll get_batch and list_batch_motions'), and routes the agent to get_motion with the exact keys (characterID and bodyIndex) for per-actor retargeting. It also warns to keep moveInPlace false to preserve interactions and shared world placement — actionable guidance an agent can execute without further inference.

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