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

Annotations already mark readOnlyHint=true, and the description adds meaningful behavioral details beyond that: it returns only structure/ids, provides scoped_video_id to identify the owning timeline, notes asset/clip ids live in the `id` field, and states URLs are absolute. This is useful context for interpreting the response even without an output schema. Minor gaps remain around pagination or error behavior, but they are not critical for a read-only getter.

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?

Three tight sentences with no filler. The core scope is front-loaded, the critical alternative is named immediately, and the parameter guidance and return-field notes each earn their place. Nothing redundant.

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 read-only state tool with no output schema, the description covers enough: what is returned, how video_id scoping affects results, how to identify the owning timeline, and where to find IDs/URLs. It doesn't exhaustively describe all asset fields, but it gives an agent a safe mental model and points to the right sibling for deeper timeline data.

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 description carries the burden. It thoroughly explains video_id semantics, including recommended usage and the main-video fallback. project_id is required and inferable from 'Get a project's videos'; the description does not spell out its format or type, but the name and context make it clear. This is adequate compensation for a sparse schema.

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 combination: 'Get a project's videos, shared library assets, and a video's timeline clips.' It also directly differentiates this tool from video_editor_get_timeline by clarifying it returns structure/ids only, not durations/positions, so an agent can distinguish siblings without inspecting 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?

It explicitly tells when to use the alternative (durations & positions go to video_editor_get_timeline) and gives concrete condition-based guidance for the optional video_id parameter: pass it to scope clips (recommended since clips are per-video), omit to use the main video. This removes ambiguity about invocation.

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