Performance of one of your YouTube videos

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

Annotations already provide readOnlyHint=true and destructiveHint=false, and the description reinforces with 'Read-only, 0 credits'. It adds beyond annotations: the 0-credit cost and the prerequisite 'Needs a connected YouTube channel'. No contradictions.

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 description is lengthy but each sentence carries distinct value: metrics, use cases, comparison, defaults, auth/cost. It front-loads the core purpose and metrics, then layered context. Slightly long but not wasteful; a well-structured block.

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 per-video metrics tool with no output schema, the description covers everything an agent needs: the exact metrics returned, use cases, date filtering, default window, cost, and auth prerequisite. Nothing essential is missing for correct invocation.

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 baseline is 3. The description adds useful meaning for videoId by explaining it as 'the v= part of the watch URL, or the videoId returned by post_to_youtube', which goes beyond the schema's generic 'the YouTube video id'. Defaults for startDate/endDate are also echoed, but the videoId clarification is the key added value.

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?

States a specific verb+resource: 'Per-VIDEO performance for a video on the connected channel', then enumerates the exact metrics returned (views, watch time, retention, engagement). Explicitly contrasts with youtube_channel ('cannot answer this'), so an agent can distinguish it from siblings without opening 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?

Gives concrete use cases: 'how did that video do', 'which upload performed best', 'judge an ad before spending more behind it'. Names the alternative (youtube_channel) and states its limitation. Also mentions date-range customization, leaving no ambiguity about when to call this tool.

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