upload_reference_media

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

Goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) by disclosing that media is re-encoded with metadata stripped, the real container and duration are validated, login is verified, and the result is an account-scoped id. It also flags that existing storage URLs may be public and that uncertain uploads must not be retried — exactly the mutation-side context annotations cannot carry.

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?

Four sentences, all front-loaded with the core action first, then requirements, then behavior, then caveats. Dense but nearly every sentence carries non-redundant information; only mild compression of the requirement list is possible.

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 no output schema, the description correctly names the return value (reference_media_id) and its account scoping, plus the validation performed. Little is missing for a 3-parameter upload tool, though failure modes (e.g., what error text an invalid container produces) 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 coverage is 67%, and the description compensates by defining the accepted container types for media_type (MP4/WAV/MP3) and reinforcing the upload-root constraint on file_path. The model_type duration distinction is already in the schema, so it adds no new detail there, keeping this at a strong 4 rather than 5.

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?

Opens with a specific verb and resource ('Upload one user-authorized local MP4 video or WAV/MP3 audio for omni reference video generation'), naming accepted formats and the downstream purpose. This clearly separates it from upload_reference_image and upload_speech_audio without needing to open their schemas.

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?

States prerequisites (dedicated upload directory, user authorization, local FFmpeg/FFprobe) and two explicit exclusions: it does not generate or spend credits, and it should never auto-retry an uncertain upload. It stops short of naming sibling tools like upload_reference_image as the alternative path, so context is clear but alternatives are unstated.

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