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

Goes well beyond the annotations by disclosing billing behavior (consumes 1 AI avatar video from the monthly allowance, and is still charged when Google's safety check refuses the clip), asynchronous latency (1-2.5 minutes), and the returned jobid. These are exactly the non-obvious traits an agent cannot infer from readOnlyHint=false and openWorldHint=true.

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 critical facts (who speaks, resolution, duration, cost, latency, endpoint) are front-loaded and every clause carries information. It is dense with stacked parentheticals, which slightly hurts scannability, but almost nothing is wasted.

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 compensates by explaining that the call returns a jobid rather than a finished video, and how long to expect. Cost, duration, resolution, script limits, and the failure/charging case are all covered, so an agent has enough to invoke it correctly.

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, and the description adds real value on top: the script field accepts voice tags like [whisper] or [short pause], and the avatar runs on the account owning that avatarId (cross-referencing vids_list_avatars). It does not add syntax detail for the avatarId itself, so it stops short of a 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?

States a concrete verb and resource (create a talking-head avatar video from a script) with explicit scope: 1280x720 landscape only, up to 30 s, script up to 400 characters. It directly distinguishes itself from the sibling vids_create_video ('3-15 s scenes with action' vs 'the avatar just speaks to camera'), so an agent can route between them without opening either schema.

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?

Names the alternative (vids_create_video) and the condition that selects it (action scenes vs. one avatar speaking a script), and explains the follow-up path by stating it returns a jobid for vids_get_job. The agent knows both when to pick this tool and what to do next.

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