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

Annotations already indicate read-only and non-destructive behavior. The description adds context about the error case (NO_CAPTIONS), return data (segments, timestamps, language), and that it's free, enhancing transparency beyond annotations.

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

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

Description is extremely concise with only 2-3 sentences, no redundancies, and front-loads the core purpose and fallback. 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?

Given no output schema, the description outlines the expected return (segments, timestamps, language) and error behavior. It could be more detailed about the output structure, but is sufficient for a fetch operation.

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% with descriptions for video_id, lang, and save. The description does not add new meaning to parameters beyond what the schema provides, meeting the baseline.

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

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

Description clearly states the tool fetches existing official transcript with timestamps and language detection. It distinguishes from sibling transcribe_video by explicitly identifying it as a fallback when no captions exist.

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?

Description provides explicit guidance: use this tool for existing captions, and fall back to transcribe_video if a NO_CAPTIONS error occurs. Also mentions the call is free, aiding decision-making.

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 agent knows it's a read-only operation. Description adds behavioral context: does NOT include transcript (preventing false expectations), and labels it 'cheap, fast, free' for cost/speed. No contradictions.

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 with no wasted words. Front-loaded with the tool's main purpose and key return fields, then provides exclusion and efficiency notes. Perfectly sized.

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 single parameter and no output schema, description fully covers what the tool returns, what it excludes, and its cost profile (cheap, fast, free). No gaps for an agent to misinterpret.

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?

Input schema has 100% coverage with a clear description of the video_id parameter (accepts 11-char ID or full URL). Description does not add additional parameter 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?

Clearly states it fetches consolidated YouTube video metadata with specific fields listed (title, channel, duration, etc.). Distinguishes from sibling tools by explicitly stating it does not include transcript and redirects to fetch_transcript or transcribe_video.

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 says when to use this tool (for metadata) and when not to (for transcript). Names alternative siblings fetch_transcript and transcribe_video. Also notes it's cheap, fast, and free, guiding usage expectations.

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 readOnlyHint=true and destructiveHint=false. The description adds value by listing all possible status values ('queued', 'downloading', 'transcribing', 'finalizing', 'done', 'failed'), explaining that a full transcript with timestamps is included when status is 'done', and recommending a polling interval. It does not mention rate limits or idempotency, but overall it provides good behavioral transparency.

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 three sentences: first states purpose, second lists statuses, third gives polling interval and cost. No fluff, front-loaded with the key action. Each sentence earns its place.

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

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

For a simple polling tool with one parameter and no output schema, the description covers status outcomes, behavior when done, and polling interval. It lacks error handling details (e.g., what happens with invalid task_id), but overall it is sufficiently complete for an AI agent to use 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 coverage is 100% with the single parameter 'task_id' described as 'Task ID returned by transcribe_video.' The description does not add additional meaning beyond what the schema already provides. Baseline score 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 clearly states the tool's purpose: 'Poll the status of an ASR task created by transcribe_video.' It specifies the verb (poll), resource (ASR task), and links to the creating tool. This differentiates it from siblings like fetch_transcript (which retrieves final transcripts) and transcribe_video (which creates tasks).

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 explicit usage guidance: it is for polling status, recommends a polling interval of 3-5 seconds, and notes it is free (no credit consumption). It implicitly indicates when to use (after transcribe_video) but does not explicitly state when not to use or cite alternatives. The cost disclosure is an added benefit.

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; description adds no pagination and wrapper behavior but does not detail return limits or ordering. Adequate given annotation coverage.

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, front-loaded with the action, no wasted words.

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 simple 1-parameter read-only tool with no output schema, the description covers purpose, usage, and behavioral context sufficiently.

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?

Input schema has 100% description coverage for the single parameter; description adds no additional meaning beyond schema. Baseline score 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?

Description uses specific verb ('Get') and resource ('most recent videos from a YouTube channel'), clearly distinguishing it from sibling `list_channel_videos` by stating it's a convenience wrapper without pagination.

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 says 'convenience wrapper over list_channel_videos with no pagination' and suggests a typical query style, implying when to use. Does not explicitly state when not to use, but the context 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?

Annotations declare readOnlyHint=true, so the description adds value by mentioning the inline transcript and AI summary. This goes beyond the annotation to specify what the read operation yields.

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, front-loaded with the main action, and immediately followed by usage guidance. No wasted words.

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 no output schema, the description explains the return content (transcript and summary) and usage context. It lacks error or permission details but is sufficient for basic 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?

