Show Media Stats

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint), so the bar is lower. The description adds genuinely useful context beyond them: the required "Read detailed stats" permission and the delegation behavior of the all:delegate_to_contact_permissions scope. It does not, however, say what the returned statistics contain.

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 core purpose is front-loaded in the first sentence, which is good. The trailing "Read-only account operation." merely restates the readOnlyHint annotation and the permission block is rendered with stray blank lines and nested code fences, adding some noise without adding meaning.

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?

There is no output schema, so the description carries the burden of telling the agent what comes back — it only says "statistics" without describing the shape of the return. Combined with the unresolved overlap against get_media_stats/get_media_stats_by_date, the definition is adequate but leaves real gaps.

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 both media_id and account are already documented in the schema. The description merely restates that media-id identifies the video and adds no format, accepted-value, or fallback detail beyond what the schema provides — the baseline 3 for full schema coverage.

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 uses a specific verb and resource — "Retrieve stats for a video" — and clarifies that the video is identified by its media-id. However, it never distinguishes this tool from the near-identical siblings get_media_stats and get_media_stats_by_date, so an agent cannot tell which stats endpoint it actually wants 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 statement of when to use this endpoint versus get_media_stats, get_media_stats_by_date, or get_media_analytics. The only conditional guidance is about token permissions, not about tool selection, so usage must be inferred entirely from the name.

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