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

Adds substantial behavior beyond the annotations: quota cost (~3 units), which APIs are queried for which private metrics, the auth precondition for private metrics, the opt-in gate for scraping, the fallback of returning setup instructions, and that report.html is overwritten idempotently. This is exactly the disk-write/auth/quota context the annotations alone (readOnlyHint=false, idempotentHint=true) do not convey.

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-loads the purpose and side effects, then layers auth/quota/fallback details. It is dense with parenthetical metric lists and would benefit from slight trimming, but nearly every clause carries actionable 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 tool with disk side effects, auth branching, and quota cost, the description covers the decision points an agent needs: auth requirement, opt-in scraping, fallback behavior, and idempotent overwrite. An output schema exists, so return-value detail is correctly omitted.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: force_public bypasses OAuth2 and yields public views/likes only, is opt-in, and should only be set on user request. That clarifies the parameter's consequence in a way the schema text alone does not fully convey.

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 set — fetch live channel stats, recent long-form videos, Shorts metrics — and names the concrete side effects (report.html dashboard, channel_snapshot.json cache). No sibling tool does a snapshot-style fetch, and the description makes that scope 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?

Clearly describes the two operating modes: OAuth-present path hits Data API v3 / Analytics API v2, while public scraping only happens with force_public=true or the env var, and without either it returns setup instructions. It stops short of explicitly routing against siblings (e.g. yt_video_details) or stating when-not-to-use, so it is not a full 5.

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

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