Input schema provides 100% coverage with descriptions for both parameters (id, locale). The description adds no extra parameter info beyond the schema, so baseline score 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 the tool reads a saved Library item, including its transcript and AI summary. It distinguishes from list_library by specifying it fetches full content.

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 says 'Use after list_library to fetch the full content,' providing clear usage context. It does not list exclusions or alternatives, but the guidance is direct.

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. The description adds behavioral context: returns up to 30 per page, uses a continuation token for pagination, and orders by publish date newest first. This goes beyond annotations without contradiction.

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 wasted words. Front-loaded with the core action and key details (ordering, pagination, page size, alternative). Very efficient.

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

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

Given no output schema, the description mentions the response includes up to 30 items and a continuation token. It covers purpose, usage, pagination, and alternatives. Lacks explicit mention of returned fields (e.g., video IDs, titles), but for a simple list tool this is adequate.

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% with detailed parameter descriptions. The tool description adds usage guidance: when to omit 'channel' (on subsequent pages using continuation). This provides extra context 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 clearly states the action ('List'), the resource ('all videos from a YouTube channel'), the ordering ('newest first'), and pagination. It explicitly differentiates from the sibling tool 'get_channel_latest_videos' by noting that tool is simpler for a few recent 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 description explicitly tells when not to use this tool ('for just the most recent handful, prefer get_channel_latest_videos') and implies when to use it (when you need all videos or pagination). This provides clear guidance on alternatives.

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 readOnlyHint=true and destructiveHint=false, indicating safe reading. The description adds behavioral details: returns recently saved items first, supports substring search and favorites filter. This complements the annotations without contradiction.

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: first states purpose and content type, second lists key features. It is front-loaded with the core action and avoids superfluous details, 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?

Given no output schema, the description explains ordering (recently saved first) and scope, but does not detail the structure of returned items beyond mentioning transcripts and summaries. It is reasonably complete for a list tool with well-documented parameters.

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 parameters. The description summarizes parameter behavior (substring search, favorites filter, pagination) but does not add significant new meaning beyond what the schema 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 description clearly states "List videos the user has saved to their Library" with specific verb (list) and resource (Library videos). It adds details like transcripts, summaries, and scoping, making it distinct from sibling tools such as list_channel_videos or search_youtube.

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

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

