YouTube Transcript & Search MCP Server

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

Beyond the annotations already disclosing destructive and idempotent behavior, it states the partial refund policy and that completed work remains paid for and stays in results. It also notes the operation is free, which is useful non-obvious 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?

Three short sentences, each valuable: the operation, the refund semantics, and the cost. The core intent appears first and there is 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 single-parameter destructive operation with an output schema, the description covers the most important behavior and economics. It could mention what happens if the job is already complete or already canceled, but idempotentHint partially covers that.

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 description does not add param details, but the schema already provides full coverage: job_id is described as 'id returned by submit_transcripts_job'. The description's general reference to 'a batch job' aligns with this parameter, so no real gap exists.

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 starts with 'Cancel a batch job', clearly naming the action and its target. It is easily distinct from the get/search/submit siblings, and the title reinforces the operation.

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 refund condition ('Credits are refunded ONLY for videos not started yet') gives a concrete rule for deciding whether a cancellation is still worthwhile. It implies this should be used when the caller wants to stop a previously submitted batch job, though it does not explicitly list when to avoid cancellation.

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

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

The annotations already declare readOnlyHint=true, and the description reinforces this with the word 'Check'. It adds context beyond annotations by noting the tool is free and by clarifying the credit accounting relationship with submit_transcripts_job (1 credit per video). This is useful behavioral context, though it does not discuss output format 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?

Two concise sentences cover purpose, cost, and two concrete use cases. There is no filler, and the primary action is front-loaded. Every sentence adds value.

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, parameterless tool with no additional configuration, the description covers all necessary context: what it does, when to use it, and how credit usage relates to submit_transcripts_job. The output schema is present, so the return value format does not need to be described in the text. Nothing essential 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 has zero parameters, and the schema is fully clear with an empty object. The description adds no parameter information because none is needed; this is the appropriate baseline for a parameterless tool.

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 action and resource: 'Check the remaining credit balance of the API key.' It is unmistakably distinct from the sibling tools, which all concern transcripts, videos, or channels, so an agent can identify this as the credit balance tool without ambiguity.

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 gives explicit usage conditions: use it when the user asks about remaining credits, or before submit_transcripts_job to confirm a large batch fits. It also mentions the alternative context of submitting a job and the credit cost per video, making the decision clear.

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

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

Beyond the readOnlyHint annotation, the description discloses billing behavior (costs 1 credit, metadata call avoids an extra charge), default track behavior (manual vs auto fallback), segment defaulting per track type, and format-specific output differences. It also notes that srv3 does not combine with segment. These are meaningful non-obvious behaviors.

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

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

The description is longer than average but information-dense. It front-loads the core purpose, then the billing optimization, then format choices and usage preferences. A small amount of repetition with the schema descriptions exists (e.g., format meanings), but every sentence contributes functional value.

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 tool with 6 parameters, an output schema present, and related sibling tools, the description covers the important edge cases: metadata inclusion, cost avoidance, format trade-offs, track selection, and segmentation behavior. An agent gets enough context to call this tool effectively without additional exploration.

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 parameters, but the description adds substantial semantics beyond it: cost implications of video_metadata, format selection guidance, and track-specific segment defaults. This is helpful and non-redundant.

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: 'Get the transcript (subtitles) of a YouTube video.' It also clarifies accepted inputs ('video id or any YouTube URL'), immediately distinguishing it from sibling tools like get_video_info and the get_transcripts_* job tools. The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: it instructs the agent to set video_metadata=true to avoid a separate billed get_video_info call, explains when to prefer specific formats ('Prefer text unless you need timestamps or a file'), and gives segment sizing advice for embeddings/retrieval. This is strong usage direction.

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 and openWorldHint, so the non-destructive nature is covered. The description adds value beyond that: it clarifies cost behavior (polling is free), the specific statuses an agent can observe, and that only counts/status are returned here — not transcript content, which is an agent-facing distinction.

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: purpose with enumerations, a free-cost behavioral note, and a routing to the replacement tool. Barely any waste; the phrase 'a job you already paid for' is slightly redundant with 'Free', keeping it from a perfect 5.

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 one-parameter, read-only tool with a full schema description and an output schema, the description is nearly self-contained. It omits only a fully spelled-out poll-then-fetch workflow (poll until done, then call get_transcripts_results), which would make the agent's end-to-end behavior unambiguous.

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, job_id, and the schema already documents it fully as 'id returned by submit_transcripts_job' (100% coverage). The description's 'job you already paid for' is consistent with that but adds no new semantic 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?

