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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds no behavioral context beyond the annotations and schema – it does not mention the 60-day range limit, pagination behavior of top_assets, rate limits, or auth requirements, so it contributes essentially nothing on this dimension.

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?

Two short, front-loaded sentences with no wasted verbiage; the examples are placed immediately after the purpose statement. 'This endpoint' is mild filler but the text is appropriately sized for the tool.

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?

The tool has an output schema and rich annotations, so return values and safety need no explanation. However, for a 6-parameter tool with nested objects (filters, date_range), a metrics enum, group_by granularity, and a paginated top_assets response, the description leaves the agent without guidance on the 60-day cap, how metrics and group_by interact, or when to page top_assets – leaving it only minimally complete.

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 83%, so the schema already documents filters, metrics, group_by, date_range, and the pagination parameters. The description's mention of 'top assets' and 'bandwidth consumption' merely echoes two of the seven metrics enum values and adds no syntax or semantics beyond what the schema provides. Baseline 3 is appropriate.

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+resource ('gives usage analytics data of your videos') and gives concrete examples ('top assets, bandwidth consumption') that map to the metrics enum. However, it offers no differentiation from the many sibling analytics tools (analytics_aggregated_data, analytics_breakdown_data, asset_analytics, retrieve_image_analytics, live_usage_analytics), so an agent cannot tell which analytics endpoint to pick from the description alone.

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?

There is no when-to-use guidance, no exclusions, and no mention of alternatives despite a very crowded sibling set of analytics endpoints. The agent is left to infer that this is the general video-usage endpoint versus the aggregated/breakdown/chart variants.

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