The description specifies the scope ("Scoped to the calling user's data only") and lists supported features (substring search, favorites filter, pagination). It implicitly tells when to use this tool (for user's own library) but does not explicitly contrast with alternatives or state when not to use it.

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

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

Description supplements annotations by disclosing pagination behavior, the order of returned videos, and that it works for public/unlisted playlists. This goes beyond the readOnlyHint and destructiveHint annotations, providing useful behavioral context.

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

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

Three short, front-loaded sentences each add unique value: listing operation, pagination, return info, and scope. No extraneous content. Highly efficient.

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

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

Given no output schema and moderate complexity, the description covers purpose, scope, and pagination adequately. It mentions returning 'video metadata and position' but is slightly vague on exact fields. Still sufficient for an AI to use effectively.

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 descriptions already cover both parameters (playlist and continuation) with full detail. The tool description adds no new information about parameter semantics beyond 'pagination' context, which is already implied by the schema. With 100% schema coverage, baseline is 3.

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 clearly states the tool lists videos in a YouTube playlist in order with pagination, and specifies it returns video metadata and position. The verb 'list' and resource 'videos in a YouTube playlist' are explicit, and it distinguishes itself from siblings like search_youtube and 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 description indicates when to use the tool: for any public or unlisted playlist identified by URL/ID. It implies that this is the relevant tool for playlist content, but does not explicitly discuss when not to use it or compare against alternatives.

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 readOnlyHint=true, so the description doesn't need to restate safety. It adds value by detailing what the tool returns (channel ID, name, stats). No contradictions.

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 efficient sentences: first explains functionality and output, second gives usage guidance. No wasted words.

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 simple tool with one parameter and no output schema, the description fully covers purpose, output, and usage context. Minor omissions (e.g., error handling) are acceptable given the tool's simplicity.

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 single parameter is fully described in the schema with examples. The tool description adds no additional meaning beyond the schema, 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 the tool resolves various input forms into canonical channel info, listing specific output fields. It distinguishes from sibling tools by focusing on resolution of handles/URLs to IDs.

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 instructs 'Call this first when you only have a handle or URL but need a channel ID for the other channel-scoped tools,' providing clear when-to-use and linking to alternatives.

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 annotations (idempotentHint=true, readOnlyHint=false), the description adds meaningful behavioral details: idempotent updates existing entry, effect of each mode (bookmarks, flips has_asr, uploads summary), and that 'text' is required for summary 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 concise sentences that front-load the main action, then elaborate modes and idempotency. Every sentence adds necessary 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?

The description covers modes, idempotency, and prerequisites for 'asr'. It lacks information about the response/return value (no output schema), but otherwise is adequate for a save operation.

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 already provides 100% coverage with descriptions. The description adds value by explaining the `kind` values and their usage, and clarifying that `text` is required for 'summary'/'both' and giving guidance on `format`.

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 'Save a video to the authenticated user's Library' with specific verb and resource. It distinguishes three modes via `kind`, making the purpose distinct from sibling tools like fetch_transcript or list_library.

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 when to use each mode, e.g., 'asr' after a transcribe_video -> fetch_transcript flow, and mentions idempotent behavior. It does not explicitly exclude alternatives or state when not to use, but provides clear context.

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 disclose read-only behavior (readOnlyHint: true) and non-destructive nature. The description adds the behavioral detail of restricting results to a single channel, but does not provide further behavioral context (e.g., rate limits, pagination). Since annotations cover safety, a score of 3 is appropriate.

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 extremely concise—two sentences that front-load the purpose and usage context. Every sentence adds value: the first states what it does, the second gives a practical example and workflow hint. No wasted words.

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 simplicity (3 scalar parameters, no output schema) and rich annotations (readOnly, idempotent, openWorld), the description is sufficiently complete. It mentions a legitimate use case and integration with resolve_channel, which is helpful. Slightly more detail on return format or error conditions would elevate it further, but it's already strong.

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 covers all three parameters (channel, q, limit) with clear descriptions, achieving 100% coverage. The description adds no additional meaning beyond summarizing the channel restriction, so it meets the baseline expectation.

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 for specific videos within a single YouTube channel, using a specific verb ('Search') and resource ('videos within a single YouTube channel'). It distinguishes from sibling tools like search_youtube by emphasizing channel restriction and suggesting a use case (e.g., 'find Karpathy's video about backpropagation').

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 explicit context: 'Use after resolve_channel if starting from a handle' and 'Restricts results to the given channel,' which guides the agent on when to use it. While it doesn't explicitly state alternatives or when not to use, the context is clear enough for correct selection.

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 key behavioral detail (returns up to 50 results with metadata) beyond annotations which already indicate read-only and non-destructive nature. No contradictions.

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 focused sentences: first states purpose and constraints, second gives usage guidance. No wasted words.

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 annotations (readOnlyHint true, etc.) and thorough schema, the description is complete. It covers result limits, metadata, and differentiates from sibling.

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 covers all 3 parameters with descriptions; the tool description does not add significant new meaning beyond the schema, so baseline score 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?

Clearly states 'Search YouTube globally' with specific resource types (videos, channels, playlists). Distinguishes from sibling search_channel_videos by noting global vs within-channel context.

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 advises when to use (topic-based discovery without channel) and when to use alternative (search_channel_videos for within a known channel).

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?

Discloses async behavior (returns immediately with task_id and estimated_wait_seconds), background processing, need to poll with get_asr_task, and cost of 5 credits debited on success. These go beyond annotations which only provide 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, each earning its place. First sentence states action and nature, second sentence tells what returns and follow-up, third sentence gives condition and cost. No waste, front-loaded with key 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?

Covers essential aspects: action, async nature, return values, next steps, usage condition, and cost. Missing some edge cases like error handling or timeouts, but overall sufficient for a tool with annotations and schema.

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?

Input schema has 100% coverage with detailed descriptions for both parameters. The tool description adds no new parameter meaning beyond what the schema already provides, so baseline score 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?

Clearly states 'Start an asynchronous AI ASR (Whisper) transcription of a YouTube video.' Specifies verb, resource, and async nature. Distinguishes from siblings like fetch_transcript and get_asr_task.

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 says 'Use this when fetch_transcript returned NO_CAPTIONS or when the video has no captions.' Provides context on when to use versus alternatives, and instructs to poll with get_asr_task.

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