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

Annotations already declare readOnly/idempotent/non-destructive, so the bar is lower; the description still adds real value by explaining the return value (a per-video multiple, with a worked 3.2x example) and the Shorts-flagging behavior. It omits quota/cost implications hinted at by the 'account' parameter.

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

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

Four sentences, front-loaded with the core mechanism and differentiator. Each sentence earns its place, though the '3.2x means three times' phrasing is mildly redundant with 'multiple per video'.

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

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

With no output schema, the description correctly explains the return format and its meaning, plus the Shorts comparability caveat. Annotations cover the safety profile, so nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents channel, limit, and account. The description adds no parameter-level detail (e.g. accepted channel formats), so it sits at 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?

States a precise mechanism (scoring recent videos against the channel's OWN median views) rather than a generic verb. The 'rather than which are simply oldest' clause and the 'multiple per video' detail make the tool's purpose self-distinguishing from raw analytics siblings even without naming them.

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

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

Gives a clear workflow cue ('Use this before modelling anyone's content') and a caveat about Shorts. However, it never names an alternative tool (e.g. get_channel_analytics) or states when NOT to use it, so an agent must infer the 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 already mark destructiveHint=true, and the description adds concrete consequences: YouTube removes the video immediately, there is no trash or undo, and views, comments, and URL are lost. It also surfaces the confirm guardrail. 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?

Three short sentences front-load the action, then provide consequences and the confirmation requirement. Every clause earns its place; there is no filler or repeated 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 a destructive tool with strong annotations and no output schema, the description covers the key invocation facts: target video/channel, irreversibility, and required confirm flag. It could mention account ambiguity when multiple channels are connected, but that detail is already in the 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?

Schema already documents account and confirm; the description reinforces confirm ('Needs confirm: true') but adds little beyond it. video_id remains undocumented in the schema, though 'delete a video' makes its role self-evident. With 67% schema coverage, the description only partially compensates.

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 lead sentence uses a specific verb ('delete'), resource ('video'), and scope ('connected channel'), and 'permanently' plus 'no trash, no undo' clearly distinguishes this destructive action from siblings like update_video or get_video. The purpose is unambiguous even without naming alternatives.

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 frames when to use the tool: when a video must be permanently removed from a connected channel. It does not explicitly name alternatives such as update_video or state when not to delete, so routing guidance is contextual rather than fully explicit.

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

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

Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable behavioral context beyond annotations by disclosing YouTube-specific rounding of subscriber counts above 1,000 and the `hidden` value when owners hide counts.

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-load the lookup action and identifier formats, then add return fields and an important data caveat. Every sentence earns its place with no redundancy or 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 simple read-only lookup with complete schema parameter descriptions, the description fully covers what the tool returns and an important edge case. No output schema exists, but the return fields are enumerated, so the agent has enough to invoke and interpret results.

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 both parameters. The description reinforces the `channel` parameter's accepted forms but does not add substantial new 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 ('look up') with a clear resource ('any channel') and enumerates the accepted identifier formats and returned fields. It differentiates from siblings like get_my_channel by emphasizing 'any channel.'

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 indicates this is for looking up channels by handle, id, or URL, which implies general channel lookup. It does not explicitly contrast with sibling tools like analyze_channel or get_my_channel, but the 'any channel' wording provides clear context without exclusions.

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

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

Annotations already establish read-only/idempotent/non-destructive behavior. The description adds meaningful traits not in structured metadata: OAuth ownership requirement, unavailability via API key, and roughly two-day data lag. 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?

Three short sentences, each carrying distinct value: output scope, auth constraint, and latency caveat. No filler and the most useful identifying details 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?

Covers the critical operational constraints (OAuth, ownership, lag) and the returned metrics, with schema covering parameter usage. Lacks an explicit return-shape/pagination note, and there is no output schema to fill that gap, so it is strong but not fully 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 88%, so the schema already documents the parameters and the description does not need to repeat them. The description adds no new parameter-level detail beyond implying metrics/dimensions; baseline 3 is appropriate.

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

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

States a precise resource ('a connected channel') and the exact analytics fields it returns (watch time, average view duration, retention, traffic sources, subscriber change). The ownership qualifier ('exists for no one else's channel') distinguishes it from channel lookup/sibling tools without opening schemas.

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

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

Gives clear invocation context: requires OAuth on the owning channel, cannot be used with an API key, and only works for the owner's own channel. It does not explicitly name sibling alternatives (e.g., analyze_channel), so it falls a point short of full 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, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds meaningful behavioral details: it returns specific channel metadata and reads the exact subscriber count, and it warns that omitting the account parameter when multiple channels are connected causes the call to fail and list choices. 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?

The description is two sentences, with the core purpose and return fields front-loaded, followed by the key differentiator. No filler or redundant repetition of the title or schema. Every sentence contributes essential information.

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

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

For a simple read-only tool with one optional parameter and no output schema, the description provides sufficient information: it lists the returned fields, the exactness of the subscriber count, and the account behavior. Given the annotations cover safety and idempotency, nothing critical is missing for an agent to call 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%, so the parameter 'account' is already documented with its purpose and behavior. The description adds extra value by explicitly noting the failure mode when omitted and the selection behavior, which is not fully captured in the schema. This enhances the agent's understanding 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 states a specific verb ('get') and resource ('my channel'), enumerates the exact fields returned (subscribers, total views, video count, uploads playlist id), and explicitly contrasts with get_channel by highlighting the exact vs. rounded subscriber count. This leaves no ambiguity about what the tool does.

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 a clear differentiator from get_channel ('reads the exact subscriber count rather than YouTube's rounded public figure'), which implicitly tells an agent when to prefer this tool. However, it does not mention alternatives like get_channel_analytics or list_accounts, and does not explicitly state when not to use it, though the parameter description adds context about the account requirement.

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

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

Annotations already cover readOnly and idempotent hints, so the bar is lower. The description adds valuable context: no-auth, no-quota operation, default prose vs timestamped output, and a clear failure case ('Videos with captions disabled have no transcript and nothing can recover one'). This goes beyond the structured annotations and gives the agent a concrete model of behavior.

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 four short sentences, each earning its place. It front-loads the core purpose, then gives the auth-free context, then the output options, then the limitation. No wasted words 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 simplicity of the tool and full schema coverage, the description provides all essential context: what it does, when to use it, what to expect as output (prose or timestamped lines), and the failure condition. No output schema exists, but the description partially covers return format. There are no missing critical details for an agent to call this correctly.

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

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

Schema coverage is 100%, so all parameters are fully documented in the schema. The description does not add additional meaning to any parameter beyond what the schema already provides (e.g., timestamps format, language defaults). It mentions prose vs timestamps but that is already captured in the schema description. No extra value is added, 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 begins with 'Read the transcript of ANY public YouTube video', a specific verb and resource. It explicitly distinguishes itself from account-specific tools by adding 'not just your own', and clarifies the output modes (prose vs timestamped lines). This clearly separates it from siblings like get_my_videos or search_transcript.

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

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

It states when to use: for any public video without needing an account or API key, which differentiates it from tools that require authentication. It also notes the captions-disabled limitation, implying when not to use. However, it does not explicitly name sibling tools like search_transcript or get_transcripts, so alternatives are implied rather than called 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 declare readOnly, idempotent, non-destructive, and open-world, so safety is covered. The description adds genuinely useful batch semantics — a captionless video is reported in place instead of failing the whole call — which is exactly the partial-failure behavior an agent needs before batching. It omits any language-fallback behavior, hence not a 5.

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

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

Three tight sentences, front-loaded with the capacity and scope, then the failure semantics, then the use cases. No sentence is redundant with the others.

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 batch fetch with no output schema, the description covers capacity, batch-failure behavior, and intended uses. The remaining gap is the language parameter — no default, no fallback when a requested language is unavailable — which an agent would need to call 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 67%, which already documents the videos item format and the maxItems cap plus the truncation intent for max_chars_each. The description only restates the 20-video limit and the 'openings' use case; the language parameter is undocumented in both schema and description, leaving real ambiguity.

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 (fetch), resource (transcripts), and batch scope (up to 20 videos in one call). The batch framing and the 20-item cap clearly separate it from the singular get_transcript sibling without needing to name it.

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

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

Gives two concrete use cases: comparing video openings and building a corpus before analysis. However, it never states when not to use it (e.g., a single video should go to get_transcript) and names no alternative sibling, so the routing guidance is directional but not exhaustive.

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 readOnly, idempotent, and non-destructive behavior. The description adds the important behavioral detail that tags are only visible to the owning channel, which is beyond what annotations provide. This gives agents a clear expectation about field availability.

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 list the returned fields and a caveat. No fluff, no repetition, and the core purpose is front-loaded. Every word 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 retrieval tool, the description covers the key aspects: what is returned, and a special ownership caveat. There is no output schema, but the field list substitutes. It lacks error handling or response format, but that is not critical given the simplicity 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?

Both parameters (video and account) have descriptions in the schema, with 100% schema coverage. The tool description does not add any extra meaning beyond the schema. Since the schema already documents the parameters, the description's contribution is neutral.

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 returns full detail for a single video and enumerates the specific fields (title, description, channel, views, likes, comments, duration, tags). This differentiates it from sibling tools like search_videos (multiple videos) and get_transcript (transcript only). The verb 'get' and resource 'video' are explicit.

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

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

The description implies this is for looking up details of one video, but it does not explicitly state when to choose this over alternatives like get_transcript or get_channel. No 'when not to use' or exclusion conditions are given, though the tags caveat hints at ownership considerations.

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 readOnly, idempotent, and non-destructive hints, so the safety profile is covered. The description adds workflow context (call first, pass result as account) and clarifies that all connected channels are returned, which is useful 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?

Two sentences, both purposeful and well-ordered. The main behavior is stated first, followed by a practical usage note. 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?

For a zero-parameter, read-only tool with rich annotations, the description fully covers what the agent needs: what to call, when to call it, and what to do with the result. No output schema is present, but the returned names are self-explanatory.

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 are no semantics to clarify beyond the schema. The baseline for 0 params is 4, and the description add no param information because none is needed.

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 states a specific verb ('List') and resource ('every YouTube channel connected to this server'), clearly identifying the tool's function. It also distinguishes itself from siblings by positioning it as the entry point that returns account names for use by other 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?

The description gives clear usage context: call first when more than one channel may be connected, then use the returned name as the `account` parameter elsewhere. It does not explicitly state when not to call it, but the condition is specific enough for an agent to decide.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context beyond that: comment text is untrusted third-party content that must be summarized and reasoned about but never obeyed. It still omits pagination behavior and how the limit interacts with the ordering.

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, with the operation front-loaded and the safety constraint immediately after. Every clause carries weight.

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

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

For a read-only listing tool with full annotation coverage and no output schema, the description covers what the tool does, the ordering axis, and the prompt-injection risk. The remaining gaps (limit semantics, pagination/return shape) are minor but real.

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 only 25% (only 'account' is documented, and thoroughly so). The description adds a mapping for the 'order' enum (time/relevance -> newest/most relevant), which is useful, but 'limit' and 'video_id' get no semantics at all beyond their names, and the max of 100 is never surfaced.

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

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

States a specific verb+resource ('Read comment threads on a video') plus a scope/ordering qualifier. It does not name the write counterpart reply_to_comment, so sibling differentiation is left to inference, but the action 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?

Usage is implied by the resource rather than stated: no when-to-use conditions, no mention of prerequisites such as which channel/account is needed, and no comparison to reply_to_comment or search tools. The ordering hint ('newest or most relevant first') is the only selection 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 establish the read-only/idempotent safety profile. The description adds behavioral details beyond those annotations: results are ordered newest-first, include views and likes, and include private/unlisted videos. It does not describe pagination or account-choice failure behavior, but those are partly covered by the parameter 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?

One dense sentence with no filler: the verb/resource appears first, followed by ordering, metrics, and the important visibility scope. Every clause pulls weight.

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 two-parameter, read-only list operation with a fully documented schema, the description is nearly complete. It supplies the key selection/sorting/visibility facts; only the lack of an output schema leaves the exact return shape slightly under-specified, though views and likes are named.

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's 'connected channel' phrase reinforces the account parameter, but it adds no meaning beyond what the schema already states for 'limit' and 'account'.

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 ('List') and a clear resource ('videos on a connected channel'), then sharpens scope with ordering ('newest first') and the included metric fields ('views and likes'). The visibility note ('private and unlisted') distinguishes it from public search-oriented siblings such as search_videos without needing to name them.

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 for use: it targets a connected channel and can surface private/unlisted content that public tools cannot. It stops short of explicitly naming an alternative or stating a when-not-to-use condition, so it misses the top bar.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds meaningful behavior beyond annotations: it discloses the output dimension (human vs. auto-generated) and provides the practical note that human captions are more accurate.

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 with no redundancy. The first sentence states the core purpose and output; the second provides actionable guidance. Every sentence earns its place.

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

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

For a simple one-parameter read-only tool, the description is complete. It explains what will be returned (caption languages plus human/auto status), when to call it, and the annotations cover side effects and idempotency.

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 fully describes the single 'video' parameter, so the description does not need to add parameter detail. The description reinforces that the parameter identifies a video, but the schema already carries the semantic weight.

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 lists every caption language on a video and whether each is human-written or auto-generated. It distinguishes itself from sibling tools like get_transcript by focusing on language and generation type rather than transcript 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 tells the agent to call this before get_transcript when the video may not be in English. This gives clear context for when the tool is appropriate, though it stops short of enumerating exclusions or alternative tools beyond get_transcript.

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 annotations (destructiveHint true, readOnlyHint false), the description discloses meaningful behavioral consequences: the reply is immediately visible, notifies the replied-to person, and that notification is not undone by a later delete. This is exactly the kind of side-effect transparency that helps an agent avoid harmful calls.

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 tight sentences with no filler. It front-loads the core purpose and then adds the high-value behavioral warnings. Every clause contributes useful 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?

Given no output schema, the description could mention what is returned after a successful reply, but it does cover the operation's side effects, the confirm requirement, the public nature, and the account context. The main gap is the absence of any note about the success/return payload.

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 75%, so most parameters already have descriptions. The description reinforces 'confirm' and the connected-channel account concept but adds little beyond the schema. The one uncovered parameter, 'text', is simple enough given minLength, but the description does not compensate further.

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: 'Post a public reply to a comment thread as the connected channel.' It clearly identifies both the resource (comment thread) and the operation (posting a reply), and it is distinct from all sibling tools, none of which post comments.

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

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

The description implies the tool is for replying publicly to a comment as the connected channel, but it does not explicitly say when to prefer it over alternatives or when not to use it. It does include an important precondition ('Needs confirm: true') and warns about side effects, but it stops short of clear usage-rule 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 cover read-only/idempotent safety. The description adds useful behavioral detail beyond annotations: it returns per-result timestamps as clickable links to the exact second. It does not mention edge cases like missing transcripts or multiple language matches, so not a 5.

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

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

Two sentences, no filler; the core behavior is front-loaded and the usage note follows. Every clause earns its place.

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

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

The description plus schema and annotations give enough to call correctly: required inputs are clear, output shape is stated (timestamp links), and safety is covered by annotations. Without an output schema, slightly more detail on result behavior would be ideal, but nothing critical 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 covers 3 of 4 parameters (75%) with descriptions; the description mainly reinforces query and video concepts ('phrase', 'video') without adding syntax or defaults. The language parameter is left undocumented, but with high 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 opens with a specific verb and resource ('Find every place a phrase is said in a video') and states the concrete deliverable ('timestamps, each as a link that jumps to that second'). This makes it easy to distinguish from get_transcript and search_videos without inspecting schemas.

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 explicitly names the alternative class ('pulling a whole transcript') and the condition that selects this tool ('when you only need to locate something'). This is a clear when-to-use statement with an implied when-not-to-use.

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

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

Annotations already establish readOnly, idempotent, and non-destructive behavior. The description adds genuinely useful behavioral context beyond those: the separate 100-calls-per-day quota versus the 10,000-unit shared pool, and the fact that results are enriched with stats. There is no contradiction with 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?

Two dense sentences accomplish everything: the first states the purpose and value-add, the second conveys quota and usage discipline. There is no filler, and the most decision-relevant 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?

For an 8-parameter search tool, the description covers the core invocation context: what the results include, why to use it, and a critical quota constraint. The schema covers parameter formats like RFC 3339 and max_results defaults. A minor gap is that there is no output schema and the description only sketches the return shape (view counts, likes, duration), but that is enough for most agent decisions.

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 description does not explain any of the 8 parameters; the schema carries most of that burden, with descriptions for account, min_views, channel_id, max_results, and published_after, and an enum for order. With schema coverage at 63%, the description adds no extra parameter-level meaning, so a mid-range 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 opens with a specific verb and resource — 'Search YouTube and get results WITH view counts, likes and duration attached' — which clearly states the action and the unique value add. It also distinguishes itself from a plain API search and from siblings like search_transcript by framing the result as performance-oriented rather than just match-oriented.

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: 'use this whenever you need to judge whether a result actually performed rather than just matched.' It also advises against casual use with 'use it deliberately rather than as a first guess.' However, it does not name a specific alternative tool to use instead, so it stops short of fully explicit 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?

The description goes well beyond the annotations by explaining that only supplied fields change, that the API replaces the whole snippet and would blank omitted fields, and that the tool preserves unspecified fields by reading them back first. It also discloses that the operation is reversible and therefore not confirm-gated. This is substantive behavioral context that the readOnlyHint/destructiveHint annotations do not provide.

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, each earning its place: the purpose, the critical partial-update behavior, and the reversibility/no-confirm implication. Key information is front-loaded, and there is no filler or 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 mutation tool with no output schema and six parameters, the description covers the most operationally critical facts: which fields change, how omitted fields are preserved, and reversibility. It does not mention the conditional account requirement or failure modes, but the schema's account description already covers the account disambiguation failure, and no nested/output schema exists to overcomplicate the picture.

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 only 17%, with only 'account' documented in the schema. The description adds meaning by listing the changeable fields (title, description, tags, privacy) and by explaining the patch-like behavior across fields. However, it does not elaborate on individual parameter semantics, units, constraints, or the conditional importance of the 'account' parameter, leaving the low-coverage schema to carry significant weight.

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 an explicit verb and resource: 'Change a video's title, description, tags or privacy.' It names the exact fields affected, making the tool's purpose unmistakable and clearly separating it from read-focused siblings like get_video and destructive delete_video. No ambiguity remains about what this tool does.

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

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

The description implies when to use the tool: whenever a video's metadata needs updating. It provides valuable context about partial-field updates, but it never explicitly contrasts this tool with alternatives (e.g., 'use get_video to inspect before updating') or states when not to use it. The usage context is clear, but exclusionary guidance is absent.

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