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

Beyond the readOnly and idempotent hints in annotations, the description discloses a critical behavior: the underlying API silently accepts lists but the tool rejects them to avoid mislabeling. It also explains the interpretation of relativeRetentionPerformance (0-1, 0.5 median), which is valuable context that goes beyond what annotations provide.

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 two sentences, front-loading the core purpose in the first sentence and adding critical usage constraints in the second. No unnecessary words, and each sentence earns its place.

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?

With no output schema, the description compensates by outlining the data granularity (1% slices) and the two metrics. It also explains the list-rejection behavior. This is sufficient for a read-only tool with comprehensive annotations and schema descriptions, though it stops short of fully describing the 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 input schema already documents all 5 parameters with descriptions, so the baseline is 3. The description adds meaning by explaining the 1% slice granularity and the semantics of relativeRetentionPerformance, which enriches understanding of the metrics parameter and the tool's output.

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 explicitly states 'The retention curve for a single video' and defines each metric (audienceWatchRatio and relativeRetentionPerformance), making the tool's purpose unambiguous and distinct from sibling analytics tools. It clearly specifies the resource (a single video) and the action (retrieving retention curve data).

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 provides clear usage guidance: use this tool to find drop-off points, and explicitly warns that lists are rejected, so call once per video. However, it does not name alternative sibling tools for comparison, so it falls short of full 5-level guidance.

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

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

The description goes well beyond the annotations by revealing a quota cost ('Costs 1 YouTube Data API quota unit'), a required scope ('needs the youtube.readonly scope'), and a conditional fallback behavior ('with only the analytics scope it reports the scopes it has instead'). These are important non-obvious traits that help an agent predict side effects and edge cases. No contradiction with 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 exactly two sentences. The first sentence front-loads the core purpose and output, while the second adds crucial context (entry point, quota, scope, fallback). Every clause earns its place; there is no fluff or redundancy.

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?

Given the tool's simplicity (0 params, no output schema), the description is complete: it explains the channel it targets, its role among siblings, expected return values (counts or scopes), and caveats (quota, scope requirements). The agent can confidently select and invoke this tool without additional documentation.

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 tool has zero parameters, so the description has no parameter semantics to clarify. Per the rubric, a 0-parameter tool gets a baseline of 4. The description adds no parameter-specific information, but none is needed.

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 clearly states the tool's function: 'Show which YouTube channel this server's OAuth credential owns, with its public subscriber, view, and video counts.' It uses a specific verb (Show) and resource (channel), and explicitly lists the output counts. It also distinguishes itself from siblings by noting 'every other tool reports on this channel and only this channel,' making its unique role as the channel-identifying entry point unmistakable.

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?

The description provides strong when-to-use guidance: 'This is the entry point' and 'start here to confirm you are looking at the right account.' It implies alternatives (the other tools that report on this channel) but does not explicitly state when not to use the tool or name specific alternatives for different purposes. The context is clear enough for an agent to know this is the first tool to call.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context beyond that, such as the YouTube Analytics 2-3 day lag on end_date and the row-count implications of group_by='day' or 'month' for long ranges. However, it doesn't describe the response structure or any edge cases like null metrics, which would be expected without an output schema.

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 sentences: the first lists the metrics, the second explains grouping, the third gives tool positioning. Every sentence serves a distinct purpose with no filler, front-loading the core function first.

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?

Despite the lack of an output schema, the description covers the core functionality, the main grouping option, and guidance on when to choose this tool over siblings. It omits details like exact response field names or pagination, but for an overview tool with strong annotations and schema, this is a reasonable level of completeness.

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%, with each parameter already having meaningful descriptions. The description's mention of group_by='day' or 'month' for a time series is essentially redundant with the schema. It adds no new semantic info beyond what the schema provides, so a baseline score of 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?

Description uses a specific verb ('totals') and resource ('channel') with a clear scope ('over a date range'). It lists the metrics returned and explicitly distinguishes itself from traffic source and video-level tools, making it easy to differentiate from siblings like yt_traffic_sources and yt_top_videos.

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?

