YouTube Transcript & Search MCP Server

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

Annotations already indicate destructive and idempotent behavior. The description adds valuable nuance: credits are refunded only for videos not started, and already-fetched content remains paid for and remains in results. It also states calling it is 'Free', which clarifies cost implications beyond the refund note.

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 short and efficient: it states the core action first, then the key refund caveat, then the free-to-cancel fact. Every sentence earns its place 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 one-parameter destructive action, the description covers the essential behavioral nuance (refund policy), annotations cover idempotency and destructiveness, and an output schema is already available. The only minor gap is not explicitly describing what happens to the job itself after cancellation, though it is largely inferable.

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 only parameter, `job_id`, is fully documented in the JSON schema with its source (`id returned by submit_transcripts_job`). The description adds no additional parameter-level guidance, which is acceptable because schema coverage is 100%.

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 verb-action ('Cancel') and resource ('a batch job'), and ties cancellation to a specific `job_id` from `submit_transcripts_job`. It distinguishes this tool from all sibling read/query tools 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 explains the result of canceling and the credit refund condition, but it does not explicitly state when to use this tool versus alternatives, such as checking job status with get_transcripts_job or allowing the job to continue. The right usage is implied by the action name, not spelled out.

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 mark this read-only, and the description adds that it is 'Free,' which is a useful operational trait beyond the schema. It also clarifies the billing behavior of the related submit_transcripts_job tool, adding context that helps the agent reason about the overall workflow.

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 brief and front-loaded with the core purpose, followed by a single useful usage directive. Every sentence adds value; there is 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?

With zero parameters, an output schema present, and clear use-case guidance including a cancellation-around submit_transcripts_job, nothing essential is missing. The description fully equips the agent to select and call 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 tool has zero parameters, so there is nothing to describe. Schema coverage is 100% and the description adds no redundant parameter detail, which aligns with the baseline for 0-parameter tools.

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?

Description starts with a specific action verb ('Check') and a clear resource ('remaining credit balance of the API key'), making the tool's purpose unambiguous. It is clearly distinct from all sibling tools, none of which concern credit balances.

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

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

Explicitly states when to use it: 'when the user asks how many credits are left' and gives a concrete workflow, 'before submit_transcripts_job to confirm a large batch fits the balance.' This is actionable, context-rich routing guidance.

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

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

Adds meaningful behavior beyond annotations: states the tool costs 1 credit, is a billed call, and describes track/segment defaults and format outputs. The readOnlyHint annotation is consistent with this being a retrieval operation, and the description enriches trust with cost and default behavior details.

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?

Every sentence is purposeful and front-loaded with the core purpose. It packs format semantics, cost, and sibling-tool routing into a compact, readable description without 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 rich schema, output schema, and read-only annotations, the description covers all the decision-relevant context: when to use, which format to choose, cost implications, and how to avoid duplicate calls. The agent has enough to invoke correctly without further research.

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 covers all parameters with 100% description coverage, so the baseline is strong. The description adds practical selection guidance for format (e.g., 'cheapest to read') and clarifies the billing benefit of video_metadata in one call, going slightly 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 and resource: get the transcript of a YouTube video, and clarifies accepted input forms (video id or URL). It distinguishes itself from sibling get_video_info by explicitly noting that metadata is included and a separate call is unnecessary.

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?

Provides explicit usage routing: 'Prefer text unless you need timestamps or a file' and warns against calling get_video_info first when video_metadata=true. This gives the agent clear decision rules for format and metadata usage.

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 mark this as read-only, and the description adds useful behavioral context: it lists the possible statuses, reports readiness/failure counts, and states that polling is free. This exceeds what annotations alone provide without contradicting them.

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 earning its place: one for purpose/outputs, one for cost behavior, and one for directing to the results tool. Key details are front-loaded 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 read-only progress tool with an output schema present, this is complete. It covers what is checked, what statuses to expect, what counts are returned, the cost implication, and where to go for the actual transcript content.

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 schema already fully describes the single parameter job_id as 'id returned by submit_transcripts_job' (100% coverage). The description adds no further parameter-specific semantics, so the schema carries the 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 opens with a specific verb and resource — 'Check the progress of a batch job' — and enumerates the exact outputs (status, ready, failed, pending), making the tool's purpose unambiguous and distinct from fetching transcripts.

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 clearly tells the agent when to use this tool (for batch progress polling) and points to the correct alternative for transcript content: 'Read the transcripts themselves with get_transcripts_results.' It does not explicitly contrast with cancel_transcripts_job or get_transcripts_result, but the core usage path is 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?

