Upload Media from URL

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

Annotations are minimal (readOnlyHint=false, destructiveHint=false, etc.), so the description carries the burden. It clearly explains that processing is asynchronous, typical wait times (1-3 minutes for audio under 60 min), and the sequence of subsequent API calls (get_media_status, get_transcript, get_media_insights). It does not mention error handling or rate limits, but the provided context is substantial.

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 concise at ~4 sentences, front-loading the core action. Each sentence serves a purpose: defining the input, explaining async behavior, pointing to alternatives, and noting a limitation. No redundant or vague statements.

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?

Given the tool's complexity (9 parameters, async, multiple URL types) and the existence of an output schema (so return values don't need explanation), the description is complete. It covers the main workflow, siblings, and a known limitation. A minor improvement could be mentioning the required parameters explicitly, but the schema handles that.

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 100%, so baseline is 3. The description adds some context (e.g., that social links are resolved automatically, and that processing is async), but most parameter meanings are already clear in the schema. The description does not significantly enhance understanding beyond what the schema's property descriptions provide.

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 clearly states the tool's action: 'Upload media from a URL'. It specifies the types of URLs (direct file, pre-signed S3, shareable social links) and distinguishes itself from sibling tools like upload_and_analyze and upload_local_file by naming them explicitly. The verb 'upload' with resource 'media from URL' is specific and unambiguous.

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 description provides explicit guidance: use this tool for URL-based uploads, use upload_local_file for local files, and use upload_and_analyze for a combined upload+analyze workflow. It also mentions that Vimeo links are not supported, giving clear exclusion criteria. The async behavior and polling instructions further inform when to call this tool.

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