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

Goes far beyond the annotations: it discloses chunk-level billing (1 credit/min, only missing 30s chunks charged), that a finished transcript/translation is reused so caption_video usually only pays the 4 credits/min burn, that the failed job stays fully refunded, and that calls are idempotent with no second charge (confirming idempotentHint). It also names the error codes and whether they are charged, which an agent cannot infer from structured fields.

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 and resumable-job list are front-loaded, and the pricing/idempotency/error details follow in a logical sequence. The no_speech parenthetical is quite dense and slightly over-elaborate, but nearly every sentence carries actionable information.

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?

Covers the return value indirectly ('Returns a new job id; poll get_job'), error codes, billing implications, and idempotency despite no output schema. The remaining gap is the unexplained webhookUrl/notifyEmail parameters, which is minor given the overall richness.

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 coverage is 50%: jobId and maxCredits are documented in the schema, while webhookUrl and notifyEmail are undocumented in both places. The description adds an example call and enough billing context to make maxCredits meaningful, but it never explains the webhook/email parameters, so it only partially compensates for the coverage gap.

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 ('Restart') and resource ('a failed job'), enumerates exactly which job types are resumable (caption_video, transcribe, create_clips, dub_video, trim/remove_silences, generate_metadata), and clearly differs from siblings like get_job or caption_video. An agent can immediately tell this is the recovery path, not the creation path.

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 (a failed job) plus concrete routing for edge cases: 422 resume_not_supported/resume_media_expired means call the original tool again, and 409 job_not_resumable with reason no_speech explains that a resume would reproduce the same failure. These are genuine alternatives, not vague hints.

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