Annotations already mark this as read-only, and the description adds useful behavioral context beyond that: it documents the specific 404 meaning and directs the agent to a validation step. This goes beyond the annotation baseline without contradicting it.

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, information-dense sentences. The key use case is front-loaded, the alternative behavior is included, and the error-handling note and free status are added without waste.

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?

Because an output schema exists, the description doesn't need to explain return values. It covers the read operation, the matching sibling, error semantics, and the fallback verification step. For a simple two-parameter read tool, this is complete.

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 every parameter is already documented in the schema. The description adds minimal extra meaning beyond mentioning the video id and job id context, 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 explicitly states the operation: reading one video's result from a batch job using its video id. It also directly contrasts with the sibling tool get_transcripts_results, making the distinction clear.

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 tells the agent when to use this tool (single video result) versus paging through get_transcripts_results, and gives an explicit troubleshooting path when a 404 occurs: check get_transcripts_job before concluding.

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 reveals important non-blocking behavior ('Results appear as they are fetched'), the exact per-entry return shape ('exactly what get_transcript returns ... plus its status'), and cost ('Free'). It does not contradict any 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?

The description is compact with four front-loaded sentences, each carrying distinct useful information: purpose/ordering, partial-result behavior, entry format, and cost. There is no filler, making it easy for an agent to parse quickly.

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 paginated read tool with a rich output schema and readOnlyHint, the description covers order, partial results, content shape, cost, pagination, and the timing. 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?

Since the input schema already provides 100% description coverage for all three parameters, the description does not need to add parameter details. It only mentions next_page_token in a pagination example, adding no meaning 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 uses a specific verb ('Read') and a clear resource ('finished transcripts from a batch job') plus ordering ('in the order submitted'), making the primary purpose unambiguous. However, it does not explicitly differentiate itself from the similarly named sibling get_transcripts_result, which could confuse an agent choosing between the two.

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 usage context: it can be called before the job completes and pagination is done with next_page_token. It does not mention any alternatives or when not to use the tool, so it falls short of explicit when/when-not guidance.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the read-only nature is covered. The description adds value by clarifying that no subtitle content is downloaded and by exposing a credit-efficiency nuance: get_transcript with metadata returns both for one credit, whereas this tool and get_transcript would be two calls. This is genuinely useful beyond the structured hints.

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 a strong front-loaded purpose, followed by a quick usage rule and a cost rationale. It is slightly longer than strictly necessary, but every sentence provides distinct value, 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?

With a single well-documented parameter and an existing output schema, the description covers everything an agent needs: what is returned, what is excluded, when to use an alternative, and the cost trade-off. Nothing crucial is missing.

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

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

Schema coverage is 100%: the id parameter is documented as 'YouTube video id or URL'. The description implies it targets a single video and includes fields like title and views, but it does not add meaning beyond the schema. The baseline of 3 is appropriate given the schema is already complete.

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 opens with a specific verb ('get metadata' for one YouTube video), enumerates the exact fields returned (title, channel, duration, views, thumbnails), and adds a constraint ('WITHOUT downloading the subtitles'). It is unmistakably distinct from the sibling get_transcript, which fetches the subtitles themselves.

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 an explicit condition: 'Use it only when the transcript itself is not wanted.' It also names the alternative (get_transcript with video_metadata=true) and explains why that route is better when the transcript is needed anyway. This is model guidance on when to choose this tool over a sibling.

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 mark this as readOnlyHint and openWorldHint, so the main behavioral risks are already covered. The description adds genuinely useful context beyond the annotations: the approximate count of ~15, the RSS feed source, and the speed/cost positioning. These explain important constraints (approximate count, feed-based freshness) that an agent would otherwise not know.

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 with no filler. The first sentence front-loads the core action and resource; the second adds distinct positioning relative to alternatives. Every word earns its place.

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

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

