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

Annotations already declare a non-read-only, non-idempotent, non-destructive, open-world mutation, so the safety profile is covered. The description adds the position semantics (0 = first), which is genuine behavioral context, but it does not state what happens on duplicate adds, whether the playlist must already exist, or the effect of create_if_missing.

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 short sentences with no filler, and the core action plus the identifying rule are front-loaded. The parenthetical is a compact and effective clarification.

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, annotations covering the mutation profile, and partial schema coverage, the description is adequate but leaves out duplicate handling, existence requirements, and return information.

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 60%, so the schema documents playlist, channel, and create_if_missing itself. The description restates the playlist identifier forms and adds meaning for 'position' that the schema does not convey beyond minimum 0, which is useful; video_id remains undocumented in both places.

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

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

States a specific verb and resource ('Add a video to a playlist') and clarifies the two accepted playlist identifiers. The verb cleanly separates it from remove_from_playlist and move_in_playlist, though it does not name those siblings explicitly.

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

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

Provides identification hints ('by playlist id or exact title') but no explicit when-to-use guidance against alternatives like create_playlist or move_in_playlist, and does not mention prerequisites such as channel selection or quota.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered; the description adds genuine value by disclosing the returned content, including the non-obvious diagnostic detail of channel sign-in health and known project limitations. It does not state whether the call is cheap, cached, or whether quota figures are live, which keeps it out of 5 territory.

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 front-loaded sentence enumerating the payload, followed by a short imperative for when to call it. No filler, no restatement of the title.

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

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

With no output schema and no parameters, the description must carry the return-value burden, and it does so by listing each field category an agent would need to decide its next step. Nothing required to call or interpret this tool is missing.

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

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

The tool takes zero parameters, so the baseline is 4. There is nothing parameter-level for the description to clarify, and it correctly spends no words on arguments.

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?

Names a specific verb ("Show") and enumerates exactly what state is reported: OAuth configuration, connected channels and their sign-in health, default channel, today's quota use, and project limitations. This is distinguishable from narrower siblings like quota_status, list_channels, or get_channel, which each cover only one slice of what this aggregates.

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?

"Call this first in a new conversation" gives a concrete trigger condition, which is exactly the orientation guidance an agent needs before touching connect_channel or upload tools. It lacks explicit when-not conditions (e.g. "don't re-call mid-session") and doesn't name alternatives, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint=false and destructiveHint=false, and the description usefully corroborates the non-destructive profile by noting the job can be resumed later. Beyond that it says nothing about the state of the upload after cancellation (bytes discarded vs. retained), what happens if the job is already complete, or whether an error or idempotent response is returned.

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 short sentences with zero filler, and the precondition is front-loaded before the pointer to the alternative tool. Nothing could be removed without losing 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?

This is a simple one-parameter tool with no output schema, so the bar is low, and the description covers purpose and the resume path adequately. It is still incomplete on identifier provenance and on error behavior for already-finished jobs, both of which an agent would need to call it reliably.

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

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

There is a single parameter, job_id, with 0% schema description coverage, and the description never mentions it or explains where an agent obtains a job id. For a required identifier whose provenance (list_uploads? upload_video? get_upload_status?) matters for correct invocation, this is a meaningful omission.

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 gives a specific verb and resource ("Stop an upload job") plus a state precondition ("that has not finished"), which distinguishes it from a general delete or status tool. It names the resume_upload sibling, though it doesn't distinguish itself from the other upload-related siblings such as list_uploads or get_upload_status.

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 the condition that selects this tool (an unfinished upload job) and points to resume_upload for the reverse operation, giving an explicit alternative. It does not say what to do if the job has already finished or failed, which is a residual gap but not a blocking one.

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' mutation and open-world signals, the description discloses the local browser side effect, return of a sign-in link, required user interaction, support for brand accounts, and bounded waiting behavior. These details substantially clarify what invoking the tool will do and what the user must do next.

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

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

Three compact sentences front-load the purpose and then cover the interaction and timing behavior. Every phrase adds useful operational information without repetition or unnecessary background.

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 definition supplies enough information for an agent to initiate the connection flow correctly, including the browser, link, user choices, and wait limit. With no output schema, it could be more complete by describing what is returned on success versus timeout and how to proceed if the user does not finish signing in.

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 explains the waiting behavior associated with wait_seconds and describes the default browser-opening flow relevant to open_browser, whose schema entry lacks a description. It does not explicitly explain that open_browser=false provides a link-only flow or clarify the practical effect of wait_seconds=0.

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 opening sentence clearly identifies the action and resource: starting Google sign-in to connect or reconnect a YouTube channel. The account and channel selection details make its role easy to understand, although it does not explicitly contrast itself with siblings such as auth_status, set_default_channel, or disconnect_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?

It establishes that the tool is for both initial connection and reconnection, and that the user must participate by choosing a Google account and channel. It does not explain when reconnection is necessary or direct the agent to auth_status for checking an existing connection, but the intended usage context is clear.

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

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

Annotations already declare this is a non-read-only, non-idempotent, non-destructive, open-world write, so the safety profile is known. Beyond that, the description says nothing useful: it doesn't explain behavior on duplicate titles, what permissions are needed, which channel is targeted by default, or whether the playlist is immediately visible. For a mutation tool this is a notable gap.

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 single sentence is front-loaded and free of wasted words, but it is under-specified rather than concise. The brevity comes at the cost of missing information an agent needs.

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?

This is a four-parameter mutation tool with no output schema and only 25% schema description coverage, so the description should carry significant weight. It provides none of the missing context – no return information, no default-channel semantics, no privacy behavior, and no usage constraints.

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 the channel parameter carries a description. The description adds no meaning for title, privacy, or description parameters, so it fails to compensate for the undocumented parameters in the schema (e.g., privacy defaulting to private, title length limits).

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

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

The description states a specific verb and resource ("Create a new playlist") and adds a scope qualifier ("on the channel"), so the basic action is unambiguous. However, it largely restates the tool name and title without differentiating it from siblings such as add_to_playlist (which adds items) or update_playlist (which modifies existing ones).

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

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

There is no guidance on when to use this tool versus alternatives like add_to_playlist or update_playlist, and no prerequisites such as required authentication or channel connection state. The agent must infer usage entirely from the name.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds the meaningful operational context that user confirmation is required, which is not derivable from the annotations. It stops short of describing what happens to the caption data or the response after deletion.

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 short sentences with no filler; the operation and the id source come first, and the confirmation constraint follows. Every clause carries information the agent needs.

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, open-world tool with no output schema, the description covers the key risks: the id source and the confirmation gate. Minor gaps remain around post-deletion effects and error behaviour, but nothing critical to correct invocation is missing.

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

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

Schema coverage is 67%, and the undocumented parameter is caption_id; the description compensates by directing the agent to list_captions for valid ids. The confirmation requirement reinforces the confirmation_token semantics, though the channel parameter's default behaviour is left entirely to 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?

Specific verb + resource ("Delete an uploaded caption track") that clearly separates it from list_captions, download_captions and upload_captions. It does not explicitly state the inverse operation or scope limits, but an agent can identify the operation without opening the schema.

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?