Explicitly states when to use it: 'This is the how is the channel doing tool — start with it, then drill into traffic sources or individual videos.' This gives clear usage context and names alternatives, satisfying the when-to-use vs alternatives guidance.

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

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

Beyond the readOnlyHint and idempotentHint annotations, the description discloses quota costs ('Costs 1 YouTube Data API quota unit for publish dates... plus one Analytics query per video') and the exact output structure ('cumulative curve... leaderboard... raw per-day API values'). This is rich behavioral context not present 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?

Four sentences, each serving a distinct purpose: purpose, motivation, output, and cost. No filler or repetition of schema fields.

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 comparison tool, the description covers the core value proposition, the output content, and resource costs. Without an output schema, the return description suffices to set expectations. The missing elements (e.g., exact leaderboard computation) are minor.

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 input schema already provides 100% description coverage for all four parameters, including detailed semantics for window_days and metric. The tool description adds conceptual framing (normalization by age) but not additional per-parameter syntax, so it neither supplements nor conflicts with the 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 opens with 'The derived view: compare several videos on equal terms' immediately stating the tool's function. It specifies the mechanism (re-indexing to days since publish) and distinguishes from raw totals, making it clearly distinct from sibling performance tools.

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?

The description explicitly frames the use case with 'Raw totals cannot answer "is this episode outperforming?" because an older video has simply had more days to accumulate; this removes that.' This tells the agent when to use the tool (fair episode comparison) and when not (raw totals), though it does not name a specific sibling tool as an alternative.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, destructiveHint=false. The description adds context beyond annotations: countries are returned as ISO codes, results are ranked, and it can be scoped to a single video. No contradiction with annotations. It does not mention pagination, but annotations cover the safety profile.

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 three sentences, front-loaded with the primary action, and contains no redundant or filler wording. It efficiently conveys purpose, output format, optional scoping, and use case.

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?

Given the rich schema (100% coverage), comprehensive annotations, and absence of output schema, the description is complete enough. It covers the tool's purpose, output format (ISO codes), ranked results, optional video scoping, and a practical use case. No critical information is missing for an agent to select and invoke the tool correctly.

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 the schema already documents all parameters. The description adds minimal parameter context—'Optionally scope to a single video' paraphrases video_id, and 'ranked' relates to max_results—but does not significantly expand on the schema's detailed parameter descriptions. 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 clearly states it 'break[s] views and watch time down by viewer country, ranked.' It specifies the resource (geographic breakdown) and action, and mentions output format (ISO 3166-1 alpha-2). This distinguishes it from sibling tools like yt_traffic_sources or yt_top_videos by focusing on country-level data.

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?

The description provides a concrete use case: 'Useful for deciding where an audience actually is before making scheduling, language, or sponsorship calls.' It implies when to use this tool but does not explicitly name alternatives or state when not to use it. Clear context, but no exclusions mentioned.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, but the description adds substantial behavioral context: it explains what each metric means (e.g., viewsPerPlaylistStart as the 'binge metric'), how grouping changes the output, and that the tool automatically sends a sort order when ranking by playlist. This goes well beyond the 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 compact and front-loaded with the core purpose, followed by a list of key metrics and grouping guidance. Every sentence contributes meaning without redundancy or fluff, making it efficient and well-structured.

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?

Given the tool's complexity (6 parameters, no output schema), the description covers the purpose, key metrics, grouping modes, and sort behavior sufficiently. It doesn't explicitly describe the response row format, but the schema's group_by descriptions handle that, and the description provides enough context for an agent to select and invoke the tool correctly.

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 descriptions cover all parameters (100% coverage), so the baseline is 3. The description adds value by semantically interpreting the metrics (e.g., playlistStarts as 'began the series') and clarifying the effect of group_by values, which enriches understanding beyond the schema's enum descriptions.

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 clearly states the tool reports playlist performance as a series-level view, with specific metrics like playlistStarts and viewsPerPlaylistStart. It distinguishes itself from video-level tools by saying 'not just as bags of videos' and explicitly framing podcasts as playlists, making the resource and action unambiguous.

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?

