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

Annotations only say non-readonly, non-idempotent, open-world, non-destructive; the description adds substantial behavior beyond that: it is asynchronous, returns a Job ID at once or within a minute, must be polled with wait_for_jobs until done, surfaces per-step findings and finally the result plus credits consumed, and must not be re-started or duplicated manually mid-run.

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 single dense paragraph front-loads the core action and polling loop, and the bulleted routine entry with When/Never labels is easy to scan. There is mild redundancy between the opening sentence and the edit_prep bullet ("a whole new edit made from the person's uploads" appears twice), which costs it a point.

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?

No output schema exists, and the description compensates by explaining what comes back (a Job ID, then polled step results and final credits). For a long-running async tool with six required parameters, the caller has everything needed: when to start, what to feed it, how to poll, and what not to do concurrently.

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 brief, seconds, assetIds, projectId and resumeJobId are already fully documented in the schema. The description adds workflow context around the returned Job ID but no extra meaning about individual parameter values, so the baseline of 3 applies.

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+resource ("Start a routine") and immediately defines what a routine is: a long server-side process that hands back its result. It enumerates the single available routine (edit_prep) and describes what that routine produces (reads uploads, plans beats, cuts, writes main.film), which distinguishes it from siblings like edit_video or patch_film.

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?

Explicit routing: "for a whole new edit made from the person's uploads, start edit_prep first, before you read any footage", plus a When/"Never" pair that excludes trims, swaps, titles, music, graphics or any layer on an already-built film, and excludes requests with no uploads. Also states the follow-up loop (call wait_for_jobs repeatedly) and the prohibition on restarting while it runs.

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