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

The annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=true. The description adds real context beyond them: it does not submit a model call or regenerate unchanged media, it applies outcomes, it returns exact job IDs and failures when a clip stalls or a captured provider result needs apply recovery, and it returns current requested clip-media resource IDs. It still does not explain the destructiveness the annotation advertises, which the word 'wait' in the tool name contradicts, or what state a recovery apply can change.

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 front-loads the core purpose, and the sentences are dense but mostly earn their place. The third sentence is a run-on that chains two separate failure modes (clip-video review stalls and captured-provider-result apply recovery) into one clause, which makes the recovery guidance harder to parse than it needs to be.

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 six-parameter, nested-object, destructive tool, the description covers the essential behaviors: what it waits for, that it does not trigger generation, how stalls surface, and how to consume the returned IDs. An output schema exists, so the return-value detail is supplementary rather than required. The lack of any parameter guidance is acceptable given the schema, though the missing warning about the destructive apply path is a real gap.

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 only 50%, and the description says nothing about the six parameters themselves: work_id, arguments, request_key, read_skills, expected_catalog_version, or publication_proposal_id. It also adds no syntax or sourcing guidance for those fields, so the parameter semantics are carried almost entirely by the schema.

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 a specific verb and resource: durably wait for this turn's accepted Film actions and generation to settle. That distinguishes it from generic waiting tools by scoping it to Film actions and generation in the current turn. However, it never names the close siblings it could be confused with (native.wait_for_work, native.wait_for_element_generation, native.wait_for_film_three_d_guides, native.get_run_status), so the agent must infer the boundary.

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 clear usage context: it waits for already-accepted work rather than starting a new model call, it says to escalate to the creator only for an unresolved decision, and it says to use the returned output IDs directly for review. It does not explicitly exclude alternatives or point to the named sibling tools, such as native.diagnose_film_studio_run or native.recover_film_studio_generation, that the returned job ID is meant for.

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