For a single-parameter, read-only tool with a rich output schema, the description combined with the schema and annotations is complete. It tells the agent what it does, what it returns approximately, how to invoke it, and why it is the right choice for a quick recent-videos check. Nothing an agent needs to call it successfully 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 single 'name' parameter is already well documented with accepted formats (@handle, channel name, UC... ID, or URL). The description reinforces the parameter's role ('of a channel from its RSS feed') but doesn't add meaning beyond what the schema provides, so 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 states a specific verb ('Get'), a specific resource ('the ~15 most recent videos of a channel'), and a source ('from its RSS feed'). It also distinguishes itself from siblings by describing how it differs — 'fastest and cheapest way to check what a channel published recently' — which gives a unique identity among the list/search variants.

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 a clear usage context: use this when you need a fast, cheap check of a channel's recent uploads. It implies contrast with heavier sibling tools like list_channel_videos or search_channel_videos, but it does not explicitly state when to avoid this tool or name alternatives, so it falls short of a full 5.

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

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

With readOnlyHint and openWorldHint already covering the safety profile, the description adds meaningful behavior: newest-first ordering, accepted input formats, and up-to-500-per-page behavior for ids_only. It would only need more detail if return values or errors were unexplained, and an 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?

The description is compact and front-loaded: purpose first, then accepted identifiers, then the ids_only optimization and when to use it. Every sentence earns its place, and there is no unnecessary repetition of schema details.

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 list tool with a complete input schema and an output schema, the description covers ordering, identifier types, pagination behavior, and the key ids_only use case. The only notable gap is explicit routing between the closely named sibling tools, which is picked up in purpose and usage.

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 value by explaining when ids_only should be used, the practical reason for it (fetching transcripts), and the fact that limit behaves differently in ids_only mode. It complements the schema instead of repeating 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?

The description names the exact action and resource — list videos from a channel's Videos tab, newest first — and specifies accepted identifier forms (@handle, UC id, URL). It is distinct from playlist and search siblings, but it does not explicitly address how it differs from the closest sibling, latest_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?

It gives clear, actionable guidance for ids_only mode: use it when you only need IDs to fetch transcripts. It does not say when to choose this tool instead of latest_channel_videos or search_channel_videos, so exclusion guidance between siblings is mostly implicit.

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 provide readOnlyHint=true, and the description complements this by being a non-mutating list operation. It adds genuinely useful behavioral details: ordering, accepted playlist id forms, the ids_only result mode, and the rough per-page limit. This goes beyond what annotations alone communicate.

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

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

Three tight sentences with no filler: the first gives the core purpose and ordering, the second explains accepted id formats, and the third covers the ids_only mode. The most important information is 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?

Given that an output schema exists and all parameters are documented within the input schema, the description covers the key behavior an agent needs before calling. It does not explain pagination flow in the sense of 'pass next_page_token for subsequent pages,' but the schema parameter already supplies that detail.

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 mostly restates what the input schema already documents (PL... id or URL with list=, ids_only returns ids), and the 'up to 500 per page' detail is also present in the schema's limit parameter. It adds only marginal clarifications.

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 uses a specific verb ('List') and a specific resource ('videos of a playlist') and adds the important semantic 'in playlist order.' This clearly distinguishes it from a generic video tool, though it does not explicitly distinguish it from sibling tools such as search_playlist_videos or list_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?

The intended situation is implied: use it when you want a playlist's full set of videos in playlist order rather than a search. However, it never mentions alternatives or says 'for search, use search_playlist_videos,' so the agent must infer when this is the correct choice.

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 usefully discloses that results are ranked by relevance, and that a video lacking the query term in its title is normal — a non-obvious behavioral trait. The readOnlyHint annotation already communicates safety, and the description adds meaning beyond it.

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 brief, focused, and front-loaded with the core purpose. Every sentence contributes useful information without 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?

