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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered; the description adds useful context about scope requirements ('Needs the write scope') and cost. However, 'Free: nothing is charged' directly conflicts with the schema's budgetUsd parameter (default 2, max 10), leaving the agent with a muddled cost model. It also does not disclose runtime or whether the call is slow for long clips.

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 opening sentence is a long run-on list, but every clause maps to a return type or parameter, and the short trailing sentences (precondition, cost, scope) are front-loaded and waste-free. Slightly denser than ideal, but 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?

With seven parameters, a full output schema, and rich schema descriptions, the definition covers intent, precondition, auth scope, and cost. The remaining gap is the unresolved cost message — an agent cannot tell whether a default call bills the default $2 budget or is genuinely free.

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 baseline is 3. The description does implicitly map its enumerations to parameters (filmstrip→frame_count, chosen seconds→frames, waveform→waveform, words→transcript, spelling→names), but it adds no syntax, defaults, or constraints beyond what the schema already states.

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 names a specific verb and resource ('Look at a video or audio file in the media library') and then enumerates exactly what is returned: duration, size, frame rate, loudness, filmstrip, chosen frames, waveform, and timestamped words. It is clearly distinguishable from neighboring tools such as edit_footage, find_footage, and generate_footage by being the read/inspection step.

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 gives an explicit sequencing rule — 'Read it before edit_footage' — which tells the agent when this tool is the correct precursor. It does not state when not to use it (e.g. versus find_footage for locating an asset first), so it stops short of full alternative routing.

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