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

Annotations already cover read-only, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond that: it explains the output is a multiple per video, clarifies the meaning of the multiple (3.2x), and flags how shorts are treated. This goes beyond what annotations alone 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?

The description is two sentences, with the core concept (scoring against own median) front-loaded. Every sentence adds distinct value: the first explains the method and purpose, the second explains the output and the shorts caveat. No filler 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 complexity relative to siblings, the description fully covers the key aspects: the metric, the meaning of the result, the use case, and the caveat about shorts. There is no output schema, so explaining the return format is essential and done clearly. 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 description coverage is 100%, so all three parameters are documented in the schema itself. The description does not add extra detail about parameters, but the baseline of 3 applies because the schema carries the full load. No compensation 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?

The description states a specific verb ('Score') and resource (a channel's recent videos) and defines the unique metric (relative to the channel's own median views). This clearly distinguishes it from sibling tools like get_channel_analytics, which would report absolute metrics.

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 before modelling anyone's content,' giving a clear recommended context. It also warns about shorts being non-comparable, an important behavioral caveat. This provides actionable guidance on when and how to apply the tool.

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

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

Annotations 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 establish readOnly, idempotent, non-destructive behavior. The description adds a meaningful behavioral detail: videos without captions are reported in place rather than failing the whole batch. This is valuable operational context beyond 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 sentences with no filler. The core function and batch limit are front-loaded, followed by the most important edge-case behavior and a brief usage note. 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?

The description covers the main operational concern (missing captions) and the tool's purpose, and the schema handles most parameters. It does not explain the return format or language behavior, which would matter more since there is no output schema, but the core usage is still clear.

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%, with descriptions for videos and max_chars_each but not for language. The description restates the batch limit but does not clarify the language parameter or add meaning beyond the schema. It does not fully compensate for the undocumented parameter.

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 ('Fetch transcripts') and the resource scope ('up to 20 videos in one call'). It distinguishes itself from the singular get_transcript sibling by emphasizing batch retrieval, so an agent knows exactly when this tool applies.

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 concrete use cases: compare openings across videos or build a corpus for analysis. It implies batch use and contrasts with a single-transcript tool, though it does not explicitly name get_transcript or state when not to use this tool.

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

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

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 mark this as read-only and idempotent. The description adds valuable security context that comments may contain untrusted instructions, which is important behavioral information beyond the structured 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 tight sentences with no filler. The primary action is front-loaded, and the security warning earns its place because it carries behavioral guidance the schema cannot express.

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?

Adequate for a simple read tool, but with no output schema the description leaves return format and pagination behavior unspecified. The account ambiguity is only handled via the schema, and limit semantics are not explained beyond the numeric bounds.

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 only 25%, so the description must compensate. It clarifies order semantics with 'newest or most relevant first,' but does not explain limit or video_id formats, and account is only documented in 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 ('Read') and resource ('comment threads on a video') with sorting semantics. Clearly distinguishes itself from sibling write tools like reply_to_comment.

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?

Implies usage context (when you need to read comments on a video), but provides no explicit alternatives or when-not-to-use guidance. The distinction from reply_to_comment is not stated, though it is easy to infer.

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.