With an output schema available and all parameters documented, the description covers the key behavior and quirk sufficiently. It could mention pagination specifically, but next_page_token and the output schema already provide that context.

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 has 100% parameter description coverage, so the schema already explains all parameters. The description adds semantic nuance about relevance ranking for the query parameter, which is helpful but not necessary.

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 ('Search') and resource ('videos inside one channel'), clearly distinguishing it from broader search tools like search_youtube or list-style tools. The mention of YouTube's native relevance search adds further precision.

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 that this tool is for searching within a single channel, which implicitly differentiates it from playlist or global YouTube search. It does not explicitly name alternatives or exclusions, but the channel-scoped framing is strong 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?

Adds meaningful behavior beyond the readOnlyHint annotation: case-insensitive matching, a fixed 500-item scan window, and the meaning of truncated=true. This sets accurate expectations for an agent, including the possibility of missing matches.

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 compact sentences with no filler. The core action is front-loaded, and the truncation caveat is stated in exactly the right amount of detail.

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 read-only annotations provided, the description covers the key remaining facts an agent needs: substring semantics, playlist limit, and truncation behavior. Nothing important 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 schema already describes all parameters, so the baseline is 3. The description adds extra value by specifying case-insensitive matching and explaining the scan limit, which influences the output and interpretation of matches.

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: find videos inside a playlist by substring of the title, case-insensitively. This clearly distinguishes it from siblings like list_playlist_videos and 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?

Establishes the context clearly: use it for substring search within a playlist, and explains that YouTube provides no native playlist search. It could go further by naming explicit alternatives, but the implied usage is sufficiently 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?

Annotations already indicate readOnly and open-world behavior, so the safety profile is covered. The description adds meaningful behavioral detail about pagination, telling the agent to pass next_page_token and to use has_more to detect another page. This goes beyond the annotations without contradicting them.

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 concise sentences. The first states the core action, and the second delivers essential pagination behavior with zero filler or repetitive phrasing.

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?

The description is adequate for a read-only, paginated search tool with a full output schema. The main gap is that it does not contextualize the tool relative to sibling search tools, which creates ambiguity for an agent choosing among search_youtube, search_channel_videos, and search_playlist_videos.

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 alone already explains q, type, limit, and next_page_token. The description adds some context on how next_page_token and has_more work together for pagination, but it does not add significant meaning beyond what the schema describes.

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 identifies the action ('Search YouTube') and resource scope ('videos or channels'). However, it does not explicitly differentiate itself from sibling tools that also have 'search' in their names, such as search_channel_videos or search_playlist_videos, so it stops short of perfect clarity.

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

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

The description explains how pagination works but gives no guidance on when to use this general YouTube search versus the more specific sibling search tools. It never mentions alternatives, exclusions, or the nuance that q may be required unless paginating.

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 key non-obvious behaviors: work continues in background, credits are charged on submit, duplicates are removed, and a user key is required. These details go beyond the annotations and inform the agent about side effects and prerequisites.

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 compact, front-loaded with the core behavior, and every sentence earns its place. It includes usage, flow, costs, constraints, and credential requirements without redundancy or unnecessary elaboration.

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 complex asynchronous batch operation, the description covers the input source, output behavior, next steps, pricing, second submit guard, and key requirement. An agent has enough context to select and invoke it correctly without additional reasoning about the workflow.

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 schema already covers all 7 parameters, so the baseline is 3. The description adds valuable context for videos, segment behavior, and cost implications, and it explains why to use the batch submit instead of a loop. It slightly exceeds baseline richness.

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?

Description says exactly what it does: queues transcripts for many videos at once, returns a job_id immediately, and continues processing in the background. It clearly distinguishes itself from the synchronous get_transcript tool by emphasizing batch submission and asynchronous results.

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 usage guidance is provided: use instead of get_transcript in a loop, feed IDs from list_channel_videos or list_playlist_videos, and poll get_transcripts_job + get_transcripts_results for results. This gives the agent an unambiguous decision path.

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