video_job_start

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

With no annotations, the description carries the full burden, and it does disclose the critical async behavior: this starts a background job and must be polled via video_job. It does not say what the start call returns (a job id?), how long jobs run, whether jobs are queued or concurrent, or what happens on failure — all material for an async mutation.

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?

Front-loads the problem it solves (client timeout) and then the routing advice in three tight lines. Dense but every clause carries operational meaning; no filler.

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 asynchronous job with no annotations and no output schema, the description omits the return shape needed to actually use video_job polling (job id/handle), and leaves five parameters undocumented. Strong on routing, thin on everything needed to invoke and follow up correctly.

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 0% across 7 parameters, so the description must compensate, and it only explains two: full=true (verbatim extraction) and comments=True (adds comment-section controversy analysis). url, lang, model, prompt, and scan_cuts get no explanation anywhere.

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+resource: start a background job for long videos to avoid client timeouts, then poll with video_job. That distinguishes it from the synchronous extraction siblings, though it never contrasts itself with video_full or video_watch, which look like the nearest overlapping tools.

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?

Explicitly prescribes an ordering (video_meta → video_plan → video_window / video_sheet) that defers this tool, and names the one condition that justifies it: only when a full verbatim transcript is actually wanted (full=true). It also names video_job as the required follow-up, so the agent knows the alternative and the condition.

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