YouTube Transcript + YouTube Search MCP

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

Annotations already declare this a safe, open-world read (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the safety profile is covered. The description adds genuine behavioral context beyond that: it caps the result at the 15 newest uploads and enumerates the channel metadata fields returned, which tells the agent the shape and volume of the response. Pagination and rate-limit behavior remain unstated, so it stops short of a 5.

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, each earning its place: the trigger, the accepted inputs, then the disambiguation. The usage condition is front-loaded and there is no redundant 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?

There is no output schema, so the description must carry the return-value burden, and it does by enumerating the channel fields and the 15-upload cap. Combined with the explicit sibling routing, an agent has everything needed to select and invoke 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?

There is a single parameter with 100% schema description coverage, so the baseline is 3. The description's "Accepts an @handle, channel URL, or UC... ID" merely restates what the schema already says and adds no format constraints, validation rules, or examples beyond it.

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, and goes further by naming what is returned: channel details (name, handle, description, subscribers) plus the 15 newest uploads. This is unambiguous and clearly separable from the other channel-related 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?

Opens with an explicit trigger condition ("when the user asks what a YouTube channel has posted recently") and then names two alternatives with the exact conditions that select them: list_channel_videos for full upload history, search_channel_videos for a topic inside one channel. Nothing is left 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 already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so safety is covered structurally. The description adds genuinely useful behavioral context beyond that: 'Calling it does not use credits' resolves the obvious agent concern for a billing-adjacent tool, and it names what is returned (plan and top-up balances).

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 the usage trigger and reserving the last line for the non-obvious behavioral fact. Each sentence carries distinct information with 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 a zero-parameter status tool with no output schema, the description supplies the trigger, the returned values (plan and top-up balances), and the cost behavior. Nothing an agent needs in order 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?

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to compensate for regarding parameter meaning.

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 ('how many credits their getyoutubetranscript.com account has left') and explicitly distinguishes its domain from every sibling tool, which are all transcript/video retrieval tools. An agent can identify it 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 two explicit trigger conditions: when the user asks about remaining credits, and after another tool reports zero credits remaining. Nothing is left to inference about when to reach for this tool.

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 the safety profile (readOnly, openWorld, non-destructive), and the description goes well beyond them: it discloses the return shape (language + code + creator-uploaded vs auto-generated + default), the edge case that an empty list means captions are off, and the cost of 1 credit. That is meaningful operational context not derivable from the schema or annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, each load-bearing: trigger, return contents, cost, and the negative routing to get_youtube_transcript. Front-loaded with the use case rather than padding, with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description describes the returned fields and the empty-list case, so the agent knows what to expect. Combined with a single fully documented parameter and clear annotations, 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?

Schema description coverage is 100% for the single video_url parameter, so the schema carries the syntax burden (baseline 3). The description adds cross-tool meaning by explaining that the returned code should be passed as `language` to get_youtube_transcript, which is value 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+resource (list caption/subtitle languages for a YouTube video) and explicitly contrasts with the sibling get_youtube_transcript, which also deals with transcripts. An agent can distinguish 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?

Gives both the trigger ('when the user asks which caption or subtitle languages a video has') and a proactive case (before requesting a non-English transcript). It also names the exclusion: 'Not needed for an ordinary transcript request: get_youtube_transcript already reports which language it returned.' This is explicit when/when-not/alternative guidance.

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

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

Beyond the readOnly/openWorld annotations, the description discloses the return shape (one text block plus title/channel), the timestamps format ('[m:ss]' per line), accepted URL variants (watch, youtu.be, Shorts, live), and the no-captions error behavior with a directive not to guess. This is rich behavioral context that annotations do not cover.

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 trigger condition, then return shape, then parameter guidance, then exclusions. Dense and mostly waste-free, though the timestamps explanation partly duplicates 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?

With no output schema, the description carries the burden of describing returns and does so (text block, title, channel), plus covers the error path and URL acceptance. 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%, so the schema already documents all five parameters. The description reinforces the timestamps semantics and ties translate/language to user intent, but adds little 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+resource ('Returns the full spoken text (captions) as one block, plus the title and channel') and the trigger conditions. An agent can distinguish it from siblings like get_transcript_languages or search_youtube 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?

Explicit when-to-use ('user shares a YouTube video link or ID, or asks to summarize, explain, quote...'), when-not ('Do not use for non-YouTube videos or for files the user uploads'), and conditional guidance for the timestamps flag. Only gap is that it never names a sibling alternative, but the routing conditions are unambiguous.

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 safe-read (readOnly, non-destructive) and open-world. The description adds pagination semantics ('one page at a time', pass continuation for next page), which is valuable context beyond the annotations. It stops short of return-shape detail, but with no output schema that's a minor 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?

Two tight sentences: the first front-loads the when-to-use and the second covers the what-it-returns and how to paginate. 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 a 2-param read-only tool with no output schema, the description covers purpose, trigger context, and pagination. It could mention result ordering or that continuation is required for subsequent pages, but the essentials are present.

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 both parameters are already documented in the schema. The description reiterates the continuation-pagination behavior but adds no format or constraint detail beyond what the schema provides. Baseline 3 for a fully-covered 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 (list/browse) and resource (a channel's uploads), and explicitly scopes it to the Videos tab beyond 'latest videos'. This clearly distinguishes it from get_channel_latest_videos and search_channel_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 concrete use case ('older episodes', 'find a video they remember') and contrasts with latest videos implicitly, but does not name the sibling tools or state when-not-to-use (e.g., exclude search_channel_videos).

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 read-only, non-destructive, open-world behavior, so the bar is lower; the description still adds real operational context by disclosing pagination ('one page at a time') and the continuation-token workflow. Ordering semantics ('in playlist order') is also non-obvious value. It does not mention rate limits or failure modes.

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 the usage trigger, then behavior, then the pagination mechanic. No filler or repetition; each 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 paginated list tool with no output schema, the description covers when to call it, ordering, and paging — the essentials an agent needs. It could briefly indicate what fields each returned video carries, but nothing required for 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 description coverage is 100%, so both parameters are already documented, including the 'required unless continuation is set' rule. The description's instruction to pass the continuation token largely restates the schema, so it adds workflow framing rather than new parameter meaning.

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 ('Returns the videos in playlist order') and scopes it to playlists, which implicitly separates it from the channel- and search-oriented siblings. It stops short of naming an alternative tool, so the differentiation is inferred rather than explicit.

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 concrete triggering conditions ('when the user shares a YouTube playlist, or wants to work through a course, lecture series, or podcast playlist video by video') with a worked example. It does not state when NOT to use it or name a sibling to prefer instead, leaving that 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 already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the one bit of useful behavior beyond that: pagination via a continuation token. It says nothing about result limits, ordering, or error behavior when the channel is not found.

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 the usage scenario, then scope, then pagination. No wasted clauses, though the example-heavy opening is near the limit of what's needed.

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 3-parameter read tool with no output schema and full annotation coverage, the description covers selection, scope, and pagination adequately. Return shape and result-count behavior are the only unaddressed items, which is a minor 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 100%, so all three parameters are already documented, and the description's note about passing `continuation` for the next page restates what the schema says. 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?

The description names a specific verb+resource (search videos) and a hard scope constraint: 'Searches only inside that channel.' This cleanly distinguishes it from search_youtube and the list_* siblings, which have no within-channel query semantics.

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 concrete trigger examples ('what has @hubermanlab said about sleep') and states the scoping condition, which implicitly rules out global search. It does not name search_youtube or list_channel_videos as the alternative for the non-scoped case, so routing is inferable but not 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 readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the exact fields returned per result, the pagination contract ('Pass continuation from a previous response for the next page'), and the negative capability that it does not return spoken content. It stops short of describing result ordering or rate/credit behavior, so it is not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences, zero waste, and the trigger condition plus examples are front-loaded ahead of the return-value and alternative-tool notes. Every sentence carries distinct information: trigger, return shape, pagination, and boundary with the transcript sibling.

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 compensates by enumerating returned fields (title, video ID, link, channel, views, length, upload date) and the pagination mechanism. Combined with annotations covering the safety profile, an agent has everything needed to call this correctly and know what comes back.

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 query, search_type, and continuation are already documented in the schema, including the note not to construct continuation tokens. The description's mention of passing continuation adds a usage cue but no syntax or format detail beyond the schema. Baseline 3 is correct 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?

The description states a specific verb+resource ('find YouTube videos or channels') with concrete query examples, and explicitly distinguishes itself from the sibling get_youtube_transcript by scope ('Does not return what a video says'). An agent can route between search and 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?

It gives an explicit trigger condition ('when the user wants to find... before reading or comparing them'), two concrete query examples, and names the alternative tool with the exact condition that selects it (call get_youtube_transcript with a result's video ID). Nothing about when to use or not use this tool is left to inference.

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