Points to list_captions as the source of caption ids and states the prerequisite that the user must confirm before deleting. No explicit when-not or alternative path is given, but the context needed to call it is clear.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and openWorldHint=true, so safety framing is covered. The description adds genuinely new behavior: the own-comment restriction and the user-confirmation requirement that gates execution. It stops short of saying what error or no-op occurs when the target is not the channel's own comment.

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 short sentences with zero filler. The scope constraint is front-loaded and the redirect to the sibling plus the confirmation caveat follow in the order an agent needs them.

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 3-parameter destructive tool with rich annotations and no output schema, the description covers scope, the alternative path and the confirmation gate. Minor gaps remain: whether deleting a parent comment also removes its replies, and what happens when the confirmation_token is missing or stale.

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%: the channel and confirmation_token parameters are already documented in the schema, including the 'identical arguments' token rule. comment_id has no schema description, and the description only implicitly constrains it to the channel's own comment or reply rather than adding format or cascade details.

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?

Specific verb plus resource ('Delete a comment or reply') with an explicit scope restriction: only comments the channel itself wrote. It also names the sibling tool that handles the other case, so an agent can distinguish delete_comment from moderate_comments immediately.

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 when-to-use rule (own comments) and an explicit alternative for the excluded case (other people's comments go to moderate_comments). It also flags the prerequisite that the user must confirm before the call succeeds.

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 destructiveHint=true, idempotentHint=true and openWorldHint=true, so the safety profile is covered. The description adds genuinely non-obvious context beyond that: the playlist's videos survive the deletion, and user approval is required. It stops short of saying whether the playlist itself is recoverable or what the response contains.

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 short sentences with no waste. The destructive effect is stated first and the important non-obvious caveat (videos preserved) and precondition follow immediately.

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 three-parameter destructive tool with full schema coverage and no output schema, the essentials are present: what is destroyed, what is not, and that user approval is required. Only minor items are missing, such as what the tool returns and whether the deletion is reversible.

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 channel, playlist and confirmation_token are already documented in the schema, including the rule that the token must come from a prior call with identical arguments. The description adds only the general confirmation expectation, no format or matching guidance beyond the schema. Baseline 3 applies.

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

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

The description names a specific verb (delete) and resource (playlist), and immediately clarifies the collateral-effect boundary: the videos inside are not deleted. That distinguishes it from delete_video and remove_from_playlist well enough, though it never names a sibling or states what a playlist deletion affects channel-wide.

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?

"Needs the user's confirmation" gives an explicit precondition for invocation, which is exactly the kind of when-to-use rule an agent needs for a destructive operation. It does not spell out the two-step flow (first call returns confirmation_token, second call with identical arguments) or say when a caller should prefer remove_from_playlist instead.

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 destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered structurally. The description adds nothing beyond that: it doesn't say whether the file is removed from disk permanently or moved to trash, nor what happens when the name does not exist.

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?

A single sentence with no filler and the verb front-loaded, so it is structurally clean. However it is terse to the point of under-specification rather than genuinely efficient, since one more clause on irreversibility or name format would have earned 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 destructive, single-parameter operation with no output schema and zero parameter documentation, the description should tell the agent how to obtain a valid name and what the effect of deletion is. Neither is present, leaving the agent reliant on annotations alone to understand the consequences.

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 0% and the single 'name' parameter is typed only as a bare string. The description offers no clarification on whether this is a template name, an ID, whether it is case-sensitive, and whether the file extension must be included — a real gap for a destructive call where a wrong value causes collateral damage.

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 ('Delete') and resource ('saved template file'), which distinguishes it from the other delete_* siblings that target playlists, videos, captions, and comments. It does not explicitly reference a sibling, but the noun is unambiguous enough for correct selection.

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?

No when-to-use guidance, no mention of irreversibility, and no pointer to list_templates for discovering valid names before deleting. The agent must infer that this is a permanent removal rather than an un-save or archive.

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 flag destructiveHint and idempotentHint, but the description adds the critical behavioral facts: the deletion is permanent, irreversible, and gated on user confirmation. It does not spell out the two-call confirmation_token handshake itself, leaving that to the schema.

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

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

Three short sentences, zero filler, with the destructive consequence and the confirmation requirement front-loaded before any call is attempted.

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 single-resource tool with annotations covering the safety profile and a schema covering the confirmation token flow, this is nearly complete. Minor residual gap: no mention of what happens to dependent resources (comments, playlists entries) or of quota cost.

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% and two of three parameters are described in the schema; only video_id is undocumented but is self-evident as the required identifier. The description adds no format, scoping, or channel-selection detail beyond the schema.

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

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

States a specific verb and resource ('Permanently delete a video from YouTube'), which cleanly separates it from sibling deletions such as delete_playlist, delete_comment, and delete_captions.

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 precondition — the user's confirmation is always required — which tells the agent this is not a fire-and-forget call. It does not name alternatives (e.g., set_visibility for unlisting rather than deleting), so no 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 annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is known. The description goes beyond them by disclosing the side effect of revoking the app's Google OAuth access and by stating the user-confirmation requirement, which explains the confirmation_token flow. It does not say what happens to already-uploaded content or whether reconnection is required afterward.

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 short sentences, front-loaded with the action and consequence, followed by the single gating requirement. No filler whatsoever.

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 two-parameter tool with no output schema and rich annotations, the description covers action, consequence, and the confirmation gate. Missing only post-state details such as what happens to existing uploads or whether the user must re-authenticate.

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 both 'channel' (ID/@handle/name, omit for default) and 'confirmation_token' (returned by prior identical call) are fully documented in the schema. The description only echoes the confirmation requirement without adding format details, so baseline 3 applies.

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

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

States a specific verb+resource ('Remove a connected channel') and adds the consequence of revoking the app's Google access, which separates it from siblings like get_channel, update_channel, and list_channels. It stops short of naming an alternative explicitly, but the destructive scope is unmistakable.

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?

'Needs the user's confirmation' gives one clear prerequisite for invocation, which is useful guidance. However, there is no explicit when-not guidance (e.g., use set_default_channel or update_channel if you only want to change settings) and no mention of what to do if the channel is the default or currently connected for uploads.

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?

Goes well beyond the readOnly/openWorld annotations: it discloses the 250-quota-unit cost, the track-selection preference order, the auto-generated fallback, and the SRT output format. It stops short of explaining what happens when no caption track exists at all.

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 short clauses with zero filler; the output format and fallback behavior are front-loaded and the cost is stated plainly. Every phrase carries 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 no output schema, the description covers format, cost, and selection behavior well. The notable gap is the undocumented language parameter and the absence of any statement about failure when no captions exist.

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 33% — channel is documented in the schema, but video_id and language are bare. The description adds no meaning for these: it does not say whether language is optional, what default is used when it is omitted, or how track preference interacts with the requested language.

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 (download), resource (caption track), target (your own video), output format (SRT), and selection behavior (prefers uploaded tracks, falls back to auto-generated). It is clearly distinguishable from sibling tools like list_captions, upload_captions, and delete_captions.

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 name and description: use this to retrieve caption text for a video rather than to list or delete them. However, it never states a prerequisite such as listing captions first to discover available languages, nor does it name an alternative tool for those cases.

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

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

The annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds that this tool gathers inputs rather than writing final metadata. It also lists the transcript sources, though it does not describe return shape, auth needs, or rate limits.

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

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

Two sentences, front-loaded with the core purpose and then the next step. The parenthetical listing transcript sources is dense but useful, with no wasted wording.

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 gathering tool with nine optional parameters and no output schema, the description covers the main inputs and the follow-up step. It could say more about the returned brief, but the schema and annotations carry most remaining detail.

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

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

Schema coverage is 78%, so the schema already documents most parameters. The description maps transcript sources to transcript, transcript_path, video_id, and file_path, and mentions the template, but adds little for notes, channel, language, or format beyond what the schema provides.

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

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

The description uses a specific verb, "Collect," and names the concrete resource: everything needed to write a title, description, chapters, and tags. It also distinguishes this gathering step from preview_metadata, so an agent can tell it is not the final metadata writer.

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

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

It clearly positions the tool before writing metadata and explicitly says to check the result with preview_metadata. It does not spell out when not to use it or compare against every sibling, but the workflow context is clear.

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

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

Annotations already declare readOnlyHint and openWorldHint, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a ~2-day data lag and the 28-day default window. It does not describe pagination or result shape, so it is solid but not rich.

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?

Front-loaded with purpose, then a compact enumeration of reports, then defaults and lag. Dense but every clause carries information; the long report list is slightly list-heavy but 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 10-parameter, no-output-schema analytics tool, the description covers report selection, defaults, and the key conditional dependency (retention→video_id). Minor gaps remain around sort and max_results behavior, but an agent has enough 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 coverage is 70%, and the description meaningfully compensates: it explains what each report value returns, that retention needs video_id, and that metrics/dimensions/filters apply only to custom. It leaves sort and max_results unexplained, which keeps it below a 5.

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

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

States a specific verb and resource ('YouTube Analytics for the channel or one video') and enumerates the exact report types it can produce, which lets an agent distinguish it from get_video or get_channel at a glance.

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 concrete usage context: defaults to the last 28 days, retention requires video_id, and custom requires your own metrics/dimensions. It does not explicitly say when to prefer this over sibling tools like get_video, so it stops short of full alternative routing.

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

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

The readOnlyHint and openWorldHint annotations already establish that this is a safe read against remote data, so the bar is lower. The description adds value by enumerating what data surfaces (keywords, country, default language, trailer, banner, settings), effectively a partial return spec. It says nothing about quota cost, auth requirements, or whether any of these fields can be null/absent, which matters given sibling tools like quota_status and auth_status.

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?

It is a single short fragment with zero wasted words, which is good. But it is a caption, not a description: there is no leading verb or purpose statement, so the structure does not front-load what the tool does the way an agent scanning tool lists would benefit from.

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 1-parameter read tool with no output schema, listing the returned fields is the most valuable thing the description can do, and it does that reasonably thoroughly. What is missing is usage routing versus sibling channel tools, not return-value coverage.

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 channel parameter's accepted forms (channel ID, @handle, name, omitted for default) are fully documented in the schema. The description adds no meaning beyond that, which is the expected baseline given complete schema documentation.

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 text is a bare enumeration of channel attributes (title, handle, keywords, counts, banner, settings) with no verb, so the agent must infer that the tool *retrieves* this data. The attribute list does loosely distinguish it from get_video and get_analytics, but the purpose is implied by field names rather than stated.

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

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

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With siblings like list_channels, update_channel, get_analytics and set_channel_banner present, the description gives the agent nothing to choose between them.

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 readOnlyHint and openWorldHint, but the description adds real value beyond them: it discloses that the call can block and wait for state changes, and it enumerates the returned aspects (progress, errors, resulting video, failure/rejection states, private-lock check). It does not state the maximum wait or that waiting holds a connection, but the schema covers the wait bound.

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?

A single dense sentence that front-loads the primary purpose and then adds the secondary mode and the wait capability. The 'and/or' construction is slightly ambiguous but compact enough to justify its length.

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 does a good job enumerating what comes back, and with zero required parameters it explains the two identifier modes. The remaining gap is the all-optional-parameter case — what happens if neither job_id nor video_id is supplied — plus the relationship between an upload job and its resulting video, which an agent polling for completion would need.

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 50%, and the two undocumented parameters are exactly job_id and video_id. The description partially compensates by mapping each to a different mode (upload job status vs. video processing state), which is genuine meaning beyond the bare schema. It still omits identifier format, whether both may be combined, and behavior when both are absent.

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

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

The description names a specific resource (upload job / video processing state) and enumerates what it reports: progress, errors, resulting video, and the 'locked to private' restriction. It is clearly a read-only status/polling tool, distinguishable from list_uploads and cancel_upload by its per-item focus, though it never names those siblings explicitly.

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 'and/or' phrasing implies that supplying job_id queries the upload job while supplying video_id queries YouTube's processing state, which is useful implicit routing. However, there is no explicit statement of when to prefer this over list_uploads or get_video, and no instruction on what to do when neither identifier is provided even though zero parameters are required.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds value by telling the agent what data surfaces (privacy, schedule, processing state), but says nothing about error behavior for missing/private videos or channel resolution.

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?

A single front-loaded sentence with no filler; every listed facet earns its place by sketching the response shape. It is a sentence fragment rather than prose, but that aids scanning.

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 usefully enumerates the return payload, which is the main completeness burden here. It still leaves the required video_id parameter unexplained and gives no usage framing, so a moderately complex read tool is only adequately documented.

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 50% – video_id has no description at all in the schema, and the description does not explain its expected format or where to obtain it. The 'channel' parameter is documented in the schema, not the description, so the description contributes nothing beyond the schema and fails to compensate for the gap.

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-and-resource framing ("Full details of one video") and enumerates the returned facets: metadata, privacy/schedule, processing state, duration, captions flag, statistics. That is enough for an agent to distinguish it from list_my_videos or get_analytics, though it never names those siblings explicitly.

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

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

There is no when-to-use guidance: nothing says this requires a known video_id, or when to prefer it over list_my_videos or get_analytics. The singular "one video" only weakly implies the lookup-by-ID scenario.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety and access profile are covered. Beyond that, the description adds only a parenthetical list of fields, with no note on ordering, whether draft/auto-generated tracks are always included, pagination, or error behavior when the video is not owned by the caller.

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?

It is a single short fragment with no wasted words, but the terseness crosses into under-specification: no verb, no sentence structure, and the parenthetical field list carries all the informational load. Short is good here, but it is not front-loaded around an actionable statement.

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 no output schema and no documentation of the required video_id, the description says nothing about return shape, ordering, or counts. An agent knows roughly what the tool returns but nothing about how to scope the call or what to expect back.

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 50%: the channel parameter is documented, but the required video_id has no description at all, and the description never mentions either parameter or how channel selection interacts with the default channel. With low coverage the description should compensate, and it does not.

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 is a bare noun phrase ('Caption tracks on a video') that names the resource and lists the fields returned but never states the verb; the agent must infer 'list' from the tool name and title. It also does not distinguish this tool from siblings such as download_captions, delete_captions, or upload_captions.

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

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

There is no guidance on when to use this tool versus the four other caption-related siblings, no stated prerequisites (e.g. the video must exist and be accessible on the given channel), and no exclusions. The agent is left to infer that this is the read-only inventory call.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered; the description contributes the useful facts that results are region-dependent and consist of id/name pairs. It does not mention that the catalogue comes from YouTube's fixed list, that the connected channel/region determines the result set, or anything about authentication or result size.

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?

A single short sentence with no filler, and the two most important facts (what it returns, region dependence) are front-loaded. It reads as a fragment rather than a complete statement, which slightly undercuts clarity but wastes nothing.

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 two-parameter read tool with annotations covering the safety profile, the description conveys returns and region scoping, which is close to sufficient. It stops short of framing the tool's role in the workflow (feeding a category id into video updates) and leaves region_code semantics entirely implicit.

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 50% — only 'channel' is documented in the schema, while 'region_code' carries just a default of 'US' and length constraints. The description's phrase 'for a region' does add the crucial meaning that categories vary by region, partially compensating for that gap, but it never explains the format (ISO 3166-1 alpha-2) or what happens when region is omitted.

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 identifies the resource clearly ('YouTube video categories') and notes the returned fields (id and name) plus the region scoping, but it is a noun phrase with no explicit verb — the agent must infer that this is a listing/retrieval operation rather than something that creates or validates categories. It is distinguishable from all siblings since none deal with categories, so the gap is phrasing rather than ambiguity.

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

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

There is no explicit when-to-use statement or named alternative, but 'categories you can assign' implicitly signals the workflow: call this to obtain valid category ids before assigning one to a video (e.g., with update_video). Nothing tells the agent when not to call it or whether results are static and cacheable.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds the useful scoping fact that results are limited to channels connected to this server, but says nothing about ordering, pagination, or what happens when no channels are connected.

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?

A single front-loaded sentence with no filler, hedging, or redundant restatement of the title. Nothing could be removed without losing meaning.

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 tool with annotations covering safety, the description is nearly sufficient, but there is no output schema and the description never indicates the shape of the result (channel IDs, titles, default-channel flag) or how an empty list should be interpreted.

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 takes zero parameters, so the baseline is 4. The description's scope phrase ('connected to this server') is the only semantic added, and there is no parameter surface left to explain.

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 ('List') and resource ('YouTube channels connected to this server'), which is enough to separate it from singular reads like get_channel and from mutation siblings like connect_channel. It does not explicitly position itself against list_my_videos or auth_status, but the resource scope 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?

There is no when-to-use or when-not-to-use guidance and no named alternative (e.g., auth_status for connection health, get_channel for per-channel detail). An agent must infer usage entirely from the name and the phrase 'connected to this server'.

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

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

The readOnlyHint annotation already covers the safety profile, so the bar is lower. The description adds real value with the 'newest first' ordering, the enumerable moderation states, and the fact that replies are included. It omits pagination behavior despite exposing page_token, and says nothing about quota consumption, which matters for a YouTube-backed API that has a quota_status sibling.

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, scoping and ordering front-loaded, with no filler. Every clause carries information the caller needs.

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 and only read-only annotations, the description should carry more of the load for a seven-parameter list tool with page_token and a max_results cap of 100. Pagination and the relevance ordering option are the notable holes; the coverage of scope, status, and replies is otherwise adequate.

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

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

Schema coverage is 29%, so the description must compensate, and it partly does by naming the three status values, the search-text filter, and that video_id may be omitted for a channel-wide sweep. It leaves channel, page_token, and max_results unexplained and never mentions that the order parameter also accepts 'relevance', which 'newest first' arguably obscures.

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 the verb implicitly ('Comment threads on...') and the exact resource, comment threads, plus the two scopes: one video or the whole channel. This separates it cleanly from moderate_comments and delete_comment, which act on comments rather than reading them. It stops short of naming a sibling, so a 4 rather than a 5.

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 strong implied usage: read comments, filtered by moderation state or search text, with replies included. It never says when to prefer this over moderate_comments or when to page through results, and gives no prerequisites such as needing a connected channel. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the description is not needed to establish safety. It still adds real behavioral value: result ordering (newest first), the surprising inclusion of private/unlisted/scheduled items, and the fact that each entry carries privacy, schedule, duration and view counts. It does not mention quota cost or whether the default channel is used when unset, which are the remaining behavioral gaps.

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 zero filler, ordering and scope front-loaded, and pagination last where it belongs. The phrase "with privacy, schedule, duration and view counts" is slightly ambiguous since "privacy" is also a filter parameter, but the return-value reading is recoverable from context.

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 usefully enumerates the fields returned per video, which is the main completeness burden here, and it covers ordering and pagination. It leaves page size (max_results, capped at 50) and channel-defaulting behavior entirely to the schema, and gives no hint about cost or result volume for a potentially large listing.

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 60%, with query, channel and privacy documented in the schema and page_token and max_results undocumented. The description only explains page_token ("Paginate with page_token") and never covers max_results or clarifies that query/privacy filter the current page only, so it partially but not fully compensates for the coverage gap.

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 ("List videos on the channel") and adds ordering ("newest first") plus the key inclusion of private, unlisted and scheduled videos, which meaningfully separates it from get_video or list_uploads. It stops short of explicitly naming a sibling to route against, so an agent must infer the boundary itself.

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 scope and the pagination instruction, but there is no explicit when-to-use or when-not-to-use statement and no pointer to alternatives such as list_uploads (upload jobs) versus this tool (channel video inventory). An agent can guess the context but is not guided.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds only that results are ordered, while omitting pagination behavior despite page_token and max_results parameters, and omitting any indication of default or capped page size.

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 technically short, but it is under-specified rather than concise. A single fragment with no verb or usage context does not front-load actionable information for an agent.

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 four-parameter listing tool with no output schema, 50% schema coverage, and no pagination details in the description, this is not complete enough for reliable invocation. An agent cannot tell how paging works, what the result shape is, or why to choose this over sibling listing tools.

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 50%, with channel and playlist documented but page_token and max_results undocumented. The description does not compensate by explaining pagination, the default of 50, or the maximum of 50, so it adds no meaning beyond the partially documented 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 is a noun phrase, 'Videos in a playlist, in order,' that essentially restates the tool title 'List videos in a playlist' without a specific verb. It implies the resource and ordering but does not clearly distinguish the operation from siblings like list_playlists or get_video beyond the object named.

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

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

There is no guidance on when to use this tool versus list_playlists, get_video, or move_in_playlist, nor any note about required preconditions such as a connected channel. The only implied usage comes from the name and title, not the description text.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description contributes by disclosing which fields come back (id, title, privacy, video count), which matters since there is no output schema, but it says nothing about ordering, pagination, or whether private/unlisted playlists are included.

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 short sentence with the scope and return fields front-loaded and no filler. It is a sentence fragment rather than a complete sentence, but nothing is wasted.

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

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

For a one-parameter read-only list tool with a fully documented schema, annotations covering safety, and the returned fields enumerated in the description, an agent has everything needed to call it correctly. Return-format concerns are partly mitigated by the listed fields.

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% and the single 'channel' parameter is fully documented in the schema (ID, @handle, name, default fallback). The description's phrase 'on the channel' loosely reinforces the scoping but adds no syntax or default behavior beyond the schema.

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

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

The description names the resource (playlists) and scope (all playlists on the channel) and enumerates the returned fields (id, title, privacy, video count). It is clearly a listing operation, though the verb is only implied and no sibling (e.g. list_playlist_items) is named for contrast.

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

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

There is no guidance on when to use this versus list_playlist_items, get_channel, or create_playlist, and no prerequisites or exclusions. Usage is only inferable from the name and the phrase 'on the channel'.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so safety is covered. The description adds only a hint about what fields the templates carry; it says nothing about whether results are account-wide or per-channel, whether the list can be empty, or whether custom versus built-in templates are mixed.

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?

A single short parenthetical sentence with no wasted words, but it is a fragment with no leading verb and no statement of purpose, so it is terse without being well-structured.

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 parameters, no output schema and read-only annotations, there is little to explain, and the field list gives a rough picture of what comes back. Still, an agent cannot tell the scope of the listing or how to distinguish custom templates from defaults before upload workflows.

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 takes zero parameters, so there is nothing for the description to disambiguate. Baseline 4 applies; the enumeration it does provide describes return content rather than inputs, which is harmless here.

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 is a noun phrase enumerating template fields (title format, description footer, default tags, hashtags, category, playlists, voice guidance) rather than a verb-plus-resource statement. It does make clear the resource is metadata templates for uploads, but never says it lists them or what scope (channel/account) they cover, so it reads as an inventory definition rather than an action.

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

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

There is no guidance on when to call this instead of the closely related siblings save_template and delete_template, nor any mention of prerequisites such as connecting a channel first. The 'available for uploads' phrasing hints it feeds upload-related tools, but the agent must infer that.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety and locality profile is known. The description usefully adds ordering ('newest first') and signals that each entry carries 'progress and results', but says nothing about pagination behavior, default status filtering, or whether entries disappear once a job is cleaned up.

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?

A single front-loaded sentence with no filler, and the ordering guarantee is placed where it is most useful. It is efficient but so terse that the brevity shades into under-specification.

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 list tool with annotations covering safety, the core intent is conveyed and 'with progress and results' compensates slightly for the absent output schema. The unaddressed parameters and the absence of any return-shape detail leave real gaps for an agent trying to predict what comes back.

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 0%, so the description carries the full burden for the two parameters and does not carry it — 'limit' and 'status' are never mentioned, the eight-value status enum is unexplained, and 'recent' only vaguely gestures at a result-count cap.

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 gives a specific resource (upload jobs) plus scope qualifiers — 'recent', 'from this computer', 'newest first' – which distinguish it from a single-job lookup like get_upload_status or a library listing like list_my_videos. It never names those siblings, so differentiation is inferential rather than 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?

Usage is only implied: an agent can deduce this is the browsing/history tool versus status polling, but the description states no when-to-use condition, no exclusions, and no pointer to an alternative tool for a specific job id or for already-published videos.

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 destructiveHint=true, openTopic read/write safety (readOnlyHint=false), openWorldHint=true, and idempotentHint=true, so the safety profile is covered structurally. The description adds real behavioral value by disclosing the two-step confirmation gate and the irreversible effect of banning (suppressing the author's future comments). It does not say what happens to in-flight or existing comments when one is removed, or whether a hold is reversible within a time window.

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 covering the three modes plus the optional ban, followed by a short second sentence on the confirmation requirement. It is front-loaded with the operation set and includes no filler.

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

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

For a destructive, multi-mode mutation tool with no output schema, the definition supplies the essential gating information (confirmation before removal) and the scope of the ban effect. The remaining gap is return/outcome behavior — what a successful hold versus publish yields — which the agent cannot infer from structured fields.

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 60%, with action and comment_ids undocumented in the schema; the description compensates by explaining what each action value means and by explaining the ban_author/remove coupling. It also reinforces the confirmation_token workflow that the schema only briefly describes. It adds no detail on the 50-item comment_ids cap or on channel resolution, but those are adequately covered 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?

The description names specific verbs and the resource: publish, hold, and remove (reject) comments, with an optional author ban. It enumerates exactly the three enum values in the action parameter, so an agent knows the operation set. It does not, however, distinguish 'remove' here from the sibling delete_comment, which is a plausible source of tool-selection confusion.

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

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

It gives a clear operational precondition — that removing or banning requires the user's confirmation — and ties ban_author to the remove action only ('Only with remove'). It does not state when to choose this over delete_comment or list_comments, so the alternative-selection guidance is only partial.

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

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

Beyond annotations declaring an idempotent, non-destructive, open-world mutation, the description adds the useful manual-sort compatibility constraint. It does not explain failure behavior for incompatible playlists, invalid-position handling, or how surrounding entries are shifted.

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 short sentences front-load the operation and immediately provide indexing and compatibility details. There is no filler or redundant restatement of structured fields.

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 flat four-parameter reorder operation, the action, index convention, and principal prerequisite are sufficient for most selection and invocation decisions. Missing identifier guidance and edge-case behavior prevent it from being 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?

With only 25% schema description coverage, '(0 = first)' usefully adds zero-based indexing semantics for position, while the operation gives basic context for playlist and video_id. However, accepted playlist and video identifier formats remain undocumented, as does the valid upper bound for position relative to playlist length.

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 specifies the action, target, and scope: moving a video to a new position within a playlist. This clearly distinguishes reordering from siblings such as add_to_playlist, remove_from_playlist, and update_playlist.

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

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

The statement 'Works for playlists sorted manually' supplies an important eligibility condition and implicitly warns against using it with other playlist orderings. It does not explain how to verify the sort mode or what alternative to use when that condition is unmet.

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

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

The readOnlyHint and openWorldHint annotations already establish that nothing is mutated, but the description adds genuinely useful behavior beyond them: no API call is made and no quota is consumed, which matters for a quota-metered platform. It does not describe the shape of the report returned (e.g., per-field limit violations or chapter-rule warnings), which is the main behavioral unknown left.

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 compact sentences with the primary outcome front-loaded and the no-side-effect guarantee second. Nothing is redundant or padding.

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 11-parameter, read-only tool with no output schema, the description explains the transformation and validation intent but not what the preview actually returns or how violations are surfaced. The annotations carry the safety profile and the schema carries most parameter semantics, so the gap is narrow 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 coverage is 82%, so the schema already documents nearly every parameter including enums and max lengths; baseline 3 applies. The description's only added meaning is that the metadata shown is post-template application (template adds title format, footer, tags, hashtags, playlists), which clarifies how the template parameter interacts with the other fields.

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?

"Show exactly what would be sent to YouTube (title, description, tags, playlists) after applying a template" is a specific verb plus resource, and the dry-run framing plus "No API call" separates it from write-side siblings like update_video or generate_metadata. It stops short of naming any sibling outright, so the distinction is inferable rather than 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 framing implies the natural use case (validate a template-applied metadata set before committing), but the description never states when to use this versus generate_metadata or update_video. There are no explicit exclusions or prerequisites, leaving the agent to infer the preview-before-write workflow.

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 readOnlyHint=true and openWorldHint=false, and the description adds meaningful context beyond them: the figures are estimates rather than exact counts, they cover the current day only, they are scoped to this Google Cloud project, and the reset occurs at midnight Pacific Time. That timezone and estimation caveat are exactly the kind of detail annotations cannot carry.

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?

A single sentence that front-loads the resource and enumerates the returned facts with zero filler. Nothing can be removed without losing 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 zero-parameter, read-only status tool with no output schema, the description covers what is measured, the scope, and the reset semantics. It could additionally note whether calling it consumes quota, but nothing essential to correct invocation is missing.

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

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

The tool takes zero parameters, so the schema leaves nothing to explain and the baseline of 4 applies. The description correctly spends no words on parameter behavior.

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

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

The description names the specific resource (YouTube API quota) and the exact values reported (units, uploads, reset time), so an agent knows precisely what it gets back. It does not explicitly contrast itself with siblings, though its scope is distinct enough from tools like get_analytics or auth_status that confusion is unlikely.

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

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

There is no explicit when-to-use statement, no prerequisites, and no named alternative. The agent must infer that this is useful before quota-consuming operations or after quota-exceeded errors; the mention of reset time hints at that but does not state it.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the mutation and repeat-safety profile is covered. The description adds one genuinely useful clarification — that the underlying video survives, only the playlist membership is removed — but says nothing about permissions, behavior when the video is absent from the playlist, or whether item positions shift.

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?

A single front-loaded sentence with no filler, and the parenthetical is well placed to prevent a destructive misread. It is arguably under-specified rather than overly long, which is a different problem than verbosity.

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 low-complexity mutation with annotations covering safety and no output schema, the essentials are largely present, but one of three parameters is undocumented and the description omits failure modes (video not in playlist, unknown channel) that matter for a destructive operation.

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

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

Schema coverage is 67%, with channel and playlist documented in-schema (default-channel omission and playlist id-or-exact-title) while video_id carries no description anywhere. The description adds no parameter meaning at all, so it neither compensates for the undocumented video_id nor reinforces the matching semantics of the playlist title.

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

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

States a specific verb and resource ('Remove a video from a playlist') and the parenthetical '(the video itself is not deleted)' carves out the scope so it is not confused with delete_video. It does not explicitly name the inverse/nearby siblings (add_to_playlist, move_in_playlist), so differentiation is only partial.

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 no when-to-use context, no prerequisites (e.g. the playlist must exist, the video must currently be a member), and no routing to alternatives such as move_in_playlist or delete_playlist. The agent must infer the appropriate situation entirely from the name.

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 this is a non-read-only, non-idempotent, open-world write. The description adds genuinely new behavior: the post is public and attributed to the channel, and a confirmation step is required before posting. It does not cover failure modes, quota cost, or whether the reply is immediately visible.

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?

A single dense sentence with the primary action front-loaded and the mode distinction in parentheses. Every clause carries information, though the nested parentheticals make it slightly harder to scan than a two-sentence split would.

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 public write tool with no output schema, the definition covers the essential mechanics: what gets posted, under whose identity, and the confirmation gate. Missing details are secondary — error behavior, quota impact, and what the response contains after posting.

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 40%, so the description must compensate. It does explain comment_id (top-level comment or thread id) and video_id (new top-level comment), but leaves channel and confirmation_token to the schema and says nothing about text constraints (1–10000 chars). Partial compensation warrants a middle score.

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

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

The description names a specific verb and resource ('Post a public reply to a comment' / 'new top-level comment on a video') and disambiguates the two modes by tying each to its parameter (comment_id vs video_id). This clearly separates it from siblings like list_comments, delete_comment, and moderate_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?

It states the two usage modes explicitly and adds the precondition that the user must confirm the exact text first, which tells the agent how to sequence the call. It stops short of naming when to prefer a sibling (e.g., moderate_comments) or what to do if the target comment is gone.

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

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

Annotations already disclose readOnlyHint=false, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds real value by explaining resumption semantics (resumes from the last confirmed byte, automatic retries) but says nothing about auth requirements, idempotency of repeat calls, or that the call may block while waiting.

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 compact sentences, front-loaded with the action and scope, then the qualifying detail about automatic retries. No filler, though the retry sentence could be tightened since it also appears as behavior elsewhere.

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?

This is a mutating tool with no output schema and fully undocumented parameters. An agent still cannot tell what job_id to supply, whether the call blocks, or what it returns on success versus an exhausted retry, which is a substantial gap for the complexity involved.

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 0%, so the description carries the full burden for both parameters and fails: it never mentions job_id (where it comes from, format) or wait_seconds (that it is a blocking wait capped at 110 seconds with a default of 10). The only hint is indirect, via 'last byte YouTube confirmed'.

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

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

The description states a specific verb and resource ('Resume a stopped, failed or cancelled upload') and pins the resume point ('from the last byte YouTube confirmed'), which cleanly distinguishes it from start-fresh siblings like upload_video. It never names the sibling tools it supersedes, so it stops short of a 5.

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

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

It gives concrete trigger conditions (stopped, failed, or cancelled upload; after a quota reset or reconnecting the channel) and adds a partial when-not by noting that network drops and quota resets are retried automatically. It does not say what to check first or which sibling reports job state, so the routing guidance is clear 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?

Beyond the annotations the description discloses two real behaviors: templates are stored as JSON files in a templates folder, and `extends` inherits from another template while tags and hashtags are merged rather than replaced. It says nothing about validation failures, what happens to omitted fields on replace, or how deeply inheritance is resolved.

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-loaded with the core action, with no filler. The final clause 'tags and hashtags combine' is telegraphic but still intelligible.

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 16-parameter mutation tool with no output schema and no annotation coverage of field semantics, the description is far too thin: most fields an agent must supply are undefined, and replace-vs-merge behavior is only stated for tags and hashtags, not for the rest of the 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 description coverage is 0% across 16 parameters, so the description must carry the load, but it only explains title_format ('{title}'), extends, tags and hashtags. Twelve parameters — including the license enum, embeddable, made_for_kids, category_id, playlists, and the description header/footer fields — get no meaning at all.

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

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

States a specific verb and resource ('Create or replace a metadata template') plus where it is persisted (JSON in the templates folder). It is clearly distinguishable from delete_template and list_templates, though it never names those siblings explicitly.

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 phrase 'Create or replace' implies the tool is the upsert path for templates and that an existing template with the same name is overwritten. There is no explicit guidance on when to save versus delete, or on prerequisites such as an existing name collision check.

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 flag the write, open-world and idempotent profile, but the description adds genuinely non-obvious behavior: the banner is publicly visible and therefore requires prior user confirmation. That side-effect disclosure goes beyond what the annotations convey. It stops short of saying whether an existing banner is replaced or what a successful call returns, which is the remaining gap.

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 compact sentences with no waste: the hard image constraints come first, then the approval requirement. Every clause carries operational information an agent needs before calling.

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 three-parameter mutation with no output schema, the definition covers the essentials: valid input format, visibility consequences and the confirmation handshake. It could be slightly more complete by stating what replaces the current banner and any per-account or quota limits, but nothing critical for calling it correctly is absent.

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%, and the one undocumented parameter, image_path, is exactly the one the description compensates for by specifying format, aspect ratio, minimum and recommended resolution, and size cap. The confirmation hint also gives the otherwise cryptically-named confirmation_token a workflow meaning. What is missing is any hint about error handling when an image fails the constraints.

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

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

States a specific verb and resource ("Upload a channel banner") and pins down the channel-level scope, which naturally separates it from set_thumbnail and set_watermark. It never names those siblings explicitly, so an agent must infer the distinction from the resource name alone.

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 sentence "Public, so the user confirms first" implies a required two-step approval workflow, which is useful context. However, there is no explicit when-to-use or when-not-to-use guidance relative to alternatives like set_thumbnail or update_channel, leaving the routing decision implicit.

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

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

The annotations already declare this is a non-read-only, idempotent, non-destructive, closed-world mutation, and the description is consistent with that. It adds real value by disclosing the side effect's scope — it changes the fallback for any later tool call that omits a channel. It does not say whether the setting persists across sessions or what happens when the referenced channel is disconnected.

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 sentence, front-loaded with the action, and every clause earns its place by defining the default's effect. There is no filler or restatement of the title.

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

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

For a single-parameter setter with full schema coverage and annotations covering the safety profile, this is nearly complete. The only material gap is the absence of failure conditions, such as what occurs when the supplied channel is not connected.

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

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

Schema coverage is 100%, with the single 'channel' parameter documented as accepting an ID, @handle, or name, so the baseline is 3. The description adds one qualifier — the channel must already be connected — but offers no format hints or error behavior 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 action and resource: choosing which connected channel serves as the default. It also explains what 'default' means operationally (the channel used when a tool call omits one), which is more informative than the title alone. It does not distinguish itself from connect_channel or list_channels by name, so sibling routing is left to the agent.

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 rather than stated: an agent can infer it should call this when it wants subsequent channel-less calls to target a specific account. There is no explicit 'use this instead of X' guidance, no prerequisite that the channel must first be connected, and no note on what happens if the named channel is not connected.

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 this is a non-destructive, idempotent, open-world write, so the description's job is to add operational constraints, and it does: file types, a 2 MB cap and a recommended 1280x720 resolution. It omits that the existing thumbnail is replaced and says nothing about quota cost or failure modes, which for a YouTube-style API would be genuinely useful.

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 action and format limits front-loaded ahead of the prerequisite. Every clause carries information an agent needs.

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 three-parameter write tool with no output schema, the description covers formats, size, path locality and the verification prerequisite. The remaining gap is behavioral rather than structural: it never says whether an existing thumbnail is overwritten or what a quota failure looks like.

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 video_id undocumented in the schema, and the description supplies the constraint that image_path must be a local JPG or PNG under 2 MB at roughly 1280x720, meaning well beyond the schema's bare 'Absolute path to the image.'

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 (upload) and resource (the video's thumbnail) with the accepted formats inline, which is enough to separate it from sibling setters like set_channel_banner and set_watermark that target channel-level branding rather than a single video.

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

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

'from this computer' rules out passing a URL, and 'The channel must be phone-verified' is a concrete precondition, so an agent knows the context in which the call can succeed. It stops short of naming alternatives (e.g. whether update_video can also touch thumbnails) or saying what to do when verification is missing.

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 idempotentHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description usefully adds the merge semantics and the default_language prerequisite, which are behaviors the annotations do not convey. It says nothing about what happens on conflicting titles, on invalid language codes, or what the call returns, so the added value is real but partial.

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-loaded with the action and immediately followed by a concrete payload example, then the merge behavior and the prerequisite. Every sentence carries information; the one weak spot is that the example inline with the first sentence slightly interrupts the purpose statement.

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 nested-object mutation with no output schema and only 25% schema description coverage, the description covers the payload structure and the key precondition well. It leaves the remove_languages parameter and the response behavior unexplained, which an agent needs in order to use the full surface of this tool correctly.

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

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

Schema description coverage is only 25%: channel is documented, while video_id, localizations and remove_languages are bare. The description compensates well for localizations by giving the exact shape and a concrete example keyed by language code, and it flags the default_language precondition. However, remove_languages receives no explanation at all despite being a distinct mutation path, leaving a meaningful gap the schema does not fill.

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 pair ('Add or update') and a specific resource ('the title and description shown to viewers in other languages'), and names update_video as the related sibling for setting default_language. It is clearly distinct from update_video and the caption tools, though it never states the canonical term 'localizations' that the parameter uses.

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

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

It gives real preconditions: the video must already have default_language set, and that is done via update_video. It also states that new entries are merged with existing translations rather than replacing them. It stops short of naming when-not-to-use cases or an alternative for removing translations, so it is clear context but not a full routing rule.

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 the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the bar is lower, and the description still adds the crucial non-obvious behavior: a confirmation gate for unlisted/public/scheduled changes, which explains the confirmation_token parameter. It stops short of describing failure modes or quota/open-world side effects.

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 short sentences, zero filler, with the resource and valid states front-loaded before the confirmation constraint. Nothing is repeated from the title verbatim.

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 5-parameter mutation tool the description covers the two things an agent most needs beyond the schema: the valid state set and the confirmation workflow that gates non-private changes. Minor gaps remain around the channel parameter and what a confirmation failure looks like, 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 coverage is 60%, with privacy (the enum) and video_id undocumented in the schema, but the description names the three privacy values, filling the most important gap. It adds nothing beyond the schema for publish_at or confirmation_token, so it sits at the baseline for partially documented parameters.

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

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

States a specific verb and resource ('Change who can see a video') and enumerates the target states (private, unlisted, public, scheduled via publish_at). It does not, however, distinguish itself from the nearby update_video sibling, which plausibly also touches visibility, so an agent must infer the boundary.

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 one real usage condition: anything other than private requires the user's confirmation. It offers no guidance on when to reach for this instead of update_video, nor on whether privacy can be omitted (scheduling-only calls), leaving the routing decision implicit.

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

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

Annotations already declare this is a non-read-only, idempotent, non-destructive open-world mutation. The description adds real value beyond that with concrete asset constraints (square JPG/PNG, ≥150x150, ≤1 MB), which the agent cannot infer from annotations. However, it omits the confirming-call workflow and the scope of effect ('all channel videos' is stated, but no note on reversibility or quota cost).

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?

A single front-loaded sentence with the primary action first and the removal variant second; the parenthetical constraint block is dense but earns its place. Nothing is repetitive or wasted.

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 six-parameter setter with no output schema, the description covers the core action, the removal alternative, and asset requirements, and the schema's own descriptions cover channel selection and the confirmation token. What remains missing is only secondary: offset semantics and post-call outcome.

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

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

With 50% schema coverage, three parameters (image_path, offset_seconds, remove) lack schema descriptions, and the description compensates for two: it defines the image format/size limits for image_path and the meaning of remove. It says nothing about offset_seconds or the interaction between show='custom' and offset_seconds, which remain undocumented.

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 gives a specific verb pair (set/remove) plus the exact resource: the subscribe watermark shown on all channel videos. It is clearly distinguishable from siblings like set_thumbnail or set_channel_banner, though it does not explicitly name those siblings as 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?

It states the removal path ('or remove it with remove: true'), which usefully tells the agent it does not need a separate delete tool. It gives no guidance on when to choose a particular 'show' mode, which channel to target, or that a confirmation_token round-trip is required for the actual mutation.

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 flag readOnlyHint=false and openWorldHint=true; the description adds the value beyond them by naming the external dependency and credential requirement and disclosing the local side effect of writing an .srt file. It omits where the file is written, whether it overwrites, and any runtime/length limits.

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 with the action, prerequisites, output artifact, and downstream use all front-loaded. No filler or redundancy.

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

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

With no output schema, the description carries the return-value burden and does so (timestamped transcript plus an .srt). Prerequisites and downstream chaining are covered; only path conventions and error/failure behavior are absent, which is acceptable but not exhaustive for a tool that shells out to ffmpeg and a remote API.

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 50%: 'language' is documented in the schema, but 'file_path' has no description there. The description only implies a local path via 'on this computer' and adds no format, path-style (absolute vs relative), or supported-container details, so it does not compensate for the gap. Baseline 3 applies.

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

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

States a specific verb+resource ('Transcribe a video file on this computer') and scopes it to a local file, which cleanly separates it from the upload/generate_metadata siblings that operate on the remote platform. The dual output (an .srt on disk plus a returned timestamped transcript) is named explicitly.

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 concrete preconditions ('needs ffmpeg and a configured key') and a downstream workflow pointer — the .srt can be fed to upload_video or upload_captions, and the transcript is for 'writing metadata and chapters', routing to generate_metadata. No explicit when-not or failure-handling guidance, so not a 5.

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

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

Beyond the supplied annotations (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true), it discloses that the edited fields are publicly visible, that a user confirmation step is required first, and that only supplied fields mutate. That is meaningful operational context the annotations do not convey, though the two-step confirmation/token choreography is only implied rather than spelled out.

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 editable fields, then the partial-update rule, then the safety/confirmation note, ending with a parenthetical exclusion. Every sentence carries information; only minor compression is possible.

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 mutation with a nested object and no output schema, the definition covers scope, mutation semantics, public visibility and the confirmation requirement. The one gap is that localization merging (per-language title/description merged with existing entries) is documented only inside the schema rather than surfaced in the description.

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 channel, country, keywords, localizations, default_language, confirmation_token and unsubscribed_trailer precisely. The prose confirms which fields are editable but adds no format or syntax detail beyond the schema; notably localizations (a nested object) is not mentioned in the description at all.

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

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

The description names a specific verb ('Change') plus the exact editable fields of the channel resource (description, keywords, country, default language, unsubscribed trailer), which cleanly separates it from siblings like set_channel_banner, set_watermark, or update_video.

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

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

It explains partial-update semantics ('Only the fields you pass change'), states the precondition that the user must confirm because the fields are public, and gives an explicit exclusion (channel name/handle must be edited in YouTube Studio). It never names a sibling tool such as get_channel or set_default_channel to read state first, so it stops short of full alternative routing.

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 it non-destructive, idempotent, and open-world, and the description adds a genuinely non-obvious behavioral rule: the confirmation gate for visibility changes. It does not state partial-update semantics (whether omitted fields are preserved) or whether the playlist lookup by title can be ambiguous.

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 short sentences with zero filler; the primary action is front-loaded and the conditional constraint follows. Nothing is repeated from the title.

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

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

For a 6-parameter mutation with no output schema, the definition covers the main fields and the confirmation workflow but omits what the tool returns, whether it is a partial or full update, and the failure mode when no editable field is provided. Adequate but with real gaps for a write operation.

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

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

Schema description coverage is 50%, and the description compensates by tying the three editable fields (title, description, privacy) together and explaining the confirmation requirement that governs the confirmation_token param. The playlist parameter's id-or-exact-title semantics and the channel targeting are left to 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?

"Rename a playlist, change its description or privacy" gives a specific verb and resource plus the exact mutable fields, so an agent can separate it from create_playlist / delete_playlist / list_playlists. It stops short of naming any sibling explicitly, so differentiation is inferred from the verb alone.

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 supplies one actionable condition: making a playlist public or unlisted requires the user's confirmation. It does not say when to reach for this tool versus set_visibility or update_video, nor what to do when no field is supplied, so usage is only implied.

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 idempotent, non-destructive, open-world mutation, so the bar is lower, and the description adds genuinely non-obvious behavior: partial-update semantics, conditional template effects tied to which fields are passed, and a confirmation-gating rule for visibility/scheduling. It stops short of describing failure modes, quota cost, or what the call returns, and the confirmation_token mechanics are only in the schema.

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

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

Three dense sentences, front-loaded with the mutation scope, then conditional behaviors, then the safety gate — no repeated or padded prose. Minor waste in the catch-all 'and other settings' and the parenthetical template clause is slightly compressed, but overall efficient.

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

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

For a 17-parameter mutation tool with no output schema, the description covers the highest-risk gaps: partial-update behavior, template side effects, and the approval requirement before publishing. The remaining undocumented parameters are mostly self-evident booleans, so an agent has enough to invoke it correctly, though failure and return behavior remain unaddressed.

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 24%, so the description must compensate; it does partially by naming the field groups and clarifying template interaction with title/description/tags. However, privacy enum values, category_id, license, and the several booleans (embeddable, made_for_kids, public_stats_viewable, contains_synthetic_media) get no semantic elaboration beyond their self-describing names, leaving real ambiguity for a 17-parameter tool.

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

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

The description opens with a specific verb and resource ('Change a video's title, description, tags, category, languages, audience') and enumerates the editable surface, then explicitly names the sibling it is not for visibility-only edits ('or use set_visibility'). An agent can distinguish this from set_visibility, update_channel or set_video_localizations without opening any schema.

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 the selection rule ('Only the fields you pass change'), explains when the template option applies and precisely which fields each template part affects, and flags the two conditions that require user approval (public/unlisted visibility, scheduling) while routing visibility-only changes to set_visibility. When-to-use, when-to-confirm and the alternative are all 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 declare this is a non-read-only, non-idempotent, non-destructive, open-world operation, and 'Add' is consistent with that profile. The description adds format and source-mode context but omits auth/channel requirements, quota implications, and duplicate-track behavior, so it goes modestly beyond the annotations without being rich.

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?

A single front-loaded sentence that states the action, the accepted formats, and the two input sources with no filler.

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

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

For an 8-parameter mutation with no output schema, the description covers the core action and input modes but leaves gaps around channel/auth behavior, quota cost, and the effect of duplicate or replacement uploads. Adequate but not complete for the tool's complexity.

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 63%, so the schema already documents most parameters. The description adds useful meaning for the file_path-versus-content choice and supported caption formats, but says nothing about name, language, is_draft, replace_existing, or channel semantics beyond what the schema provides.

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

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

The description states a specific verb and resource ('Add a captions track') and specifies supported formats and input sources. It is clear enough to distinguish from siblings like list_captions or delete_captions, though it never names an alternative explicitly.

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 implies usage when a caption file or inline subtitle content is available, but gives no when-to-use versus alternatives such as transcribe_video or download_captions, and no prerequisites such as channel selection or permissions.

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 only mark this as a non-read-only, non-idempotent, open-world write; the description adds the behavior that matters: resumable/checkpointed upload surviving network drops, background execution returning a job_id or a finished video, and the wait_seconds threshold for synchronous completion. The confirmation_token requirement for non-private uploads is a material behavioral disclosure not derivable from 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?

Four dense sentences plus a tip, front-loaded with what the tool does before the async model, confirmation gating, and next-step hints. Every sentence carries operational information; nothing is padding for a 25-parameter tool.

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 25-parameter mutation with no output schema, the description still covers return shape (job_id or finished video), polling path, and the confirmation prerequisite. An agent has enough to invoke correctly and handle the response without further inference.

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 already 88%, so the baseline is 3. The description adds real meaning beyond the schema: the file_path/URL mutual role as alternate sources, publish_at semantics (uploads as private until the scheduled time), and that thumbnail, playlists and captions are applied in the same call. It doesn't clarify the confirmation_token echo-back mechanics in detail, which keeps it from a 5.

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?

Names a concrete verb and resource (upload a video) and specifies both input sources (file_path on this computer or a public URL) plus the destination (YouTube). It distinguishes itself from siblings by defining the async job model, which separates it from resume_upload and upload_captions.

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 explicit routing: poll get_upload_status after the call, and write metadata first via generate_metadata then preview_metadata. It also states the gating condition (private uploads start immediately; public/unlisted/scheduled need the user's confirmation first), so the agent knows the workflow prerequisites.

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