Describes a specific verb+resource ('Check the progress of a batch job') and enumerates what is returned (status queued/running/done/cancelled, counts of ready/failed/pending). It also names the sibling get_transcripts_results, so an agent can clearly tell this progress-checker apart from the transcript-reading tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

States when to use this tool (checking job progress) and explicitly routes the agent away when it needs transcripts: 'Read the transcripts themselves with get_transcripts_results.' The 'Free — polling a job you already paid for costs nothing' note additionally reassures the agent that frequent polling is safe, which is a practical usage condition.

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

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

Beyond the readOnlyHint annotation, the description adds meaningful behavioral disclosures: the exact meaning of a 404 and the explicit recommendation to consult get_transcripts_job, plus the 'Free' cost note. This goes well beyond what the schema or annotations already 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?

The description is concise: three short sentences, each earning its place. The opening line gives the purpose, the second provides critical error semantics, and the third addresses cost. No filler or redundancy.

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

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

Given the tool's simple two-parameter input, a readOnly annotation, and an output schema, the description is complete. It covers purpose, differentiation, error handling, and cost, and refers to the right sibling tool for follow-up—leaving no critical gaps for an agent to invoke 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 100%, with clear descriptions for both job_id and video_id. The tool description does not need to repeat parameter details, but it also does not enrich them beyond the schema, so the baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Read') and exact resource ('ONE video's result out of a batch job'), and clearly differentiates the tool from its plural sibling get_transcripts_results by saying 'without paging through get_transcripts_results.' This makes the purpose unambiguous and immediately distinguishable.

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 explains when to use this tool—when you need a single video result from a batch—and names the alternative 'get_transcripts_results' by advising against paging through it. It also provides important "do not assume worst case" guidance by telling agents to check get_transcripts_job on 404 before concluding anything.

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

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

The readOnlyHint=true annotation declares safety, and the description adds meaningful behavior: partial results appear before job completion, each entry includes status, pagination via next_page_token, and it's free. No contradiction; the extra context complements the annotations.

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

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

Three sentences with high information density and no fluff. It front-loads the core purpose and then adds caveats and pagination. It could be slightly more structured or clearer about parameter usage, but it earns a solid score.

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, the description doesn't need to explain return values in depth. It covers key operational details: partial results before completion, per-entry format, pagination. Minor lack of explicit rate limits or error conditions, but not essential given the output schema 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 description doesn't need to document parameters in depth. It still adds value by explaining that order is submission order and confirming pagination behavior through next_page_token—semantics beyond field names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool reads finished transcripts from a batch job in submission order, which distinguishes it from siblings like get_transcripts_job (job metadata) and get_transcript (single transcript). The verb 'read' plus the resource 'finished transcripts from a batch job' makes the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It says this can be called before the job is done since results appear as fetched—useful timing guidance. It also notes each entry equals what get_transcript returns, indirectly distinguishing it from that sibling. It lacks explicit when-not-to-use conditions, but the context is mostly clear.

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

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

Beyond the readOnlyHint/openWorldHint annotations, it discloses a key behavioral boundary: it returns transcript languages but does NOT download the subtitles. It also discloses the cost trade-off compared to get_transcript, which is information not present in annotations, schema, or output schema.

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

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

The description is front-loaded with the function purpose and output scope, then immediately provides the routing instruction to get_transcript. Every sentence adds distinct information in a compact form 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 one-parameter read-only tool with an output schema, the description covers what it returns, what it omits, when to use it, and when to call an alternative. Nothing an agent needs to route the call 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 explains the single parameter. The description reinforces that the call targets 'one YouTube video,' but it doesn't add new syntax, formats, or constraints beyond the existing schema coverage. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly names the operation ('Get metadata for one YouTube video'), enumerates the specific metadata fields returned, and explicitly notes it returns transcript languages without downloading subtitles. This distinguishes it immediately from get_transcript, the closest sibling, while also limited to a single video as opposed to list/search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives an explicit when-to-use rule: 'Use it only when the transcript itself is not wanted.' It then names the recommended alternative with exact parameters and cost implications: 'call get_transcript with video_metadata=true instead — it returns both for one credit, where these are two separate calls and two credits.'

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

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

The description adds useful behavior beyond the readOnlyHint by revealing that data comes from the RSS feed and that the result is approximate (~15 videos). It also signals cost/performance ('fastest and cheapest'), which helps an agent choose between similar tools.

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 contain only relevant information: what the tool returns, approximately how many items, what source is used, and why this is a good option. The key scope and cost signals are 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?

For a single-parameter tool with a documented input schema, an output schema, and readOnly annotations, the description covers the essential behavior: source, result size, speed, and intended use. There is no critical missing information an agent would need to 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?

The input schema already fully describes the parameter, listing accepted forms such as @handle, channel name, UC... channel id, or channel URL, and schema description coverage is 100%. The description only weakly reinforces that the parameter refers to a channel, so no significant value is added 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?

The description names a specific operation ('get the ~15 most recent videos of a channel'), a resource ('channel'), and a concrete source ('RSS feed'). It distinguishes itself from sibling listing/search tools by framing itself as the fastest, cheapest way to check recent channel publications.

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 clearly establishes when to use it: when you need a quick, lightweight check of what a channel recently published. It does not explicitly exclude cases like full channel listing or searching, but its intended niche is clear from the wording.

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

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

The description discloses meaningful behavior beyond the annotations: newest-first ordering, accepted channel identifier formats, ids_only behavior, and the 500-per-page ceiling. Since readOnlyHint=true already signals the operation's safety profile, the description does extra work by documenting ordering and output modes. There is no contradiction with the read-only 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?

The description is concise yet information-dense, with no filler or redundancy. The core action and ordering are front-loaded, and the id-only optimization is explained in a short second sentence.

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

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

Given the rich input schema, output schema, and readOnlyHint annotation, the description covers the remaining essentials: ordering, accepted identifiers, ids_only behavior, and pagination limits. The only material gap is the lack of explicit differentiation from the sibling list/search tools, which means an agent must infer when this tool is preferred.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already has 100% parameter coverage, so the baseline is solid. The description adds value by explaining the purpose of ids_only, clarifying that a channel name or handle is acceptable even though the schema names the parameter 'name', and noting the 500-item limit when ids_only is used. This is a meaningful complement to the schema rather than a mere restatement.

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 clear verb and resource: it lists videos from a channel's Videos tab, and it adds a useful behavioral detail by specifying 'newest first'. It also lists the accepted identifier formats, which helps an agent identify valid inputs. It does not explicitly differentiate itself from the sibling tool latest_channel_videos, so some sibling distinction 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?

The description provides one specific usage guideline: use ids_only=true when you only need IDs to fetch transcripts, which is genuinely useful for call selection. However, it gives no explicit guidance about when to prefer this tool over search_channel_videos, latest_channel_videos, or list_playlist_videos. The intended use case is implied rather than clearly stated.

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 provide readOnlyHint=true, and the description goes further by disclosing playlist ordering, ID/URL input flexibility, and the up-to-500-per-page behavior with ids_only. This adds meaningful behavioral context beyond a simple 'list' label.

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 sentence states the core behavior, and the second covers input forms and the ids_only pagination nuance. Every phrase 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 an output schema present, readOnlyHint=true, and full schema documentation on parameters, the description covers the important nuances: playlist-order listing, accepted id shapes, and ids_only pagination constraints. No major calling concern is left unexplained.

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 baseline is 3. The description adds extra detail: id can be a PL... id or a URL with list=, limit has a 500 cap only with ids_only, and ids_only changes the response shape to video IDs. This goes beyond the schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (list videos), the resource (a playlist), and a distinctive behavioral property ('in playlist order'). It does not explicitly distinguish itself from search_playlist_videos, but the list-vs-search distinction is reasonably inferable from the wording.

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 gives clear context: it accepts a PL... playlist id or a list= URL, and explains the ids_only option and page-size behavior. It does not explicitly say when to choose this tool over alternatives like search_playlist_videos, but the intended call pattern is clear enough.

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

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

The readOnlyHint and openWorldHint annotations already signal safe read-only behavior. The description additionally discloses that results are relevance-ranked rather than keyword-matched, including the non-obvious fact that matching videos may lack the query in their title; this is meaningful behavioral context beyond 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?

The two sentences are front-loaded and free of waste. The first sentence defines the operation and scope, and the second guards against an agent misinterpreting relevant results that do not contain the query text.

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

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

Given the rich input schema, existing output schema, and read-only annotations, this is nearly complete for an agent insert-correct call. The small gap is that it does not state what happens when no channel is identified or how to route among the similar channel/playlist siblings, which agents must infer from sibling names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not materially deepen any parameter beyond what the schema already documents, such as q, the channel identifier forms, or pagination token.

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 action and scope: search videos inside one channel. It also adds the YouTube-native relevance-search detail, which clearly separates it from a general YouTube search or a plain channel listing 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?

There is clear context: this is for searching within a single channel using YouTube's relevance ranking, so an agent can distinguish it from cross-YouTube search or listing tools. It does not explicitly name when-not-to-use alternatives or provide exclusions, 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?

Beyond the readOnlyHint/openWorldHint annotations, the description discloses two non-obvious behaviors: the fixed 500-item scan window and the meaning of truncated=true. This is exactly the kind of caveat an agent needs to know before relying on the result — it cannot infer the scan limit or the partial-result flag from the schema and would otherwise assume the result is 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?

Three short sentences with zero fluff: it front-loads the matching behavior, gives the platform rationale, and closes with the critical truncation caveat. Every sentence earns its place and the ordering is maximally informative.

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 and readOnlyHint/openWorldHint annotations covering the safety profile, most of the burden is already borne by structured fields. The description covers the key additional semantics (scan window, truncation). Minor gaps that remain are being explicit about result ordering and behavior on invalid playlist IDs, which are small for a 3-parameter 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% (id, q, limit each have meaningful descriptions with ranges and defaults), so the baseline is 3. The description adds only the case-insensitivity nuance about q via prose; no per-parameter detail is added beyond what the schema already provides.

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 first sentence states a specific verb+resource and the match mechanics: 'Find videos inside a playlist by a substring of the title (case-insensitive).' This clearly differentiates from siblings like search_youtube (global search), list_playlist_videos (full listing), and search_channel_videos (channel-scoped) by confining the search to an existing playlist.

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 rationale ('YouTube has no native playlist search, so this scans up to 500 playlist items') explains why the tool exists and tells the agent it is the workaround for that platform gap. However, it does not name any alternative tool, give explicit when-not-to-use guidance, or point to a sibling like list_playlist_videos for full enumeration, so the agent is left to infer the decision boundary.

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 indicate readOnlyHint and openWorldHint, so the safe read-only nature is already established. The description adds valuable behavioral context: it explains the pagination pattern and the meaning of has_more, which are not present in the input schema. No contradiction with annotations 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?

The description is two sentences, front-loads the core search capability, and includes pagination guidance efficiently. There is no filler or redundant restating of the title.

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 presence of a rich input schema, an output schema, and annotations, the description covers what an agent needs to invoke the tool correctly, especially the pagination loop. Nothing critical is missing for a search tool with this structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already documents all four parameters with 100% coverage, so the baseline is 3. The description adds meaning by linking next_page_token to the pagination flow and mentioning that has_more indicates another page, which helps agents understand the parameter interaction beyond the schema's individual field descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches YouTube for videos or channels, a specific verb and resource. This distinguishes it from sibling tools like search_channel_videos, which are scoped to specific contexts rather than a general YouTube-wide 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?

The description provides clear pagination usage guidance with next_page_token and has_more, but it does not explicitly state when to choose this tool over siblings such as search_channel_videos or latest_channel_videos. The intended usage is implied rather than explicitly contrasted.

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

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

The description discloses the asynchronous execution model (background processing after immediate job_id), the billing dimension ('Costs 1 credit per video, charged on submit'), deduplication, and the auth requirement (sk_... key). All of this goes well beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false) and enriches the agent's picture of side effects. No contradiction with annotations.

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

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

