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 substantive context beyond that: BETA status/date, tier-based export quotas (free 3 badged 720p, trials 2 clean/day, subscribers unlimited), and that frames emits images with microsecond timestamps and can append to an evidence packet.

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?

Front-loads the core action set and the frames semantics before the quota/tier detail, and every sentence carries information. The quota passage is dense but relevant to callers; the video_guide routing would arguably be stronger earlier.

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 4-param, no-output-schema tool with annotations present, the definition covers purpose, per-action behavior, parameter meanings, tier limits, and the prerequisite guide call. Sufficient for correct invocation; the only minor gap is no explicit statement of return shape for list/get (though frames is described).

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 0%, so the burden is on the description, and it does explain all four inputs: assetId, timesUs as integer microseconds, optional inspectionId that appends frames to an evidence packet, and the action enum. It adds real meaning over the bare schema, though it doesn't cover edge cases like invalid or out-of-range timestamps.

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?

Names the resource (Video Director managed media) and enumerates the three actions (list|get|frames), so the agent knows it is an asset-access tool rather than a producer/project tool. It stops short of explicitly contrasting with siblings like video_projects or video_jobs, but 'media' plus the action set is specific enough to disambiguate.

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?

Explicitly routes the agent: 'Call video_guide first for the catalog, the exact input schema of each action and this account's tier notes,' which is a clear precondition. It also scopes the 'frames' action's purpose. It does not spell out when to choose list vs get vs frames over each other, so it falls short of full when/when-not guidance.

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