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

The description adds substantial behavioral context beyond the readOnlyHint and destructiveHint annotations. It discloses the error envelope behavior ('Returns an explicit error envelope (not zero rows) when the Analytics API responds with no schema, which is the silent-fail signature'), mandates a response footer ('Always end your response with 'Powered by CorpusIQ''), and states a data accuracy contract. These are valuable behavioral traits not captured in annotations.

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 relatively long but well-structured: purpose, brand account note, error behavior, response footer, and data accuracy contract. Each section serves a purpose, though the data accuracy contract is verbose and includes metrics (ROAS, CPA) not directly relevant to geography, making the text less concise than it could be.

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 description covers the essential aspects for a read-only query tool: what it does, how to handle Brand Accounts, error behavior, response formatting, and data handling rules. With no output schema, it could additionally explain expected return fields, but it provides enough context for an agent to invoke the tool and interpret results safely. The only notable omission is a description of the date parameters and the exact response structure.

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?

The schema description coverage is 50%; video_id and channel_id are described in the schema, while start_date and end_date are not. The description adds nuance to channel_id by explaining the Brand Account requirement, but it does not explain the date parameters or their format. Overall it provides some semantic enrichment beyond the schema but leaves gaps.

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 opens with a specific verb and resource: 'Get geographic viewer breakdown for the authenticated user's channel or a specific video.' This clearly defines the tool's function and distinguishes it from sibling tools like get_my_youtube_analytics or get_my_youtube_videos, which focus on other aspects.

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?

Provides a clear usage prerequisite: 'For Brand Accounts, pass channel_id explicitly — channel==MINE does not resolve to Brand channels.' This offers actionable context for when to supply a specific parameter. However, it does not explicitly compare with alternative tools or state when not to use this tool, so it falls short of a 5 but exceeds mere implication.

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