Reserve an upload slot for a local video file

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 so thoroughly: it reveals the returned upload_url and upload_id, requires raw-byte HTTP PUT, states expiry and size limits, and explains the tmpfiles.org fallback lifecycle including the 60-minute expiry and signed-link refresh.

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 is front-loaded with the primary use condition and workflow, then adds constraints and fallback instructions in a logical order. Every sentence carries operational value, including exact curl examples and timing details.

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, so the description must explain return values and next steps, and it does: upload_url, upload_id, expires_in, max_mb, and the required call to process_video. It also covers failure handling, making it complete for an agent to execute the workflow.

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?

The single optional filename parameter is fully documented in the schema as 'Original file name (optional, for the extension).' The description does not add parameter-specific meaning, but the schema coverage is 100%, so the baseline of 3 applies.

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 states a specific action and resource: reserve an upload slot for a local video file. It clearly distinguishes this from processing a video by explicitly contrasting file input with a link and by naming process_video as the follow-up step.

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 opens with 'Use when the user hands you a video FILE instead of a link,' giving a direct condition for use. It also provides a fallback path for when the sandbox cannot reach the upload URL, and a final fallback to ask the user, so an agent knows exactly how to route the task.

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