The description explains the grouping options ('playlist', 'day', 'none') and the sort-order requirement, giving clear context on how to use the tool. However, it does not explicitly name alternative sibling tools or state when not to use it, though the 'not just as bags of videos' contrast hints at when video-level tools are more appropriate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive. The description adds concrete behavioral details: max_results cap, resolve_titles quota cost per 50 videos, no quota for analytics query, and behavior when false. This goes beyond 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?

Three sentences, front-loaded with purpose and downstream usage. Each sentence adds distinct information: ranking criteria, downstream integration, and quota/cap details. No redundancy.

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 no output schema, so the description carries responsibility for return values. It indicates the result includes video IDs and implies metric values, but doesn't specify the exact response structure. Given the simple nature and sibling context, it's adequately complete, though a bit more on return format would be ideal.

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 covers 100% of parameters with descriptions, including defaults and enums. The description reinforces max_results cap and resolve_titles cost but adds little new semantic detail beyond the schema. 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 states 'Rank the channel's videos over a date range by views, watch time, average view duration, or subscribers gained.' This is a specific verb and resource, and it distinguishes from sibling tools by noting the returned IDs feed other tools.

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?

Explicitly says 'Use this to find which videos to look at more closely' and names downstream tools. However, it doesn't provide exclusions or compare with sibling tools like yt_video_performance, so it's clear context but not full when-not guidance.

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

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

Annotations already declare readOnly, idempotent, and non-destructive hints, so the bar is lower. The description adds value by disclosing that source names are returned as API constants (YT_SEARCH, RELATED_VIDEO, etc.), which informs the agent about the exact output format. No contradiction with 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 three sentences, tightly packed with useful information: the breakdown dimension, the diagnostic use case, and the output constant names. No filler or redundancy; every sentence earns its place.

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?

Given a 4-parameter tool with no output schema, the description covers the tool's purpose, the meaning of the output constants, and a compelling use case. The schema handles date and video_id details, and annotations cover safety. It does not explicitly describe return structure or pagination, but those are less critical for this read-only diagnostic tool.

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 the baseline is 3. The description adds indirect context about the video_id parameter ('Optionally scope it to one video') and mentions the available metrics indirectly, but it does not add detail beyond what the schema already provides for each parameter.

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 phrase 'Break views and watch time down by how viewers arrived' and lists concrete source examples (YouTube search, suggested video, channel page, etc.). This clearly distinguishes it from sibling tools like yt_top_videos or yt_video_performance, which focus on different dimensions.

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?

The description explicitly states the diagnostic use case: 'The single most useful diagnostic for why did this take off or why did it flatline.' It gives clear context for when to use the tool, though it does not name specific alternative tools or exclusion criteria, which prevents a 5.

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

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

Annotations already indicate readOnly/openWorld/idempotent hints, but the description adds crucial context: the reporting window is not the video's lifetime (with a concrete example), and resolve_titles incurs Data API quota while the Analytics query does not. This goes well beyond the annotations and clarifies real-world behavior.

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?

Every sentence carries essential information: purpose, differentiation, return shape, window nuance, and quota behavior. The description is front-loaded with the core purpose and structured logically, with no filler or redundant repetition of schema details.

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 analytics tool with full schema coverage and no output schema, the description covers the key contextual gaps: when to use it, the reporting-window caveat, and the quota trade-off for title resolution. It also notes the row-per-video format, making it sufficiently complete for an agent to invoke correctly.

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 coverage is 100%, so baseline is 3. The description adds extra meaning by clarifying the date window semantics ('last 30 days of a video published two years ago') and the per-video row structure, which supplements the schema's param descriptions. It doesn't systematically re-iterate each parameter but adds meaningful context.

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 clearly identifies the tool as providing metrics for specific named videos over a date range, explicitly distinguishing it from the sibling yt_top_videos by the use case 'when you already know which videos you care about.' It also states the return shape ('one row per video'), giving a specific, actionable purpose.

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?

Explicitly positions the tool as the counterpart to yt_top_videos and states the condition for using it ('when you already know which videos you care about'). This provides clear guidance on when to choose this tool over its sibling, and the quota note for resolve_titles adds practical usage direction.

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