motion_control

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

With no annotations present, the description carries the full behavioral burden and does so well: it discloses the default model, that output length is tied to the reference video (up to 10 s with orientation "image"), that only https links are accepted, that server-returned links work, and a non-obvious timeout/retry hazard that would otherwise cause double billing. That retry warning is exactly the kind of trait structured fields cannot express.

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 purpose sentence is front-loaded, followed by default model, output length, return value, and the retry caveat in roughly priority order. Every sentence carries information an agent needs; nothing is padding.

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 an 8-parameter generation tool with no annotations and no output schema, the definition covers inputs, defaults, output (job_id for get_video), duration, link requirements and failure behavior. Remaining gaps are modest – no cost framing outside the schema's estimate_only, and no permission or async-polling detail – but nothing essential to a correct call is missing.

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 and the schema already documents every parameter including defaults and enums. The description adds practical meaning beyond the schema by explaining the https constraint on both URLs and that links produced by this server are acceptable, plus the duration consequence of the orientation choice.

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?

States a specific verb and resource – animate the character in an image using the motion from a reference video – and implicitly separates itself from siblings like start_video, extend_video and edit_video by naming both inputs (image_url + video_url). The agent can identify exactly what the tool produces without opening the schema.

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 concrete operational guidance: it names get_video as the follow-up for the returned job_id, and explicitly says not to retry on timeout because a job may already be running and a retry pays twice. It does not explicitly contrast itself with start_video or other video siblings, so the when-to-use-vs-alternative story is clear from context rather than stated.

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