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

Annotations only declare readOnlyHint=false and destructiveHint=false; the description adds far more: the endpoint shape (upload_url + "/video-url"), the required PUT of raw bytes, the follow-up POST with video_r2_key and Accept: application/json, and the handoff fields upload_id / uploadUrl. It also enumerates hard limits (512MB, one MP4/MOV, 20 min on X, 125 with Premium, 4 attachments total, BlueSky 100MB cap) and per-platform behavior (LinkedIn skips video, TikTok accepts one video or JPEG/WebP). Only the origin of upload_url and any auth expectations are left unstated.

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 is front-loaded, which is good, but the body is a dense block where three client branches, a limits list, and per-platform rules run together without structure. Some lines are redundant repetitions of the same prohibition ("Do not describe it or reject it", "Do not try", "Do not put the file in a SupaBird argument"), and the step-by-step upload sequence is compressed into one run-on sentence.

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 zero-parameter tool with no output schema, it covers an unusual amount: platform routing, size/format/duration caps, and the downstream calls that use upload_id. The gap is the tool's own I/O contract — upload_url and upload_id appear from nowhere in the call signature, and it never states plainly what invoking this tool returns, which matters precisely because there is no output schema to fall back on.

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?

With zero declared parameters, the baseline is 4, and the description at least describes the payload the upstream call expects ({filename, mimeType, size, duration}) and the form field video_r2_key. Those fields are not tool parameters, however, so this is not meaning added to the schema so much as a parallel HTTP contract, and it never explains how the attached file reaches a zero-parameter tool.

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 first sentence names the trigger and the resource: "Call this when a video is attached or the user wants video on a post. That file is the post media." That is a specific verb-plus-resource framing that an agent can act on, and the later references to get_image_upload / schedule_post clarify where this sits in the pipeline. It loses a notch because the purpose is only stated once at the top and the rest of the text is per-client operational procedure, so the core contract is easy to lose.

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 partitions when to call by client: Grok gets a full upload sequence; Claude is told to show upload_url and stop, with "Do not try"; ChatGPT is told "do not call this while a file is attached" and to call it "only when schedule_post returns needs_upload_link." Both when-to-use and when-not-to-use are stated, along with the alternative path (passing chat_files on schedule_post).

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