Create a motion-control clip

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

The description goes well beyond annotations by disclosing that the operation costs 3 credits per driver second capped at 30 seconds, that the driver is uploaded first, that generation runs in the background, and that the agent should poll every 5–10 seconds until status is 'completed' or 'failed'. It also specifies the next step. This is rich behavioral context with no contradiction against the annotations.

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 dense but every sentence earns its place: action summary, cost, driver constraints, the exactly-one rule, return values, and the polling/download follow-up. It is front-loaded with the purpose and contains no repetition of schema content.

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?

Given the absence of an output schema and the complexity of a background generation task, the description fully covers what is returned (clip id and status), how to poll with the correct parameters, and what action to take on completion or failure. It also addresses prerequisites such as credit confirmation and file limits, so an agent can invoke and monitor the tool correctly without prior knowledge.

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 100%, so the baseline is 3. The description adds meaning beyond the schema by clarifying the mutual exclusivity of image/photo, the upload-first requirement, and the credit cost basis. These details help an agent reason about parameter combinations, pushing it above baseline.

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 with a specific verb and resource: 'Animate a character look (or your own photo) by copying the motion of a driver video.' It clearly identifies the operation as motion transfer, and the reference to `clipugc videos motion` ties it to a known command, distinguishing it from the sibling create_clip. This is not a tautology and leaves no ambiguity about what the tool accomplishes.

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?

The description provides strong contextual guidance: driver format/size/duration limits, the requirement to upload first, the 'exactly one of image or photo' rule, the need to confirm credits via get_credits, and a detailed post-call polling workflow with get_video and download_video. It does not explicitly state when not to use this tool versus alternatives like create_clip, so it misses the top tier.

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