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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. The description adds the important behavioral trait that the call blocks/waits up to wait_seconds, but it does not say what happens on timeout, whether partial status is returned, or any rate-limit behavior, so it adds moderate value beyond 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?

Two tight sentences with zero waste: the purpose and resource are front-loaded, and the wait behavior follows immediately. Nothing extraneous is included.

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?

There is no output schema, yet the description never explains what the returned status looks like, how to interpret job states, or what happens when the wait times out. For a long-running-job polling tool this leaves too much unspecified for an agent to use it confidently.

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 25% (audio_file_id alone has a schema description), so the description must compensate. It clarifies task_id's role and that wait_seconds is a maximum wait, but only implicitly conveys the kind enum and never mentions audio_file_id's role, leaving meaningful gaps for the required kind parameter.

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 action (get status) and resource (a job identified by task_id) and enumerates the job kinds (transcribe / enhance / music / export / first_pass_apply), so the agent knows exactly what it returns. It is clear but does not explicitly differentiate from siblings such as cast_get_transcript, so it falls just short of a 5.

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 mention of waiting up to wait_seconds implies this is used to poll or block on a previously started job, which is useful implied usage. However, it gives no explicit when-to-use/when-not or alternative tools (e.g., versus cast_get_transcript for finished transcripts), leaving the agent to infer context.

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