Five sentences that are all load-bearing: the core value, the when-to-use rule, the input source, the follow-up workflow, and the costs/dedup/auth. It is front-loaded with the most critical information first and contains no filler or restatement of schema content.

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 async batch operation with 7 parameters, the description covers the entry criterion (many videos vs handful), how to invoke it (input sources), what comes back (immediate job_id), the costs, the required key, and the full downstream contract (poll get_transcripts_job until 'done', read results from get_transcripts_results). The output schema handles return-value specifics, so nothing essential 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?

With 100% schema description coverage, the baseline is 3 and the schema already documents every parameter including segment sizing guidance and idempotency_key behavior. The description adds a sourcing hint for videos (feed from list-channel/playlist tools) and the credit-per-video math, but it does not provide per-parameter explanations beyond the schema — a correct middle ground.

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 and resource: 'Queue transcripts for MANY videos at once (up to 4000) and get a job_id back immediately'. It differentiates this batch tool from its sibling get_transcript and the polling/result tools, so an agent understands exactly what this tool does and what it is not without reading any other definition.

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 tells when to choose it: 'Use this instead of calling get_transcript in a loop for more than a handful of videos.' It also tells the agent where to get inputs ('Feed it video ids from list_channel_videos or list_playlist_videos') and exactly which sibling to poll next (get_transcripts_job, get_transcripts_results). This is explicit routing, not implied.

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