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

Annotations already flag destructiveHint=true and idempotentHint=true, but the description adds substantive context beyond them: it names exactly what gets destroyed (mismatched declared type, non-H.264 video, SVG with active content), that failures surface a reason in the error, and that `replaced` indicates whether a replacement took effect. That is real behavioral disclosure, though it does not address permissions or the admin scope implied by the [Admin] tag.

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?

Two tight sentences front-load the purpose and validation behavior, followed by the return-field note and a single reference pointer. Nothing is padded, though the get_tool_reference pointer occupies space that adds little to a covered schema.

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?

With an output schema present the description need not explain return values, and it still highlights the meaningful one (`replaced`) plus error behavior. Combined with full schema coverage, an agent has enough to call this correctly; only permission/auth requirements for a destructive admin tool are left implicit.

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 the schema already explains media_id, dimensions, poster_url, duration_seconds, and the analytics fields. The description adds no meaning to individual parameters and instead defers with 'Every argument in full, with examples: get_tool_reference', leaving the baseline of 3 appropriate.

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 concrete verb and resource ('checks the stored file and makes it usable') and anchors itself as the final stage of start_media_upload, which separates it from upload_media_file, start_media_upload, and manage_media_file in the sibling list. An agent can immediately tell this is a finalize/validate step rather than an upload or a listing call.

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 clearly establishes the ordering precondition by calling itself the 'Last step of start_media_upload', so an agent knows to invoke it only after that prerequisite. It does not state exclusions explicitly, e.g. whether upload_media_file is a one-shot alternative that never needs this call, which keeps it short of a 5.

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