YTAPI

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety and repeatability profile is covered elsewhere. The description adds genuinely useful non-annotation context: the cost (1 credit) and the returned field set. It says nothing about failure behavior (e.g., unresolvable handle) or rate limiting, leaving it adequate rather than rich.

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 short sentences: the return payload is front-loaded, followed by the input contract and cost. No filler, though the opening is a telegraphic noun phrase rather than a statement of the action.

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 compensates by enumerating the returned fields, and annotations carry the safety profile. The only material gap is the absence of when-to-use routing against the many sibling tools, which for a one-parameter read is a minor omission.

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% and the single parameter is fully documented in the schema. The description restates the accepted forms (handle, channel ID, URL) without adding format examples or precedence rules, so it neither compensates for nor exceeds the schema — 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?

The description names the resource (a YouTube channel) and enumerates the specific fields returned (title, handle, subscriber and video counts, country, links, tabs), so an agent knows exactly what comes back. It is clear but does not explicitly contrast itself with channel-adjacent siblings such as get_channel_videos or search_youtube.

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?

There is no guidance on when to use this tool versus alternatives like search_youtube (to find a channel) or get_channel_videos (for a channel's uploads). The stated input formats (handle, ID, URL) are schema semantics, not usage routing, so the agent must infer selection on its own.

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, idempotentHint=true, openWorldHint=true, so safety is covered. The description adds cost ('1 credit per page') and pagination ('one page at a time') context, which is useful beyond annotations. Return format isn't described, but 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, no fluff, front-loaded with the core action and scope. Slightly terse but 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?

Covers pagination, cost, and default ordering. Missing: explicit handling of cursor usage (though schema covers it) and any note on rate limits or error cases. Adequate for a read-only list tool with full schema coverage and annotations.

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 the schema documents all parameters (cursor, channel, sort_by) thoroughly. The description only echoes the default sort and pagination, adding little beyond 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?

States a specific verb ('Lists') and resource ('a YouTube channel's uploads'), and the default ordering ('newest first'). Clearly distinguishable from siblings like get_playlist_videos or search_youtube.

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?

Implies usage (fetching a channel's uploads) and mentions pagination, but doesn't state when to prefer this over search_youtube or get_video_info. No explicit alternatives or exclusions.

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 only cover safety (readOnly, idempotent, openWorld); the description adds genuinely new behavioral facts: ~20 comments per page, two sort orders, cursor-based page traversal, 1 credit per page, and zero cost when comments are disabled. These are exactly the traits an agent needs before calling.

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, front-loading the return payload, then pagination, then cost. Every clause conveys 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, so the description compensates by naming the returned fields (author, likes, reply count) and explaining pagination and cost. An agent has everything needed to call it correctly and interpret the result.

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 four parameters are already documented, including the dual role of replies_cursor. The description only restates default sort and cursor usage plus the page size, adding marginal meaning beyond the schema, so the baseline 3 is right.

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 ("Returns a YouTube video's comments") and immediately scopes it with pagination size and ordering. This is clearly distinguishable from siblings like get_transcript, get_video_details, or get_video_heatmap 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?

Explains how to proceed for reply threads ("Pass a comment's replies cursor to read its replies") and notes the default ordering, giving clear operational context. It does not name explicit when-not-to-use conditions or point at an alternative sibling, but there is little overlap risk given the sibling set.

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 openWorld, so safety is covered; the description adds genuinely new context by disclosing the paged return behavior and the cost model ('1 credit per page'), which the agent would otherwise not know. It still doesn't say what each returned video entry contains.

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 short sentences, output shape stated first and the cost/rate constraint second; every word carries information and nothing is padded.

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 annotation coverage and a fully described schema, the description covers purpose, paging and billing. The only gap is return-shape detail (what fields accompany each video), which matters somewhat because no output schema exists.

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 documented in structured data; the description only reinforces paging semantics that the cursor field already implies. Baseline 3 applies since the schema carries the parameter burden.

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 ('Returns a YouTube playlist's title and videos') with an explicit scope modifier (one page at a time), which clearly separates it from get_channel_videos and search_youtube. It never names those siblings, so it stops short of full differentiation.

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?

There is no statement of when to pick this over get_channel_videos or search_youtube, and no mention of required inputs or prerequisites beyond what the schema already requires. The only implicit hint is the pagination phrase, which the cursor parameter already conveys.

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 readOnly/openWorld/idempotent annotations by disclosing the cost model (1 credit for the first page, later pages free for 30 minutes), the pagination contract (the result ends with the offset to pass next), and the error/refund behavior for captionless videos. These are exactly the operational facts 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?

Three sentences, front-loaded with what is returned and in what formats, then paging, then cost. No filler; each sentence carries distinct operational 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 carries the return-value burden and does so: it describes the Markdown/text/SRT/VTT shapes and the trailing offset for continuation. Combined with cost and error disclosure, an agent has everything needed to call and continue 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, format, offset, languages, and max_chars. The description largely restates the format variants and adds paging intent for offset, but says nothing about languages selection or the max_chars cap. 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 (returns the captions of a public YouTube video) and names the concrete output forms. It is unambiguously distinct from siblings like get_video_details or get_comments, which return metadata and comment data rather than caption text.

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 context for when this applies: caption retrieval with selectable format, paged output, and an explicit failure case (no captions -> error, no charge). It does not name a sibling alternative or describe 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?

Annotations already declare readOnly, idempotent and open-world, so the safety profile is covered. The description adds genuinely non-obvious context: the tool only works on public videos, and it costs 1 credit, which is exactly the kind of cost/scope information annotations cannot convey.

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 first front-loads what is returned, the second covers the derived metrics and the credit cost. 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 carries the return-value burden and does so thoroughly, plus it discloses the public-only constraint and credit cost. The one real gap is sibling differentiation against get_video_info/get_video_heatmap for an agent choosing between near-duplicate tools.

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?

There is a single parameter at 100% schema description coverage ('YouTube video ID or URL'), so the schema already carries the semantics. The description adds nothing about accepted input forms, 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?

The description names a specific verb+resource and enumerates the returned fields in detail (view/like/comment counts, publish time, description, keywords, hashtags, chapters, links, music, related videos), which is well beyond a tautology. However, it never distinguishes itself from the close sibling get_video_info, leaving the agent unsure which of the two 'video detail' tools to pick.

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?

There is no when-to-use guidance, no exclusion criteria, and no reference to an alternative tool. With a sibling named get_video_info sitting right beside it, this omission is material rather than cosmetic.

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 openWorld, so safety is covered. The description goes beyond them by disclosing cost (1 credit), the error behavior for videos without a graph (free), and the return shape. It does not document rate limits or auth, but adds meaningful behavioral context.

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 deliverable, then progressively adds the retention framing, the failure mode, and cost. Every sentence earns its place with no redundancy; nothing can be cut without losing signal.

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 takes responsibility for explaining return values (moment, peaks, 20-part graph with links) and covers cost and the common empty-graph case. Combined with annotations that cover safety, 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?

Only one parameter ('video') with 100% schema description coverage, so the schema already fully documents it (accepts ID or URL). The description adds no further parameter syntax or format guidance, making the baseline 3 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?

Names a specific verb and resource ('most replayed graph for a video') and enumerates its exact outputs (most replayed moment, five peaks, 20-part graph with timestamped links). This clearly separates it from siblings like get_video_details or 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?

The description implies usage (find retention/rewatch hotspots) and adds useful operational context ('many videos have no graph; that error is free', '1 credit'), but never states when to prefer this over sibling tools such as get_video_info or get_video_details, nor any prerequisites. Usage is inferable 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 cover the safety profile (readOnlyHint, idempotentHint, openWorldHint), so the description only needs to add context. It contributes the cost signal ('Free') and the sequencing constraint that this call should precede get_transcript, which is genuinely useful behavior information. It does not mention rate limits, quota consumption, or failure modes (e.g. unavailable/private videos).

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: what it returns, its cost/position in a workflow, and the sibling to use instead. The return fields are front-loaded and 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?

With no output schema, the description compensates by enumerating the returned fields, and it routes the agent to get_video_details for the fields it does not return. For a single-parameter read tool with strong annotations, 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?

There is a single parameter with 100% schema description coverage ('YouTube video ID or URL'), so the schema already carries the semantics. The description adds nothing about accepted ID/URL formats, 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?

The description names the exact return payload (title, channel, duration, caption languages) for a specific resource, which is more precise than the name alone. It also explicitly contrasts itself with get_video_details, 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?

It states a concrete workflow use ('check which languages exist before asking for a transcript') and names the alternative plus the condition that selects it ('for view, like and comment counts or the publish time, use get_video_details'). Both when-to-use and when-not-to-use are covered explicitly.

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 openWorldHint, so the safety profile is covered. The description adds return field expectations (IDs, titles, channels, durations, view counts) and the credit cost per page, which is valuable behavioral context 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 short sentences, front-loaded with purpose, then return values, then cost. No filler, 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?

Covers purpose, return fields, and cost. Lacks explicit usage guidelines vs. siblings and pagination behavior, but with annotations and full schema coverage, this is largely complete for a search 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 schema documents all four parameters fully. The description only mentions 'page' implicitly without elaborating on pagination via cursor. Baseline 3 is appropriate given 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 (Searches) and resource (YouTube) with scope covering videos, channels, playlists, or Shorts. Distinguishes itself from siblings like get_video_info and get_transcript, which retrieve specific known items rather than performing 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?

Usage is implied by the search semantics, but the description does not explicitly state when to use this vs. sibling tools (e.g., use get_video_info for a known ID). No when-not-to-use guidance.

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