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

No annotations are provided, so the description carries the full behavioral burden and does so well: it discloses cost ('one unit from the shared pool'), the error shape for missing handles (error vs. empty result), the hidden_subscriber_count edge case that makes subscriber_count meaningless, and the rounding of subscriber counts. These are all non-obvious behaviors an agent needs.

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?

Front-loaded with the operation and the core constraint, then useful details. Every sentence earns its place, though it runs long and could be tightened. The parenthetical statistics list is efficient.

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 an output schema present, return-value explanation is not required, yet the description still calls out key return fields and edge cases (hidden subscriber counts, meaningfulness of subscriber_count). Combined with the identifier contract and cost disclosure, an agent has everything needed to call 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 0%, so the description must compensate and it does: 'handle' accepts '@name' or 'name', and the exactly-one-of-two constraint is stated. This fills the schema gap fully for both parameters.

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 ('Get a YouTube channel') and immediately constrains the two input modes (by ID or by handle). It also disambiguates against the sibling youtube_list_channel_videos by naming it and clarifying that uploads_playlist_id is the input that sibling resolves. An agent can route correctly 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 description explicitly requires 'pass exactly one of the two' identifier modes, which is concrete selection guidance. It stops short of stating when to prefer this tool over youtube_search_videos for channel discovery, so it's clear on the input contract but not on the wider when/when-not decision.

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?

With no annotations, the description carries the full burden and does so well: it discloses the shared quota pool cost per page, pagination behavior, that replies and reply counts are absent (with a directive never to imply otherwise), the plain-text format, a prompt-injection warning about untrusted comment content, and the disabled-comments failure mode.

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?

Front-loaded with the core behavior, then ordering, pagination, limitations, and failure modes in a logical order. Slightly verbose in the reply/limitation passage, where the no-reply-text and no-reply-count points are restated, but nothing is genuinely wasteful.

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?

An output schema exists, so return shape need not be explained. Given that, the description covers everything an agent needs to call this correctly: ordering, paging, quota cost, content caveats, and the expected empty/failure outcome.

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 0%, so the description must compensate. It documents `order` values and the default, and explains pagination via next_page_token, but never mentions `max_results` or its 1-100 bound, nor the literal `page_token` parameter name.

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 with scope: 'Get a video's top-level comments — text, author, likes, publish time.' The enumeration of returned fields and the explicit 'top-level' scoping lets an agent distinguish it from transcript-oriented siblings without opening any 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 operational context: ordering choices, the default, pagination via next_page_token, the quota cost, and the failure case when comments are disabled (with an explicit 'retrying will not change it'). It does not name a sibling tool or state when to prefer an alternative, 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?

No annotations are provided, so the description carries the full burden, and it does: truncation policy ('truncated at RESPONSE_LIMIT by cumulative text length'), pagination contract (`next_cursor` is the next segment index, `null` means complete), cost ('costs no Data API quota'), and inherited caching/failure behavior from the sibling. It even warns that `duration` is on-screen time, not speech length, because segments overlap.

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?

Front-loaded with purpose and return shape, then usage routing, then pagination/limits. Every sentence carries distinct information; nothing is restated from the title 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?

