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

Annotations already flag readOnlyHint=false and openWorldHint=true, but the description adds genuinely non-obvious traits: the asset is bound to the uploading account ('usable on that account only'), the source url must be public https, and there is a 50 MB ceiling. The one gap is that it never states re-uploading the same file yields a new assetId (consistent with idempotentHint=false), which matters for callers trying to avoid duplicates.

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?

A single dense sentence with nested parentheses, but every clause carries real information and the core action plus formats are front-loaded. The nested parenthetical lists are slightly harder to scan than a short bulleted structure would be, though nothing is filler.

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 four-parameter creation tool with no output schema, the description covers the essentials: accepted formats, two input transports, size bound, account binding, and the returned assetId. It leaves open whether assets expire and how to enumerate existing assets, but those are secondary for a correct invocation.

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 100%, so the baseline is 3; the description still earns above baseline by adding constraints absent from the schema, notably the 50 MB url limit and the guidance that contentBase64 is for 'small files' only. It also reinforces the account-scoping semantics of email, which is the parameter most likely to be set wrong.

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 opens with a specific verb and resource ('Upload your own JPEG, PNG or WebP image') and immediately names the concrete downstream roles the resulting asset fills (startImage / referenceImage_N for vids_create_video, person photo or logo for vids_create_avatar). That makes it clearly distinct from siblings like vids_get_media or vids_list_avatars, which read rather than create assets.

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?

Usage context is clear: this is the prerequisite step that feeds vids_create_video and vids_create_avatar, and the description tells the caller which transport to pick (public https url vs contentBase64 for small files). It stops short of explicit exclusions — e.g., it never says to use vids_get_media when the asset already exists in the account — so an agent must infer the boundary.

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