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

Annotations already declare idempotentHint=true and readOnlyHint=false, but the description adds real cost behavior beyond them: the run is billed 'at the price agreed for the run' and 'never a second charge'. It also discloses server-side orchestration ('Tevyon starts it by itself as soon as the still ... has succeeded') and the fallback path if the server hasn't started it. The idempotency sentence partly restates the annotation, which keeps it from a 5.

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?

Dense and front-loaded: the version gate comes first, then the auto-start warning, then the manual fallback. The pairing 'you do not need to call this. Call it to get that video job' reads as slightly self-cancelling but is deliberate and resolves quickly. Little wasted wording overall.

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 7-parameter, money-spending mutation with no output schema, the description covers the decision context and billing safety well but never says what comes back (a job id? a job object?) or how wait_seconds and max_credits affect the call. It also leaves half the parameters unexplained. Adequate to decide whether to call, thin on how to call it well.

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 29%, so the description must compensate, and it largely does not: aspect, duration, max_credits, style_id and frame_job_id are undocumented in both places. Its one contribution is provenance ('pass the values from that call's next'), which tells the agent where values come from but not what each parameter means or how max_credits interacts with the agreed price.

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 identifies this as 'second step' of an old-style UGC run and speaks of 'that video job', and the title says 'make the still talk', so the resource is inferable but never stated as a plain verb+resource sentence. The opening sentences are spent on eligibility ('Only for UGC runs started before 29.10.2026') rather than on what the tool produces. An agent can distinguish it from run_marketing_style, but only after parsing the versioning caveat.

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 when-to-use ('Only for UGC runs started before 29.10.2026, which made a still first'), when-not-to-use ('new UGC runs are one job and need no second step'), and an explicit discouragement ('Tevyon starts it by itself ... you do not need to call this'). It even names the sibling that produces the input values and specifies passing the values from that call's 'next'.

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