For a transcript fetch with an output schema present, the description adds everything an agent needs beyond the schema: segment field semantics, truncation/pagination behavior, sibling routing, and quota cost. No meaningful gap remains apart from the undocumented `languages` parameter.

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 0%, so the description must compensate. It explains the pagination parameter's meaning and lifecycle ('the index of the next segment — pass it back to continue; null means you have all segments') and demonstrates `video_id` usage in the deep-link template. The `languages` parameter is never mentioned, leaving one of three parameters undocumented.

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 (fetch a YouTube video's transcript as timed segments) and immediately defines the exact output shape `{text, start, duration}` with unit semantics. It explicitly distinguishes itself from the sibling `youtube_get_transcript`, so an agent can choose between them 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?

Explicit routing: 'Use this to build chapter lists or deep links ...; use `youtube_get_transcript` when you only need the words.' It also gives the operational condition for continuing pagination ('pass it back to continue'). Both when-to-use and the named alternative are 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?

With no annotations, the description carries the full burden and does so richly: no Data API quota, scraped from an internal endpoint, cached forever, server-side truncation at RESPONSE_LIMIT with caption-boundary cuts, first-segment time anchor repeated per page, and named failure modes (captions disabled, missing languages, blocked IP, age-restricted).

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?

Purpose is front-loaded in the first sentence, and the remaining paragraphs are dense and each earns its place (timestamps, pagination, cost, failures). It runs long, but there is little filler; slightly more compression would help.

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?

Even though an output schema exists and would cover return fields, the description still explains next_cursor, truncated, language, and auto-generated flags, plus the truncation/pagination loop. For a tool with a non-trivial paginated return and several failure modes, 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 coverage is 0%, so the description must compensate, and it does for all four params: video_id is an 11-character ID, include_timestamps defaults off and controls [mm:ss] marker insertion density, cursor drives page-to-page continuation, and languages is surfaced through the 'absent in the requested languages' failure mode.

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 ('Fetch a YouTube video's transcript as plain text') and immediately scopes it to one 11-character video ID. It implicitly separates itself from youtube_get_timestamped_transcript via the 'timestamps OFF by default' framing, but never names that sibling explicitly, so the differentiation is left to inference.

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 strong operational context — pagination via next_cursor, free repeat calls, expected failure modes — but never states when to pick this tool over the timestamped, language-listing, or in-transcript-search siblings. Usage is implied rather than routed.

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?

With no annotations, the description carries the full burden and does so: it discloses quota cost (one unit per 50 IDs from a shared 10,000-unit daily pool), that a separate tool uses a different bucket, that parts increase response size but not quota, and that dislike counts are permanently unavailable. These are exactly the behavioral facts an agent cannot infer from the 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?

Front-loaded with purpose, then usage, then parameter guidance, and each sentence carries unique information (quota, missing IDs, part semantics, dislike caveat). It is slightly long at three paragraphs, but nothing is padding.

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?

An output schema exists so return-shape detail is not required, yet the description still explains the one non-obvious return behavior (missing_video_ids). Combined with quota, batching, and part semantics, an agent has everything needed to call this correctly and interpret results.

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 0%, so the description must compensate, and it does: it explains that video_ids accepts a single string or an array of up to 50, and that parts selects snippet/statistics/contentDetails/status with a gloss for each enum value. This adds meaning well beyond the bare schema types.

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 ('Get YouTube video metadata by ID') and enumerates the returned fields (title, description, channel, duration, statistics). It also explicitly separates itself from the sibling youtube_get_video_stats, so an agent can route correctly 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 explicit when-to-use-elsewhere guidance ('If you only need view/like/comment counts, use youtube_get_video_stats instead') and explains how to interpret the missing_video_ids result rather than treating it as a failure. It also states the batch limit (one ID or up to 50) that governs how to call it.

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?

No annotations are provided, so the description carries the full burden and does so: it discloses the separate quota bucket, cache TTL (~3600s and the 0-means-forever semantics), the non-atomic batch behavior with failed_video_ids, and the fact that dislike_count is unavailable and must not be worked around. These are exactly the operational traits an agent needs beyond structured fields.

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?

Front-loaded with the core purpose and the key quota insight, and every sentence carries new information. It is dense and slightly long with nested parentheticals about cache semantics, but little of it is 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?

An output schema exists, so the description needn't restate return values, and it goes further by explaining the partial-success shape (failed_video_ids alongside successful results) and the cached flag semantics. Nothing an agent needs to call this correctly and interpret the response appears to be 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 0%, so the description must compensate, and it does: it explains the parameter accepts either a single ID or a list and enforces an 'up to 50 videos' cap that the schema does not convey. It does not specify ID format (e.g., raw ID vs URL), leaving a minor gap.

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 ('Get view, like and comment counts') plus the scope ('up to 50 videos in one call' and 'one ID or a list'). It explicitly contrasts itself with the sibling youtube_get_video, so an agent can distinguish it 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?

Names the alternative (youtube_get_video) and gives the exact condition that selects this tool: it uses its own 10,000-call/day bucket and 'does not consume the shared pool that youtube_get_video draws on, so it is the cheap way to get numbers.' Clear when-to-prefer guidance with the rationale.

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?

With no annotations, the description carries the full burden and does so well: it discloses no paging (whole list in one response), quota cost (one unit from the shared pool), response language (English titles), and the semantic wrinkle that some categories are assignable:false yet still valid as search filters. These are non-obvious operational facts an agent could not infer otherwise.

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 primary purpose leads, followed by practical notes in a logical order; each sentence adds distinct information. The assignable:false sentence is slightly tangential to invocation but still earns its place by preventing misuse of the returned data.

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 single-optional-parameter listing tool, everything an agent needs is present: scope, parameter format, default behavior, quota implication, and the downstream handoff to youtube_search_videos. Output schema exists, yet the description still usefully summarizes the returned fields.

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 0%, so the description must compensate, and it does: region_code is defined as ISO 3166-1 alpha-2 with concrete examples (US, PT), and the omission default is spelled out (YouTube picks based on the server's location). This fully replaces the missing schema description.

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 opening sentence gives a specific verb and resource ('List YouTube's video categories') plus the optional scoping dimension (region). It is instantly distinguishable from siblings like youtube_search_videos or the transcript tools, since none of them enumerate the category taxonomy.

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 explicitly explains the downstream use case: pass the returned category_id to youtube_search_videos as video_category_id to filter by topic. That is a clear routing signal. It does not, however, state when NOT to use this tool or contrast it against other listing tools, so it stops short of a full 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?

No annotations are provided, so the description carries the full burden and delivers: it discloses the underlying API implementation (uploads playlist via channels.list, cached forever, walks playlistItems), the cost model (one unit per page of 50 from a shared 10,000-unit pool vs. the scarce 100/day search.list bucket), and latency-ish behavior (walk stops as soon as max_results is reached). These are high-value behavioral facts an agent needs for quota-aware planning. It also states what each item does and does not contain (no view counts).

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?

Front-loaded with the core purpose in the first sentence, then cost rationale, then requirements, then per-item contents, then continuation behavior. Every sentence carries a distinct decision-relevant fact; 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?

Given the tool's moderate complexity, the absence of annotations, and the presence of an output schema (so return shape needn't be re-explained), the description covers purpose, routing, cost, prerequisites, item contents, and continuation. Nothing an agent needs to call this 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 0% and there are 2 parameters, so the description must compensate. It clarifies that channel_id must be the channel's ID (not handle) and that max_results controls how far the walk goes, with next_page_token for continuation. It does not spell out the min/max bounds (1-50) that the schema encodes, but the semantics of both params are covered at a level beyond the bare 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 states a specific verb+resource (list a channel's recent uploads) and explicitly distinguishes itself from the sibling `youtube_search_videos`, positioning it as 'the cheap alternative to searching.' An agent can immediately tell when to use this over search.

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 gives the when: 'Use it whenever the question is "what has this channel posted", instead of youtube_search_videos.' It also provides the prerequisite path (start from youtube_get_channel if you only have a handle) and tells the reader where to get view counts. This is textbook routing 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?

No annotations exist, so the description carries the full burden and does: it discloses caching ('Cached forever, costs no Data API quota') and the failure mode ('Fails cleanly when a video has captions disabled or no caption track at all — that is a normal outcome, not an outage'). It also warns that generated tracks are less accurate than uploaded ones.

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?

Front-loads the purpose in the first sentence, then covers return shape, usage routing, and reliability constraints without waste. 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?

An output schema exists, so the field-level return documentation is a bonus rather than a necessity, and the operational caveats (quota, caching, clean failure) round out everything an agent needs to call and interpret this 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?

One parameter at 0% schema description coverage, so the schema provides no help. The description implies the input is a video identifier ('for a YouTube video') but never states the expected format or how to obtain the ID. Minimum-viable rather than compensatory.

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?

Specific verb (List) plus resource (caption tracks available for a YouTube video), and it names the entry fields returned. An agent can distinguish this from youtube_get_transcript, which fetches a transcript rather than enumerating tracks.

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: 'Use this before youtube_get_transcript when you need a specific language, or to tell the user which languages exist.' It names the alternative tool and the condition 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?

With no annotations provided, the description carries the full burden and does so richly: server-side case-insensitive substring matching, per-segment matching limitation, literal-not-regex semantics, pagination via cursor with next_cursor:null signaling the last page, language default behavior, and 'costs no Data API quota; cached.' This is exactly the behavioral disclosure a mutation-free search tool needs.

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?

Front-loads the one-line purpose, then layers limitations, then parameter/pagination notes. Despite its length every sentence adds distinct, actionable information (matching semantics, token savings, quota, caching) rather than restating the name.

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?

Although an output schema exists (so return shape need not be explained), the description still clarifies the match payload (start seconds, total_matches, up to 20 per page), pagination, and matching limitations. Combined with the schema, an agent has everything needed to call and interpret it 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 0%, so the description must compensate, and it does: it explains `query` is a literal substring (not boolean/regex), `cursor` enables paging past 20 matches, `next_cursor: null` marks the end, and `language` selects the caption track with a default. Only `video_id` is left to the obvious name, which is acceptable.

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: 'Search inside a video's transcript and return only the matching segments.' It clearly contrasts with the sibling youtube_get_transcript by emphasizing it returns only matches rather than the full transcript, letting an agent distinguish it 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 a clear usage context with a concrete example ('does this video mention Kubernetes?') and frames the cost tradeoff against pulling the whole transcript, implicitly routing away from youtube_get_transcript. It does not name the alternative sibling explicitly, so it falls just short of 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?

No annotations are provided, so the description carries the full burden and does so: it discloses the scarce 100-calls/day quota bucket, that each page including page_token fetches costs another call, that results carry no statistics (and points to youtube_get_video_stats with its own 10,000/day bucket), and that dislike counts are unavailable since 2021. This is exactly the operational context an agent needs to avoid burning quota.

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?

Front-loaded with purpose and the quota warning, then structured into scannable segments for ordering, date filters, and safe_search. It is long, and a few sentences (e.g. restating the page-cost point) could be tightened, but nearly every line earns its place given the 9 undocumented parameters.

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 9-parameter search tool with 0% schema coverage, no annotations, and an output schema, the description supplies quota economics, safer alternatives, enumerations, timestamp format constraints, and the discovery that only like counts (not dislikes) are retrievable. 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 0%, so the description must compensate, and it does for most parameters: order enum values plus the caveat about incomplete result sets, published_after/before as timezone-aware RFC 3339, safe_search enum and default, region_code ISO format, and video_category_id sourcing. It does not explain max_results or query semantics, so it falls short of fully covering all 9 parameters, but the coverage is well above 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+resource ('Search YouTube for videos by keyword') and immediately distinguishes itself from siblings by naming how it differs from youtube_list_channel_videos and youtube_search_in_transcript. An agent can identify the tool's role 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?

Explicitly tells the agent to prefer other tools first, explains why (scarce 100/day quota), and routes to concrete alternatives with their cost profiles: youtube_list_channel_videos for channel listings and youtube_search_in_transcript for questions about a video. Names the precise condition ('when you genuinely need to discover videos by topic') that should select this tool.

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