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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower, and the description adds real value beyond them: the return is a per-video multiple, 3.2x means 3x the channel's normal, and Shorts are flagged because their views aren't comparable. It doesn't mention quota cost or pagination, but the substantive semantics are covered.

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 tight sentences: what it does, how to read the output, and when to use it. Front-loaded with the scoring method and no filler.

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?

No output schema exists, yet the description explains the return shape (a multiple per video) and the Shorts caveat, and the input schema fully documents parameters. Nothing material is missing for an agent to call this 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 all three parameters (limit, account, channel) are already documented with types, bounds, and defaults. The description adds no parameter-level detail, so the baseline of 3 applies.

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 (score) and resource (a channel's recent videos) plus the exact method: comparing against the channel's OWN median views. This is distinguishable from siblings like get_channel_analytics or search_videos, which don't normalize per-channel.

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?

"Use this before modelling anyone's content" gives a clear usage context and implicitly excludes raw analytics lookups. It doesn't name an explicit alternative sibling or state when NOT to use it, so it stops short of 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?

Adds rich detail beyond annotations: no trash, no undo, collateral loss of views, comments and URL, and the required confirm flag for authorization. This goes well past the destructiveHint and idempotentHint signals.

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 tight sentences, front-loaded with the action and its irreversible consequence. Every clause 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?

For a destructive, irreversible tool with no output schema, the description covers consequence, irreversibility, and the confirm gate, which is what an agent needs to invoke it responsibly.

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 67% with formal descriptions on account and confirm. The description reinforces the confirm requirement, adding value on the highest-risk parameter, though it doesn't detail video_id format.

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 (delete) and resource (video), plus scope (from a connected channel). Distinct from the sibling update_video by its permanently destructive nature.

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 clear usage instructions including a required confirm:true gate, implying this is not for reversible changes. Does not name explicit alternatives, but for a terminal destructive action the guardrail is the relevant 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, non-destructive and openWorld, so the safety profile is covered. The description adds genuine behavioral context the annotations do not: YouTube's own rounding of subscriber counts above 1,000 and the 'hidden' value when an owner hides them — a real edge case an agent would otherwise misread.

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 tight sentences, front-loaded with the lookup capability, then the return payload, then the data caveat. No filler; every clause carries information.

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 correctly enumerates the returned fields and flags the subscriber-count caveat, which is exactly the missing piece. Annotations cover safety and schema covers parameters, so nothing needed to call it correctly is absent.

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 parameters are already documented, including the @handle/id/URL forms and the quota-spending note for 'account'. The description restates the identifier forms without adding syntax or format detail beyond the schema, so the baseline 3 applies.

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 (look up) and resource (channel) with the accepted identifier forms, and explicitly scopes to 'any channel' — implicitly contrasting with the sibling get_my_channel. It also enumerates the returned fields, so an agent knows exactly what it gets.

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 phrase 'any channel' hints at the distinction from get_my_channel and analyze_channel, but no alternative tool is named and no when-to-use/when-not condition is stated. Usage is only implied.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), yet the description adds genuinely new operational context: an OAuth-only access path, the ownership constraint, and a ~2-day data lag. That freshness caveat is exactly the kind of behavior an agent must know before trusting the numbers.

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 tight sentences: the first front-loads what you get, the next two cover access constraints and freshness. No repetition of the schema, no filler.

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 an 8-parameter read tool with no output schema, the description covers payload contents, auth requirements, and data latency, which is most of what an agent needs. Minor gaps remain around pagination (max_results) and the multi-account disambiguation behavior, though the schema handles the latter.

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 88%, so the schema already documents sort, account, filters, metrics, dimensions, and date formats in detail. The description contributes nothing parameter-specific, so the baseline 3 applies — no penalty, but no added value either.

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 the concrete resource (a connected channel's analytics) and enumerates the specific metrics returned — watch time, average view duration, retention, traffic sources, subscriber change — so an agent knows exactly what data this yields. It does not explicitly differentiate itself from siblings like analyze_channel or get_channel, which keeps it short of a 5.

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 gives a hard precondition (OAuth on the channel that owns the data, no API-key path) and an explicit exclusion (it exists for no one else's channel), which tells the agent when this tool is even callable. It stops short of routing to an alternative sibling for other channels' data, so 4 rather than 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 establish readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description still adds real behavioral value by revealing that this targets the authenticated connected channel and returns precise (non-rounded) figures, i.e. private/authoritative data rather than public aggregate data.

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 sentences, no filler, and the payload contents are front-loaded before the sibling comparison. Every clause carries information.

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 listing the returned fields explicitly, and it covers the key differentiator from the nearest sibling. For a simple single-parameter read tool, nothing an agent needs to call it correctly is missing.

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% and the single 'account' parameter is fully documented there, including the failure behaviour when multiple channels are connected. The description adds nothing about the parameter, so the baseline 3 applies.

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?

Names a specific resource (the connected channel) and enumerates exactly what is returned: subscribers, total views, video count and uploads playlist id. It also explicitly distinguishes itself from a sibling, get_channel, so an agent can separate the two without opening either schema.

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 contrast with get_channel ('reads the exact subscriber count rather than YouTube's rounded public figure') gives a clear selection criterion between the two channel-reading tools. It stops short of stating broader when-to-use/when-not conditions, but the discriminating context is present.

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 cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely new operational context: no API key, no connected account, no quota — i.e. zero auth and no rate-limit cost. It also discloses the default return shape and a hard failure mode (caption-disabled videos are unrecoverable), which no annotation conveys.

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 short sentences, front-loaded with the capability and scope; each sentence carries distinct information (scope, auth cost, output modes, failure mode) with no filler or repetition.

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 must describe returns — and it does, specifying prose by default versus timestamped lines. Combined with the auth-free framing and the unrecoverable-caption caveat, an agent has everything needed to call this 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 video, language, timestamps, and group_seconds, including the '[m:ss] text' format and defaults. The description restates the prose-vs-timestamped choice but adds no syntax, format, or constraint detail beyond the schema, so baseline 3 applies.

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 and resource (read the transcript) and immediately bounds the scope with 'ANY public YouTube video, not just your own,' which distinguishes it from account-scoped siblings like get_my_channel or list_my_videos. An agent can identify the target resource without opening the schema.

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 clear routing for the timestamps parameter ('when you need to cite a moment') and a concrete exclusion ('videos with captions disabled have no transcript and nothing can recover one'), which prevents futile retries. It does not name the adjacent transcript siblings (list_transcript_languages, search_transcript), so the sibling-selection guidance is implied rather than explicit.

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 read-only, idempotent, non-destructive, open-world behavior, so safety is covered. The description adds real value beyond that by disclosing partial-failure semantics: a video without captions is reported in place rather than failing the batch, which materially affects how the agent should handle results.

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, zero filler, with the core capability and the 20-item bound front-loaded before the edge-case and use-case notes. Every sentence carries distinct information.

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 batch tool with full annotation coverage and no output schema, the description covers capability, limits, failure handling, and motivation adequately. The only gap is the unexplained 'language' parameter, which no structured field clarifies either.

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 67% and the schema already documents the URL/id formats and the max_chars_each truncation purpose. The description reinforces the 20-item cap and hints at the truncation use case ('openings'), but the 'language' parameter is undocumented in both schema and description, so it adds only marginal 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?

The description states a specific verb and resource ('Fetch transcripts') plus a precise scope ('up to 20 videos in one call'), which implicitly separates it from the singular sibling get_transcript. It stops short of naming that sibling, so an agent must infer the batch-vs-single split rather than being told it.

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?

Two concrete use cases are given ('compare how a set of videos open', 'build a corpus before analyzing it'), which tell the agent when this tool is the right choice. There is no explicit exclusion or pointer to get_transcript for the single-video case, so it falls just short of the top band.

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, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a genuinely non-obvious behavioral trait: tags are only returned to the owning channel and read as empty otherwise, which prevents an agent from misreading an empty tag list as a data error.

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 tight sentences with zero filler. The return-field inventory comes first, and the caveat that qualifies those fields follows immediately after.

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 usefully enumerates the returned fields and discloses the tag-visibility caveat; annotations cover the safety profile. Only minor gaps remain, such as behavior on an invalid or missing video id.

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%: 'video' (id or URL) and 'account' (quota-spending channel) are both documented in the schema. The description adds no further parameter syntax or format detail, so the baseline of 3 applies.

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 ('Full detail for one video') and enumerates the exact fields returned (title, description, channel, views, likes, comments, duration, tags). The singular 'one video' scope implicitly separates it from list-style siblings like search_videos and list_my_videos, but no sibling is named explicitly, so it stops short of a 5.

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 what is returned but never says when to reach for this tool versus get_transcript, search_videos, or get_channel. There are no stated prerequisites or exclusions beyond the incidental tag-visibility note.

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/non-destructive/openWorld, so the safety profile is covered. The description goes further by disclosing the practical contract: the call returns channel names that act as the `account` selector for other tools, which is behavioral context not captured by any annotation.

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 sentences, no filler. The core purpose is front-loaded and the workflow instruction follows immediately, with every clause carrying actionable information.

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?

No output schema exists, yet the description compensates by telling the agent what comes back (channel names) and how to use them downstream, which is the key missing piece for a zero-parameter discovery 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?

The tool takes zero parameters, so the baseline is 4. The description adds relevant semantics about the returned value being consumed as the `account` parameter elsewhere, though it says nothing about ordering or duplication in the returned list.

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 and resource ('List every YouTube channel connected to this server') and scopes it to the server's connections, which cleanly separates it from siblings like get_channel or get_my_channel.

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 prescribes ordering ('Call this first when more than one may be connected') and the downstream action ('pass the name you get back as `account` on the other tools'), so the agent knows both when to invoke it and what to do with the result.

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, non-destructive and openWorld, so the safety profile is covered. The description adds genuinely new behavioral context by flagging that comment text is untrusted third-party content that must be summarized and reasoned about rather than obeyed — a meaningful injection-safety disclosure not present in annotations. It stops short of describing pagination or limits.

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 tight sentences with zero filler. The retrieval purpose is front-loaded and the safety constraint follows, each sentence earning 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?

For a read-only listing tool with no output schema, the description covers purpose, ordering, and an important safety caveat. The main gap is pagination/limit behavior, which is relevant given the `limit` parameter, but the schema handles required params adequately.

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 only 25%, so the description must carry weight; it explains the `order` dimension ('newest or most relevant first') but says nothing about `limit` or `video_id`, and `account` semantics live only in the schema. Partial compensation justifies the baseline 3.

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 and resource ('Read comment threads on a video') and immediately scopes the result with ordering. An agent can distinguish this read-only listing from siblings like reply_to_comment or delete_video without opening a schema.

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 implies the retrieval context by describing the ordering choices, but never states when to use this tool versus alternatives (e.g. search_videos, get_video) or any prerequisites. Usage is inferable but not guided.

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, openWorld and non-destructive, so safety is covered. The description adds genuinely useful behavior: results are ordered newest first, include views and likes, and — critically — surface private and unlisted videos that public-facing tools cannot return, which is non-obvious and affects how an agent should use the result.

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 tight sentences, no waste, with the scope and ordering front-loaded and the differentiating private/unlisted capability last as emphasis.

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 describing returns — it names ordering and included metrics — and it also explains the account-selection failure mode via the schema. Nothing an agent needs to invoke it correctly is missing.

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 limit's default/max and account's failure behavior fully documented in the schema. The description only adds the notion of a 'connected channel' as the scope, so the 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?

States a specific verb and resource (list videos), the scope (a connected channel, i.e. the caller's own channel), the ordering (newest first), and the returned fields (views and likes). The clause about private/unlisted videos being invisible to public tools implicitly separates it from the public search_videos sibling.

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 makes clear when this tool is the right one: when the user needs their own channel's videos, including private and unlisted ones that public tools cannot see. It does not name search_videos or get_video explicitly or state exclusions, so it falls short of a full when/when-not routing statement.

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 cover readOnly/idempotent/non-destructive, so the bar is lower, and the description still adds real value by disclosing that languages are tagged human vs auto-generated and that human captions are more accurate. It does not discuss rate limits or pagination, but for a simple read-only listing that is not a serious gap.

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 short sentences with no filler: what it returns, why it matters, and when to call it. The output shape and the trigger condition are both front-loaded.

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 carries the return-value burden and does so by naming the two fields an agent gets (language, origin). For a single-parameter read-only listing tool, nothing needed to call it correctly is missing.

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?

Only one parameter and the schema already documents it at 100% coverage, including accepted URL forms (watch, youtu.be, Shorts, embed, live). The description adds no syntax or format detail beyond that, so the baseline of 3 applies.

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 (List) and resource (caption languages on a video) plus the discriminating attribute (human vs auto-generated). An agent can distinguish this from the sibling get_transcript without opening either schema.

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 an explicit condition for calling it: 'Call this before get_transcript when the video may not be in English.' Names the sibling tool and the situation that selects it, leaving nothing to inference.

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 declare destructiveHint=true and idempotentHint=false, but the description adds consequences the annotations cannot express: the reply is public immediately, it notifies the recipient, and a later delete does not undo that notification. That is exactly the irreversibility context an agent needs before a non-idempotent write.

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 tight sentences, front-loaded with the action and its visibility/notification consequences, then the confirm gate. No filler and no repetition of the schema.

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 non-idempotent, public mutation with no output schema, the description covers visibility, side effects, irreversibility, and the confirmation prerequisite, while annotations carry the safety profile. Nothing essential to correct invocation is missing.

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 75% and the schema already documents account, confirm, and parent_id in detail; the description only restates the confirm requirement without adding format or edge-case meaning. Baseline 3 applies when the schema does the heavy lifting.

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 (post), resource (public reply), and target (comment thread), plus the acting identity (connected channel). An agent can distinguish this from list_comments and the other read-oriented siblings without opening a schema.

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 a clear operational prerequisite ('Needs confirm: true') that gates invocation, and the schema's account field reinforces the multi-channel condition. It stops short of naming alternatives or explicit when-not-to-use conditions, so it falls short of 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: results are per-occurrence, and each hit is a timestamped deep link that jumps to that second — important since no output schema exists.

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 sentences, zero filler, with the primary capability front-loaded and the sibling contrast second. Every clause 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 correctly takes on the burden of describing the return value (timestamps as jump links). It leaves the language parameter undocumented in both description and schema, a minor gap for an otherwise self-contained 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 75%, with query, video and context_segments documented in the schema and only language undocumented. The description adds no parameter-level meaning (no syntax, no default behavior, no language semantics), so the baseline 3 applies.

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 ('Find every place a phrase is said in a video') and specifies the return shape (timestamps as jump links). It explicitly distinguishes itself from the sibling get_transcript by framing the alternative ('pulling a whole transcript').

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?

'Use this instead of pulling a whole transcript when you only need to locate something' gives a clear selection condition and points at the alternative behavior. It stops short of naming the sibling tool get_transcript explicitly or stating exclusions, so it is clear context rather than fully prescriptive routing.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds genuinely new behavioral context: a separate 100-calls-per-day allowance distinct from the shared 10,000-unit pool, which directly shapes agent behavior. It doesn't cover pagination or result caps beyond the schema's default.

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, all load-bearing: the enriched-output differentiator comes first, the usage intent second, and the quota constraint last. No filler and no repetition of the tool name or schema.

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 does part of the return-value job by naming the attached metrics, and it covers the quota-cost dimension thoroughly. For an 8-parameter tool at 63% coverage, a few parameters (order, published_before) remain undocumented anywhere, leaving a small gap.

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 63%, and the description contributes little parameter-level detail beyond implying that stats (views, likes, duration) are joined into results, which is the context for min_views. Parameters like 'order' and 'published_before' are left entirely to the schema, so this sits at the baseline.

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 and resource ('Search YouTube') plus a differentiator that matters: results come back WITH view counts, likes and duration attached, unlike plain API search. An agent immediately knows this is the enriched-search tool, distinct from get_video or list_my_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?

Gives a clear selection rule ('use this whenever you need to judge whether a result actually performed rather than just matched') and a caution against casual use ('use it deliberately rather than as a first guess'). It stops short of naming a specific sibling tool as the alternative for simple lookups, so it's strong context but not fully explicit routing.

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?

Goes well beyond the annotations: it explains partial-update semantics and the underlying reason (the API replaces the whole snippet, so untouched fields are read back and preserved first), and it explains why it is not confirm-gated (reversible). This is exactly the kind of side-effect disclosure a mutation tool needs. The 'not confirm-gated' framing is consistent with destructiveHint=false.

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 tight sentences with zero filler; the field list is front-loaded and the preservation/confirm-gating rationale follows in support of it. Every clause 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?

For a mutation tool with no output schema, the description covers what changes, what is preserved, and the safety posture, which is the critical information. It omits any mention of failure modes or the return value, but those are minor given the annotations and schema carry the rest.

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 only 17%, so the description must compensate. It names four of the six parameters (title, description, tags, privacy) and states that only passed fields are changed, which adds meaningful semantics; the account parameter's fallback behavior is documented in its own schema entry and video_id is implicit. Coverage of types/formats remains thin, so a baseline 3 fits.

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 ('Change') and resource ('a video's title, description, tags or privacy'), enumerating the mutable fields. It is immediately distinguishable from get_video, delete_video, and search_videos among the siblings.

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 context for use is implied by naming editable fields and by the note that it is reversible and not confirm-gated, which tells the agent it can call it without extra confirmation. However, no alternative tool is named and no when-not condition is given.

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