TubeGrade

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds the economically important fact that the call is free and deducts nothing, which is real behavioral context in a credit-metered API and not derivable from the annotations.

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

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

The definition is short and front-loads the resource and the free-cost fact. It is mildly redundant, stating the zero-cost property three times ('free', 'deducts nothing', 'Cost: 0 credits (free)'), but the waste is small.

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 balance lookup with an output schema available to describe return values, the description covers everything an agent needs: what it fetches, when to call it, and that it does not consume credits.

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 per the baseline there is nothing the description must compensate for. It correctly adds no parameter narrative, which is the right call for a no-arg call.

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 first sentence names a specific resource (TubeGrade credit balance) and what it returns, which is unambiguous and clearly distinct from all siblings, none of which are balance-related. An agent can identify this tool 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?

It gives two concrete triggers: when the user asks how many credits they have, and before a large paid request. That's clear context, but no explicit exclusions or named alternatives are given (though the sibling list contains no competing balance tool, so little inference is needed).

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

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

Adds genuinely non-obvious behavior beyond the annotations: idempotency spelled out concretely ('saving twice, or removing one that isn't saved, changes nothing'), the folder-limit error contract, and a zero-credit cost statement. The annotations already carry destructive/idempotent/openWorld hints, and nothing here contradicts them, but permissions or concurrency behavior are not addressed.

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 the usage rule and cost in short, scannable sentences. The folder-limit error sentence is useful but sits oddly inside the purpose paragraph rather than with the constraints.

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 an output schema present, return values need no explanation, and the description covers the mutation semantics, idempotency, cost, and one error path. The main remaining gap is that it never clarifies that 'remove' is scoped to a single folder or what happens on permission/auth failure.

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

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

Schema description coverage is 100%, so the schema already explains video, action, and folder semantics; baseline is 3. The description only adds the side effect that an unknown folder is auto-created and that removal requires a folder, which is largely mirrored in the folder field's own description.

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

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

States a precise verb pair (save/remove) plus the exact resource (a YouTube video in one of the user's TubeGrade bookmark folders) and ties it to the visible product state ('the same saved videos the user sees in the TubeGrade app'). An agent can distinguish this from tubegrade_list_bookmarks or tubegrade_get_video 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?

Gives an explicit gating condition: 'Use only when the user asks to save, bookmark, or remove a video.' That is a clear when-to-use restriction, though it never names an alternative tool (e.g. list_bookmarks for reading) or states when not to use it, so it stops short of full routing guidance.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). Beyond that, the description adds real value: the credit cost model, default resolution, the max count, and the fact that failed fetches are noted inline. It stops short of describing output ordering guarantees or pagination behavior.

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

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

Front-loaded payload description, tight usage sentence, and cost statement last. Every sentence carries information 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?

No output schema exists, so the description correctly explains what is returned (thumbnail images preceded by video id, title, URL) and how failures surface. Combined with annotations and a fully documented schema, an agent has everything needed to invoke this correctly.

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

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

Schema coverage is 100% and the schema already documents limit, source, resolution, and channel_id formats in detail. The description reinforces some of this (default size, accepted id formats) but adds little beyond the schema, 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: retrieving a channel's video thumbnail images, with source selection (latest/popular/Shorts) and a cap of 30. Clearly distinct from siblings like tubegrade_thumbnails (likely single-video) and tubegrade_find_similar_thumbnails (search-oriented).

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

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

Explicitly names the use case: 'Use when the user wants to study a channel's thumbnail style,' and clarifies accepted identifier formats. It does not, however, contrast with sibling tools like tubegrade_thumbnails or find_similar_thumbnails, so an agent still has to infer the boundary.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds genuine value beyond that: per-video credit cost with a concrete worked example, and the partial-failure behavior where captionless videos return an `error` field rather than failing the whole request. It stops short of describing pagination or rate limits, keeping it at a solid 4.

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 what the tool returns, followed by when to use it, input formats, and a clearly demarcated COST line. Nearly every sentence earns its place, though the channel_id format restatement duplicates the schema and the cost/max-50 fact appears twice.

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 bulk-read tool, an agent has everything needed: what it returns, the partial-failure semantics, accepted identifier formats, the billing model, and the selection source. An output schema exists, so return-value documentation is not required, and the description still usefully flags the `error` field behavior.

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 limit (max 50), source (recent/popular) and channel_id formats are all already documented in the schema. The description largely restates these ('latest or most popular, up to 50', 'channel id (UC…), an @handle, or a channel URL') without adding syntax or edge-case detail, so the 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 (fetch full transcripts) applied to a specific resource (many of one channel's videos), with scope (latest or most popular, up to 50). The phrase 'many of one channel's videos at once' implicitly distinguishes it from the singular tubegrade_get_transcript sibling, and the [MM:SS] output format plus title inclusion make the deliverable concrete.

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 triggering scenario: 'Use when the user wants to study a creator's scripts, hooks or talking points across several videos.' It does not explicitly name the single-video alternative (tubegrade_get_transcript) or state when NOT to use this expensive bulk call, so the routing guidance is clear but not complete.

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 the safety profile (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds a genuinely non-obvious behavioral fact: the cost is 3 credits per call, plus the 100-item cap.

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 what it returns, then when to use it, then cost. Every sentence carries unique information with no repetition of the surrounding metadata.

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 list tool with an output schema and full schema coverage, the description covers trigger, scope, accepted identifiers and cost. It doesn't note limits on empty channels or result freshness, but nothing critical to invoking it correctly is missing.

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

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

Schema coverage is 100%, so the schema fully documents limit, source, and channel_id. The description restates the tabs and the accepted channel-id formats without adding syntax or semantics beyond the schema, 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?

The description gives a specific resource (a channel's videos) and scope (latest/most-popular/Shorts tabs, up to 100, with title/views/duration/publish time). It's clear what the tool returns, but it never names or contrasts a sibling like tubegrade_get_channel or tubegrade_search_videos, so differentiation must be inferred.

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?

"Use when the user wants to see what a channel has been uploading or its most-viewed videos" gives a concrete trigger condition mapped to the source tabs. There are no explicit exclusions or alternative-tool guidance, so it stops 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 readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the output carries phrases only with no search volume, competition or difficulty data, and the call costs 1 credit. Both are useful facts an agent cannot get from the annotations.

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

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

Three short blocks, each front-loaded with its key fact: what it returns, when to use it, what it costs. Zero filler; every sentence 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?

An output schema exists, so return-value documentation is unnecessary, and the description instead covers the two things that most affect correct invocation: the limited data types returned and the per-call credit cost. Nothing material is missing for a 1-parameter read 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 description coverage is 100% and the single 'query' parameter is already documented with an example in the schema. The description restates the seed-phrase concept and adds the ordering guarantee, but contributes no new syntax or format detail for the parameter itself, so the 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 and resource: YouTube autocomplete suggestions for a seed phrase, returned in YouTube's ranking order. It also scopes the result type sharply ('Phrases only'), which distinguishes it from any volume/difficulty tool an agent might assume exists.

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 trigger: 'Use when the user wants related search phrases or title wording around a topic.' That is a usable selection criterion. It stops short of naming an alternative or stating when not to use it, 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld). The description adds real context beyond them: the corpus is explicitly limited ('tens of thousands of breakout videos, not all of YouTube') and the cost is disclosed at 10 credits per call, which matters for a metered tool.

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 blocks - what it returns, when to use it, cost - each front-loaded with its key information. No filler and no repetition of schema details.

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

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

For a read-only search tool with an output schema, the description supplies everything an agent needs to decide and call: the corpus boundary, the semantics of the scoring fields, the available filters, the usage trigger, and the credit 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 100% and each parameter carries its own description, so the schema does the heavy lifting. The description restates the filter set and adds conceptual meaning to outlier_ratio ('times over the channel's baseline'), but adds little syntax or format 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 (semantic search) and resource (corpus of breakout videos about a topic), plus the defining mechanic: videos that beat their own channel's baseline. This distinguishes it from channel-scoped siblings like tubegrade_get_channel_outliers, which look per-channel rather than topic-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?

The 'Use when the user asks what is going viral or breaking out on a topic, or wants proven ideas to model' sentence gives clear triggering conditions. It lacks explicit exclusions or named alternatives (e.g. when to prefer tubegrade_search_videos), so it stops short of fully routing the agent.

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 that an unanalysed video incurs extra latency, that a not-ready analysis returns status 'indexing' and the same request succeeds in ~15 seconds, that nothing in the account or YouTube changes, and that the call costs 20 credits. Latency, async retry semantics and cost are exactly the operational details an agent needs.

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 what the tool returns, then usage, then edge-case behavior, then cost. Every sentence carries information an agent would otherwise have to discover by trial; 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?

An output schema exists, yet the description still summarizes the payload (views, outlier score, channel subscribers, average views), and covers the async indexing caveat and cost. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description's note about accepting an 11-character id or a YouTube URL mirrors the video_id schema description rather than adding new 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 precise operation — returning videos whose thumbnails look/read like a reference video's — and even discloses the ranking formula (60% visual, 40% title). This clearly separates it from siblings like tubegrade_thumbnails, tubegrade_search_videos and tubegrade_similar_channels.

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 concrete use case: 'when the user wants videos packaged like a reference video, or the thumbnail and hook patterns around it.' That is clear context, but it does not name an alternative tool or state when NOT to use this one versus e.g. tubegrade_thumbnails.

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 past the annotations (readOnly, idempotent, openWorld): it discloses the credit cost (5 per call), the public-data-only constraint excluding YouTube Analytics metrics, and the conditional presence and semantics of the `growth`/`gained` block (per-period change averaged over sparse readings). These are meaningful behaviors not captured by structured fields.

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 return contents, then conditional behavior, then usage and cost. Dense but every clause carries information; the growth-block sentence is slightly involved but justified for interpreting results.

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?

An output schema exists, yet the description still clarifies the otherwise ambiguous `growth`/`gained` semantics and adds cost and data-scope context. For a read-only single-param stat tool, nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is 100% and there is a single parameter, so the schema already documents accepted formats. The description echoes the id/@handle/URL forms without adding new syntax or constraints, 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?

Specific verb+resource ('Stats for one YouTube channel') with an enumerated return set (subscribers, views, videos, avg views, upload frequency, length, country, description). It is clearly distinguishable from siblings like tubegrade_channel_videos or tubegrade_channel_transcripts, which fetch content rather than aggregate stats.

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?

Explicit when-to-use ('Use when the user asks how big a channel is, how it is growing, or what its typical video gets') and a clear boundary exclusion ('Public data only: no private YouTube Analytics'). No sibling alternative is named for adjacent needs, so it falls short of 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?

Annotations already declare readOnly, idempotent, non-destructive, openWorld, so the safety profile is covered. The description adds genuinely new behavioral facts: the empty-result case ("Empty when the channel has no flagged outliers") and an explicit per-call cost of 10 credits — the credit cost is not derivable from any structured field.

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

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

Three short, front-loaded blocks: what it returns, when to use it, and cost. No filler sentences and no restatement of the title beyond the opening scope phrase.

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, two-parameter tool with an output schema already present, the description covers the remaining gaps an agent needs: the meaning of "outlier," a usage trigger, the empty result, accepted identifier formats, and cost. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents both channel_id and limit including the accepted id/handle/URL forms. The description repeats the same identifier formats without adding syntax or validation detail, 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 resource and scope — "One channel's breakout videos" — and then defines the term operationally ("uploads that beat that channel's own typical views"), plus the sort order and returned fields. The channel-scoped framing implicitly separates it from the global tubegrade_find_outliers sibling.

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 concrete trigger: "Use when the user asks what worked best for a specific channel." That is clear usage context, but it names no exclusions and does not point to tubegrade_find_outliers for cross-channel or all-channel outlier questions, which is the most likely sibling confusion.

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 read-only/idempotent/non-destructive/open-world, and the description still adds value: replies are excluded, the list is empty when comments are disabled, sort semantics, and a 5-credit cost per call. The disabled-comments and cost disclosures are exactly the behavioral context an agent can't infer 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?

Three short paragraphs: what/return shape first, then when-to-use, then cost. Each sentence earns its place with no filler or repetition of the schema.

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 an output schema present, return values needn't be re-explained, and the description still covers scope, sort behavior, reply exclusion, disabled-comment edge case, input formats, and cost. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100%, so sort/limit/video_id are fully documented in the schema. The description restates 'most relevant or newest first, up to 100' and 'accepts an 11-character video id or a YouTube URL' but adds no syntax or format detail beyond what the schema already provides; 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 (get) and resource (top-level comments on a YouTube video), plus the returned fields and the scope (up to 100, top-level only). No sibling competes for comments, and the 'top-level, replies not included' framing pins the resource precisely.

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?

'Use when the user wants audience reactions, questions or requests about a video' gives clear positive context for selection. It stops short of naming when-not-to-use or a specific alternative sibling (e.g. get_transcript for transcripts), so it lands just below the top tier.

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 (readOnly, idempotent, non-destructive, openWorld), so the bar is lower. The description adds genuinely useful context beyond them: the error behavior when captions are absent and the 10-credits-per-call 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?

Front-loads what is returned, then usage triggers, then accepted input, then cost. Four tight sentences with no filler, each carrying distinct 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 single-input read tool with full schema coverage, an output schema, and rich annotations, the description covers return format, failure mode, usage triggers, and cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100% and the single parameter's accepted forms (11-char id or URL) are already documented in the schema. The description restates this acceptance without adding format or validation detail, so the 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 and resource (transcript/captions) and even the output shape (one `[MM:SS]` timestamped line per cue). The phrase 'one YouTube video' implicitly separates it from the channel-level sibling `tubegrade_channel_transcripts`, but no sibling 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 clear when-to-use triggers: reading, summarizing, quoting what a video says, or studying hook and structure. No when-not conditions or explicit alternative routing are provided, 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?

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses materially useful traits: the conditional `growth` block that 'many videos have none yet', the data boundary 'public data only: no watch time, retention, CTR or traffic sources', and an explicit cost of 5 credits per call. Cost and conditional-return disclosure are exactly the kind of behavior annotations cannot 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?

Three tight sentences with the primary purpose front-loaded, followed by usage context, data limits, and cost. 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?

An output schema exists, so return values need not be detailed, yet the description still flags the optional `growth` block and its absence case. Data-scope limits and pricing complete the picture for a read-only lookup 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 description coverage is 100% and the single parameter is fully documented in the schema ('11-char YouTube video id or a YouTube video URL'), which the description merely restates. Baseline 3 is appropriate since the schema carries the parameter 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+resource ('Stats for one YouTube video') and enumerates the returned fields (title, channel, views, likes, comment count, duration, publish date, tags, category). This distinguishes it from sibling channel-level tools like tubegrade_get_channel without the agent needing to open a 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?

Explicitly says to use it 'when the user asks about a specific video's performance', which is a clear selection context and implicitly excludes channel/ranking tools. It does not name a competing sibling (e.g. tubegrade_channel_videos or tubegrade_search_videos) as the alternative for the non-specific case, so it stops 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, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds value beyond that: result ordering ('newest first'), the per-item shape, and the explicit cost disclosure '0 credits (free)', which is not derivable from any structured field. That is real added context, though nothing about limits or pagination.

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 segments: what it returns, when to use it, and its cost. The output description is front-loaded and the parenthetical packs ordering and per-item fields without a wasted clause. Nothing repeats and nothing is 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?

An output schema exists, so return values need not be explained, and the annotations cover safety. The description still conveys modes, ordering, and cost. The only meaningful gap is scale behavior (how many bookmarks come back, whether results are truncated or paginated), which matters for a user with a large saved backlog but is not addressed here.

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% – both 'show' and 'folder' are fully documented in the schema, including the enum values and the case-insensitive folder-name semantics. The prose ('one folder or all folders') restates the schema's own scoping note rather than adding syntax or edge-case detail. Baseline 3 applies when the schema carries the parameter 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?

States a concrete verb+resource (list the user's saved YouTube videos) and explicitly covers both output modes: saved videos or bookmark folders with counts. It also pins down ordering ('newest first') and per-item payload ('its folder and save date'), which is unusually specific. An agent can distinguish this from the sibling write tool tubegrade_bookmark without opening either 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 gives explicit trigger conditions: 'Use when the user asks what they have saved or which folders they have.' That maps intent to tool cleanly. It stops short of naming an alternative (e.g., tubegrade_bookmark for adding) or stating when not to use it, so it is clear context rather than full routing guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds two things annotations cannot: the empty-state behavior ("Empty when they track none") and the credit cost per call, which is operationally important for a credit-metered API.

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 with no waste: the returned content is front-loaded, the usage trigger follows, and the cost is stated last. No sentence could be removed without losing real 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 no-parameter, read-only list tool with a declared output schema, the description covers everything an agent needs: what the tool returns, when to call it, what an empty result means, and what it costs. The output schema handles return-value 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?

The tool takes zero parameters, so there is no argument semantics to document and the baseline is 4. The description goes slightly further by describing the shape of the returned data fields, even though the output schema already carries that detail.

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 — the competitor channels the user tracks in TubeGrade — and enumerates what each entry contains (subscribers, average views, 7/30-day changes). That is enough to distinguish it from discovery tools like tubegrade_similar_channels or tubegrade_search_videos, though it never explicitly names a sibling 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?

"Use when the user asks how their tracked competitors are doing" gives a clear trigger condition tied to a user intent. It does not, however, state when not to use it or point to a complementary tool (e.g., track_competitor to add entries, or similar_channels for discovery), so the routing picture is incomplete.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses the coverage limitation (only channels TubeGrade tracks, with `tracked_channels` giving the count, not all of YouTube), the absence of topic filtering, and the concrete error behavior for an unavailable region. The '1 credit per call' cost note is another trait 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?

Front-loaded with the core purpose, then output fields, then scope caveats, then usage, then cost — a sensible progression. It is dense but almost every sentence adds information; the one redundant passage is the restatement of the `list_type` semantics already present in the schema.

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?

Despite an output schema and full annotation coverage, the description still supplies the return-field semantics, the coverage caveat, the region-error behavior, and the credit cost. Nothing an agent needs to select or invoke this tool correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds real meaning: `previous_rank` is null for new entries, `gained_30d_text` is rounded to YouTube's published precision, and a bad `region` produces an error listing valid regions. The `list_type` definitions largely duplicate the schema's enum description, which caps this at 4 rather than 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?

The description names a specific resource (TubeGrade's weekly YouTube channel rankings) and precisely defines the three list variants, including the qualifying thresholds for each (100K+ for fastest-growing, 50K–2M start for breakout). An agent can distinguish this from sibling tools like tubegrade_search_videos or tubegrade_find_outliers 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?

It gives an explicit trigger: 'Use when the user asks about the fastest-growing, breakout or biggest YouTube channels.' That is clear positive guidance, but it names no alternatives or exclusions (e.g. it doesn't say to use tubegrade_find_outliers or tubegrade_search_videos for other kinds of 'top channel' questions), so routing is left partly to inference.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds genuinely non-redundant context: 5 credits per call, the fact that channel fields are omitted when a channel can't be resolved, and the exact meaning of derived metrics like outlierRatio. These are behaviors an agent cannot infer from the schema or 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?

Front-loaded with purpose and filters, then return fields, then usage guidance and cost. It is on the long side for a search tool, but nearly every clause carries distinct information; only the subscriberCountText formatting example is arguably expendable.

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-param tool with an output schema, the description still explains field semantics (outlierRatio with a concrete 5.0 example), the degenerate case (unresolvable channels), and the credit cost. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% and three params are enums with defaults, so the schema fully documents inputs. The description references `limit` and the filter dimensions but adds no syntax or format detail beyond what the schema already states, 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?

Opens with a specific verb+resource+scope: 'Live keyword search across YouTube, with filters for long-form or Shorts, upload window and duration.' The closing line 'Results include all matching videos, not only breakouts' implicitly distinguishes it from tubegrade_find_outliers, so an agent can route correctly.

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?

'Use when the user wants videos on a topic or a scan of what is being published in a niche' gives clear usage context, and the breakout caveat hints at the alternative. It stops short of explicitly naming find_outliers or stating when-not-to-use, so it's 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?

Adds substantial context beyond the readOnly/idempotent/openWorld annotations: the 0.3x-3x subscriber size band, only close matches returned (so few or none is normal), a tubegrade_url in each result, a weekly rebuild cycle, an error path for unfingerprinted channels that does not charge, and the credit cost. This is exactly the behavioral detail the 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-loaded with the what, then the constraints, then the when-to-use and cost. Every sentence carries information, though the fingerprint/category/country detail is dense and the usage line is separated from the purpose by a behavioral paragraph.

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?

An output schema exists so return values need no explanation, and the description still flags the tubegrade_url field. For a read-only, idempotent, two-parameter lookup with rich behavioral notes, nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including that channel_id accepts UC ids, @handles, or URLs. The description's 'Only close matches are returned, so broad or unusual channels can get few or none' gives useful context on why limit may not be satisfied, but it does not add new syntax or format meaning.

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 ('Channels that cover the same topic as a given channel and are a similar size') and defines the matching mechanism (topic fingerprints of name/description/tags, category and country bias). This clearly separates it from siblings like tubegrade_find_similar_thumbnails and tubegrade_get_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?

Explicitly says 'Use when the user asks who their competitors are or for channels like a given one,' plus states the 5-credit cost and the error-without-charge condition for unfingerprinted channels. It does not name the nearest alternative (tubegrade_my_competitors) or explain when to prefer it, which keeps this from 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 cover readOnly/idempotent/openWorld/destructive=false, and the description adds substantial context beyond them: the outlierRatio definition, the caveat that large ratios on old videos signal back-catalog hits rather than fresh breakouts, and the explicit cost of 5 credits per call.

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 core purpose and the returned-field list are front-loaded, and the outlierRatio/back-catalog explanation earns its place by aiding interpretation. The middle sentence is dense but not redundant; only minor tightening 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?

With an output schema present, return values need not be explained, yet the description still clarifies the most confusing field (outlierRatio) and its interpretive caveat. Cost is disclosed and safety is covered by annotations, leaving nothing an agent needs missing.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the 11-char id or URL format restated in the description. The description adds no syntax or format detail beyond the schema, so the 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 states a specific verb and resource: 'The videos YouTube itself suggests next to a given video (its "Up next" rail)'. It also enumerates the returned fields (views, publish time, channel, subscriber count, average views, upload frequency, outlierRatio), making the resource unmistakable against siblings like find_outliers or similar_channels.

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 explicit when-to-use guidance: 'Use when the user asks what YouTube recommends alongside a video, or which channels compete around it.' However, it names no alternatives or when-not conditions, so routing against sibling tools is left to inference.

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 safety (readOnly, idempotent, non-destructive, openWorld), and the description adds real operational context beyond them: resolution tiers (1280×720 vs 480×360), the summary reporting how many were smaller, inline notation of unfetchable thumbnails, and a per-video credit 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?

Front-loaded with what is returned, then usage, then cost as a clearly labeled line. Every sentence carries information; only the opening sentence is slightly over-packed, and it is efficient overall.

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-format burden and does so: per-video id + image URL, resolution fallback, count of smaller thumbnails, and failed-fetch handling. Cost and input format are both covered, leaving nothing an agent needs 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% and the single parameter is fully documented in the schema itself, including the 11-char id / URL formats and the max of 10. The description restates these (11-character ids, URLs, up-to-10) but adds no syntax or format detail the schema lacks, 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 concrete resource and scope: thumbnail images for specific videos, up to 10, from any channels. The 'from any channels' clause implicitly separates it from the channel-level sibling, but it never names tubegrade_channel_thumbnails, so the 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?

"Use when the user wants to see or compare the thumbnails of particular videos" gives a clear trigger condition. There is no exclusion guidance pointing to tubegrade_channel_thumbnails for whole-channel requests, so the agent must infer that boundary.

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

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

Beyond the annotations (which already declare idempotent=true and destructive=false), the description discloses the entitlement requirement (only accounts with competitor tracking), the capacity limit and that the error reports fullness, the daily async refresh behavior, and the cost (0 credits). This is unusually rich operational context for a mutation tool.

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?

Six short sentences, each carrying distinct information — effect, idempotency, capacity, entitlement, usage restriction, accepted inputs, cost — with the primary 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?

An output schema exists, so return values need not be explained, and the description covers everything else an agent needs: preconditions, side effects, idempotency, capacity behavior, and cost. Nothing material 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 documents the single 'channel' parameter. The description restates the accepted formats (UC id, @handle, URL) without adding format constraints, validation rules, or failure modes beyond what the schema says, 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?

The description states a precise verb and resource — adding a channel to the user's tracked competitors — and immediately describes the consequence (daily refresh building subscriber/view history). This clearly distinguishes it from siblings like tubegrade_my_competitors (read) and tubegrade_untrack_competitor (remove).

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 an explicit invocation condition: 'Use only when the user asks to track, follow or add a competitor.' That is a clear when-to-use with an implied exclusion, but it never names the adjacent siblings (my_competitors, untrack_competitor) or the inverse case, leaving a little routing inference to the agent.

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 and idempotentHint, and the description adds genuinely new context: the scope of destruction is limited to the tracking relationship ('the channel's public data is not affected'), the no-op case is surfaced to the caller, and the cost is stated as 0 credits. It does not describe auth/permission requirements, 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?

Four short, front-loaded statements — effect, limitation, usage condition, accepted input, cost — with no filler or redundancy in the prose itself.

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?

An output schema exists so return values need no explanation, and the description covers the operation's side effects, no-op behavior, input forms, and cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100% and the single parameter already documents the accepted formats, so the description's restatement of channel id/@handle/URL adds no meaning beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb (remove/untrack) and resource (a channel from the user's tracked competitors), and its counterpart tubegrade_track_competitor in the sibling list makes the direction of the operation 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?

'Use only when the user asks to stop tracking or remove a competitor' gives an explicit selection condition and implicitly excludes other cases. It never names tubegrade_track_competitor or tubegrade_my_competitors as the alternative, so the routing guidance stops just short of fully explicit.

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

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

With annotations already covering readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, the description adds genuinely useful context beyond that: the cross-niche mining behavior, the fallback-with-note behavior for niche-less filters, and an explicit cost ('5 credits per call'). It does not, however, describe rate limits, pagination, latency, or caching behavior.

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

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

Front-loaded purpose sentence followed by compact supporting details; the cross-niche fallback sentence and the cost line are each informative and non-redundant. Slightly dense in the middle sentence, but every sentence earns its place.

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

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

For a read-only analytics tool with a full output schema, 100% schema coverage, and rich annotations, the description supplies the key behavioral context (cross-niche mining, niche fallback with note, cost). It omits rate limits and pagination behavior, which are the main remaining gaps for an agent to call it confidently.

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

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

Schema description coverage is 100%, so the schema already fully documents all five parameters, including enum values and defaults. The description restates the response field set but does not add parameter-level meaning beyond what the schema provides. Baseline 3 is appropriate when the schema does the heavy lifting.

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 resource ('recurring title or thumbnail formats that repeatedly produce breakout videos') and how they are derived ('clustering and AI labelling'). Enumerates the concrete fields returned (label, template, lifecycle state, strength score, hit rate, member count, trend, examples), which clearly distinguishes it from sibling tools like tubegrade_thumbnails or tubegrade_rankings.

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 explicit when-to-use guidance ('Use when the user wants proven title or thumbnail patterns to model'). However, it does not name any alternative sibling tools or state when NOT to use this tool, leaving the agent to infer the boundary against tools like tubegrade_find_outliers or tubegrade_thumbnails.

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