Goes well beyond the annotations: discloses quota cost, the required youtube.force-ssl OAuth scope, immediate public visibility under the authenticated channel identity, and concrete failure conditions. Annotations already flag non-idempotence, and the description reinforces it with the consequence (each call publishes a new visible 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?

Four dense sentences, each carrying distinct information (action, cost/auth, side effects, failure modes), with the core action front-loaded and 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?

Everything needed to invoke correctly is present: auth requirement, cost, side effects, failure conditions, and even the return shape despite an output schema already existing. Nothing material is missing for a two-parameter mutation tool.

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

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

Schema coverage is 100%, so both parameters are already fully documented with length and pattern constraints. The description adds only the notion that the comment is public and top-level, which is useful framing but not new per-parameter meaning, so the baseline of 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 and resource ("Post a public top-level comment thread on a YouTube video or Short") and pins the exact API method (commentThreads.insert), which cleanly separates it from siblings like yt_upload_draft and yt_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?

Gives clear preconditions and failure modes (comments disabled, private video) plus the ~50 unit quota cost, so an agent can judge affordability and applicability. It does not explicitly name an alternative tool or say when not to use it, but the sibling set contains no closer competitor for this action.

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

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

Annotations already cover readOnly, idempotent, and openWorld, and the description adds substantial behavior beyond them: the newest-first ordering, the live YouTube Data API v3 + Analytics API v2 sourcing, the unauthenticated fallback to public channel pages, and the '—' placeholder for private retention columns. The only gap is that it doesn't say what happens on API failure or auth errors.

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

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

Three sentences, front-loaded with the deliverable and column list before the data-source/auth caveats and the empty-case notice. The middle sentence is dense but every clause (auth fallback, placeholder behavior) carries information an agent needs; little could be cut without loss.

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 the heavy lifting by naming the columns, the ordering, the placeholder for unavailable metrics, and the 'No Shorts found' empty case — enough for correct invocation and interpretation. Minor gaps remain around result-size limits and error behavior, but nothing essential 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 single 'handle' parameter is fully documented in the schema (100% coverage, including pattern and default), so the description adds nothing parameter-specific beyond referring to "the channel's" Shorts. A baseline 3 is appropriate when the schema already carries the semantics.

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 artifact — "Generate a GitHub-Flavored Markdown comparison table" — scoped to the channel's YouTube Shorts, and enumerates the exact columns. This clearly separates it from siblings like yt_video_details (single video) or yt_channel_snapshot (different output shape).

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

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

The description implies when this is the right tool (you want a newest-first retention/engagement comparison across Shorts), and it explains the authenticated vs unauthenticated data paths. However, it never explicitly says when to prefer a sibling such as yt_video_details or yt_channel_snapshot, so the agent must infer routing from the output format alone.

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 annotations: it discloses the ~51 quota unit cost, the OAuth2 authorization requirement, and the crucial fetch-then-merge behavior that preserves omitted fields rather than clearing them. It also flags the non-obvious side effect that publish_at forcibly overrides privacy_status to 'private', which an agent could not predict from the schema alone.

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?

Dense but front-loaded: purpose first, then prerequisites, then behavioral caveats, then return shape. Every sentence carries information, though the final sentence listing the return keys is redundant given an output schema exists.

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 7-parameter mutation tool with an output schema, the description covers authorization, quota cost, side effects, and merge semantics — everything an agent needs to call it correctly. Return values are documented in the output schema, so the brief mention of them is harmless surplus rather than a gap.

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 baseline is 3, and the description does consolidate the merge semantics (omitted params preserved) and the publish_at/privacy_status interaction into one readable statement. However, most of this detail — 'Leave omitted to keep existing', 'Forces privacy_status=private' — is already duplicated verbatim in the schema, so the added meaning is modest.

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 — 'partial, idempotent update on an existing YouTube video's metadata, visibility, schedule, or custom thumbnail' — and enumerates exactly which fields are touched. The word 'existing' implicitly separates it from yt_upload_draft, but no sibling is named explicitly, so an agent must infer the boundary rather than read it.

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

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

Gives clear operating context: channel-owner OAuth2 is required, and the underlying calls (videos.list + videos.update) with their quota cost are disclosed. It does not state when to prefer this over yt_video_details (read) or yt_upload_draft (create), so the exclusion guidance is inferential rather than 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?

Beyond the annotations, it discloses the ~1,600-unit quota cost, the required youtube.upload OAuth scope, the fact that a new video resource is created each call, and the exact return payload ({videoId, studioUrl, watchUrl, privacyStatus, publishAt}). It also explains the publish_at/privacy_status interaction and that inline fields override spec_path values, which the annotations do not cover.

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 dense but front-loaded, leading with the action, API call and quota before optional behaviors. The enumeration of return fields is slightly redundant given an output schema exists, but otherwise every sentence carries decision-relevant 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 15-parameter mutation with rich annotations and an output schema, the description supplies the remaining essentials: authentication scope, cost, idempotency consequences, default state, scheduling semantics and parameter precedence. An agent has enough to call it correctly without further exploration.

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 100%, so the schema carries most of the burden, but the description still adds real meaning by stating the precedence rule (inline title/description/tags/hashtags/pinned_comment override spec_path) and clarifying that publish_at overrides privacy_status. Those cross-parameter interactions are not expressed 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 a specific verb and resource ('Upload a local MP4/MOV video file to YouTube Studio'), plus the underlying API call (videos.insert) and the two optional side-operations (thumbnails.set, commentThreads.insert). It is clearly distinct from siblings like yt_update_video and yt_post_comment, which modify or comment on an existing video rather than create one.

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

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

It gives clear operating context: defaults to an unpublished private draft, and publish_at triggers scheduled release with privacy forced to 'private'. It does not explicitly say when to prefer yt_update_video or the dedicated yt_post_comment over the inline pinned_comment option, so the boundary with siblings is left implied rather than stated.

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 readOnly/idempotent annotations by disclosing the OAuth2 scope requirement, the studioDiagnosisError raised on a missing scope, and the fact that scraping is opt-in via a flag or environment variable. These are exactly the operational traits an agent needs before calling.

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-loads the core purpose and keeps every clause informative, but the enumerated list of return metrics is verbose and partly duplicates the output schema. Still tight for the amount of conditional behavior it must convey.

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

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

Covers identification, auth requirements, the opt-in gate for scraping, the optional words-alignment mode, and the error surface. With an output schema present, return value documentation is not required, so 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 100%, so the schema already explains video_id format, the force_public opt-in, and the words file purpose. The description largely restates those semantics in behavioral terms (what the words file unlocks, why scraping is gated) without adding format, defaults, or edge-case 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 ('Fetch') and a precisely bounded resource: metadata plus owner-authorized Analytics retention diagnostics for a single 11-character video_id. The output artifacts (retention curve, drop-off cliffs, peer percentiles, traffic sources) make it unmistakable against siblings like yt_channel_snapshot or yt_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?

Gives clear preconditions for use: retention/traffic diagnostics need channel-owner OAuth2, and public page scraping happens only when force_public=true or the env var is set. It does not, however, explicitly contrast itself with sibling tools or state when a caller should prefer yt_channel_snapshot instead.

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