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

Annotations already declare readOnly/openWorld/idempotent/non-destructive, so the bar is lower, and the description still adds real value: the Open Graph data source (implying data may be sparse for profiles with restricted OG tags) and an explicit cost model of 1 credit per successful call with failed calls refunded. Rate limits and behavior on missing/private profiles are not covered.

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 lines, front-loaded with what is returned, followed by cost and the return shape. No filler sentences; the dense return-field list is justified because no 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?

With no output schema, the description compensates by enumerating every returned field and its nullability, plus cost and data provenance. For a one-parameter read-only scraper this covers everything an agent needs before invoking it.

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 'username' parameter already documents accepted forms (vanity name, numeric ID, or facebook.com URL) with an example. The description adds nothing about the parameter, so this sits at the baseline for a fully 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?

States a specific resource (public Facebook Page/profile metadata) and enumerates the exact fields returned (name, bio, image, like/follower counts). The platform is unambiguous and separates it from the instagram_profile / x_profile / tiktok_profile siblings by name alone, though the description never explicitly contrasts them.

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

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

Usage is implied rather than stated: an agent can infer 'call this when you want Facebook profile metadata', and the '(for Pages)' qualifier hints that count fields only apply to Pages. There is no explicit when-to-use, no exclusions (e.g. private profiles), and no pointer to sibling tools for posts or comments.

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 value beyond that: it discloses the exact response contents (email, plan, credits, rate/concurrency limits) and that the call consumes no credits, which is a real behavioral trait. It stops short of stating what happens with an invalid or expired key.

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. The resource and returned fields are front-loaded, and the cost note is a compact trailing qualifier.

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?

There is no output schema, so the description carries the burden of describing the return value — and it does so by naming the key fields. For a zero-parameter read tool with annotations covering safety, this is nearly complete; only error/auth-failure behavior is 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?

The tool takes zero parameters and the description correctly does not invent any. With no inputs to explain, the baseline for this dimension 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?

Uses a specific verb ("Show") on a specific resource ("the current API key's account") and enumerates the fields returned: email, plan, remaining credits, rate/concurrency limits. This is clearly distinct from the sibling scraping endpoints, though it does not explicitly name or exclude any of them.

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

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

"Free (no credits)" gives a concrete condition for calling it — useful before running credit-consuming scrapers to check remaining balance and limits. There is no explicit when-not guidance, but with zero siblings offering account data the alternative space is effectively empty.

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 openWorld, so the safety profile is covered. The description adds genuinely new behavior: pricing at 1 credit per successful call with failed calls refunded, a hard 15-comment ceiling, and a nullable comment_count plus has_more flag. It stops short of explaining pagination semantics for has_more, which keeps it from a 5.

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

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

Three tight lines: scope first, then cost, then input rule, then return shape. Every sentence carries information, and the return-type enumeration is necessary because no 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?

With no output schema, the explicit field list (shortcode, link, comment_count, comments, comments_fetched, has_more) is exactly what an agent needs to plan around the response. The main residual gap is that it does not warn the agent that a failed or empty result is charged differently, or clarify what drives has_more.

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 url, shortcode and limit in more detail than the description. The description's 'Provide one of: url OR shortcode' merely restates the schema's own constraint and it says nothing about limit, 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 and resource: 'the most recent comments (up to 15) on an Instagram post or reel by URL or shortcode'. The 15-comment cap and the accepted identifiers make the scope unambiguous, and it is plainly distinct from sibling tools like instagram_post or instagram_reel that fetch post-level data.

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 the input selection rule ('Provide one of: url OR shortcode') and a cost model, which implies usage, but never states when to pick this over instagram_post/instagram_reel or that it returns only top-level logged-out comments. No explicit when-not or alternative routing is provided.

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, so the safety profile is covered. The description does add genuinely useful non-schema behavior — 2 credits per successful call with refunds on failure, a hard cap of 60 posts, and nullable/optional fields flagged as such. However it says nothing about what happens with private profiles or how has_more/posts_source behave, which are the behaviors an agent actually needs to interpret results.

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?

Purpose is front-loaded, then cost, then returns, which is a sensible order and contains no filler prose. The return-value list is long, but since no output schema exists it is doing real work rather than 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?

It compensates well for the missing output schema by enumerating every returned field, and it discloses pricing and post limits. What it omits is the sibling boundary (profile-only vs profile+posts) and error/private-account behavior, which for a paid, open-world scraper is a meaningful 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 coverage is 100% and both parameters are self-documented with examples, so the baseline applies. The description adds only an indirect hint — the 'up to 60' ceiling implies limit is bounded server-side — but does not explain limit's default, or that username accepts a handle or URL (the schema carries that).

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 concretely what the tool returns: a profile object plus up to 60 recent posts with type, caption, thumbnail and engagement counts. That is clear enough to understand the resource, but it never distinguishes this from the sibling instagram_profile, which by name sounds like the same thing — the 'plus posts' delta is buried rather than contrasted.

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 at all: nothing says to pick this over instagram_profile or instagram_post, and no prerequisites (private accounts, rate limits) are mentioned. The only contextual note is pricing, which is not usage guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered without prose. The description adds genuinely new behavioral information: a pricing rule ('Cost: 1 credit per successful call, failed calls are refunded'), which tells the agent retries are cheap and failures are not billed. It does not disclose behavior for private or deleted posts, 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?

The purpose and cost are correctly front-loaded in the first two lines, which is good structure. However, the description then dumps roughly twenty return fields as one flat comma-separated block, which is hard to scan and would read better as a compact summary or omitted entirely in favor 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 only two optional parameters and no output schema, the description carries the return-shape burden and does so by enumerating every field, including nullability. It is nearly complete; the notable omission is any explanation of the nested 'media' array for albums or what the 'type' and 'product_type' string values signify.

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%, with both parameters documented including examples and the alias precedence ('shortcode; alias used only when url is empty'). The description's restatement of 'provide one of url OR shortcode' adds nothing beyond the schema, so the baseline of 3 is appropriate.

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

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

The description opens with a specific verb-and-resource pairing ('A single Instagram post/reel by URL or shortcode') and enumerates exactly what data it returns, so an agent knows this fetches one media item with its full metadata. It loses a point because it never distinguishes itself from the close siblings instagram_reel and instagram_photos, which appear to cover overlapping ground.

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 only guidance is a parameter rule ('Provide one of: `url` OR `shortcode`'), which restates the schema rather than explaining when to pick this tool. There is no statement of when-not-to-use it or which sibling to choose for a reel, a photo album, or a comment listing, all of which exist in the sibling set.

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: a 1-credit cost with refunds on failed calls, which an agent cannot infer from structured fields. It stops short of describing failure modes (private account, rate limit) or latency.

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 cost, then returns — a sensible order for an agent scanning quickly. The return-field enumeration is long but earns its place because no output schema exists. Minor trim possible where both profile_pic_url and profile_pic_url_hd are listed with identical nullable typing.

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 contract itself and does so field-by-field with types and nullability, plus credit cost. What is missing is edge-case behavior: whether private accounts return partial data, and what a failed/refunded call looks like to the caller.

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 username parameter is documented with accepted forms (@handle, plain username, profile URL) and an example. The description adds nothing about the parameter beyond the schema, 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 names a specific resource (public Instagram profile) and enumerates exactly what it carries — bio, avatar, verification/business flags, follower/following/post counts, highlights. That field list cleanly separates it from siblings like instagram_photos, instagram_post, or instagram_comments, which return content rather than account metadata.

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: the resource name and returned fields make it obvious you call this when you need account-level metadata rather than posts. There is no explicit 'use this instead of instagram_photos when...' routing, no mention of what happens for private or nonexistent accounts, and no prerequisites 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open world), yet the description adds genuinely new behavior: a cost model of 1 credit per successful call with failed calls refunded, plus a complete field-by-field return contract including which fields can be null. It does not explain failure modes (private/deleted reels) or what video_url_expires_at implies for downstream use, which keeps it short of a 5.

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

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

The cost and argument lines are tight and front-loaded, but the bulk of the description is a long comma-free run of field names with repeated '(string, nullable)' annotations that reads like a dumped schema rather than a curated summary. It earns its place somewhat (no output schema exists), yet it could have been compressed into grouped categories.

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 return-field enumeration is necessary and the description supplies it in full; both parameters are covered and the cost/refund behavior is disclosed. The remaining gap is error behavior and freshness (video_url_expires_at is listed but its consequence is unexplained), which an agent handling retries would want.

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 both parameters already carry examples and precedence rules (shortcode 'used only when url is empty'). The description's 'Provide one of: `url` OR `shortcode`' merely restates the schema-level description, adding no new syntax or format meaning beyond it, so the 3 baseline 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 opens with a specific resource and scope: 'A single Instagram reel by URL or shortcode', then enumerates the data returned (owner, caption, likes, duration, MP4 link). The word 'single' implicitly separates it from the sibling list tool instagram_reels and the search tool instagram_reels_search, but those siblings are never named, 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?

There is argument-level guidance ('Provide one of: `url` OR `shortcode`') but no when-to-use guidance at all: nothing says when to pick this over instagram_reels, instagram_reels_search, or instagram_post, and no exclusions or prerequisites are stated. The credit cost is a useful constraint but is not a usage 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 declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely non-structured behavior: a cost of 2 credits per successful call with refunds on failure, and a hard ceiling of 50 reels. It does not explain what happens for private accounts or whether a partial 'has_more' result still consumes full credits.

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 front-loaded with the resource and scope, then splits cost and return shape into their own labeled sections, which is easy to scan. The Returns block is dense but each field maps to real output; the parenthetical field list in the first sentence partially duplicates the Returns line.

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 explicit Returns block is necessary and well chosen, covering profile fields, the reels array, reels_fetched and has_more. The remaining gap is that has_more is listed without explaining pagination (whether a larger limit or a cursor is needed) and credit/refund behavior on partial results is unstated.

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% on both parameters, so the schema already carries username formats and limit semantics, making 3 the baseline. The only added meaning is the implicit cap of 50 reels on 'limit', which the schema's bare 'minimum: 0' does not express — useful but marginal.

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: an Instagram profile's Reels tab, capped at 50 reels, with the per-reel fields it returns (views, likes, comments, cover image, approximate publish time) plus profile basics. That clearly separates it from the single-item 'instagram_reel' and from 'instagram_reels_search', but the description never names those siblings, 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?

Usage is implied by the resource name — use this when you have a username and want that profile's reels. There is no explicit statement of when to prefer 'instagram_reels_search' (search by keyword/hashtag) or 'instagram_reel' (single reel), and no note about private or non-existent profiles, so an agent must infer the 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?

Beyond the read-only, non-destructive annotations, it discloses the two-stage search-and-open behavior, the external search-engine dependency, and the specific per-reel data retrieved. It also gives unusually useful operational billing details: 3 credits per successful call and refunds for failed calls.

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

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

The purpose and retrieval behavior are front-loaded, followed by compact cost and return-value information. Although the first sentence contains a long field list and the return line is dense, both provide useful information without filler or repetition of annotations.

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?

Together with the fully documented input schema and safety annotations, the description supplies enough mechanism, cost, pagination-related output, and result information for reliable invocation. Because there is no output schema, its treatment of the nested reels objects remains incomplete: the first sentence lists available data but not exact object keys, types, or nullability.

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 schema already explains query, page, limit, and date_posted, including constraints and examples. The description reinforces the keyword-search purpose but adds little parameter-specific meaning beyond those structured descriptions, so the high-coverage baseline 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 clearly states the verb and resource: finding Instagram reels by keyword through search-engine results, then retrieving detailed information for each reel. The search-engine mechanism and field list clarify its scope, although it does not explicitly distinguish itself from siblings such as instagram_reel or instagram_reels.

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 provides a clear use case: keyword-based reel discovery followed by detailed retrieval, rather than merely implying a generic Instagram search. It does not explain when to prefer a sibling tool or when this indirect search-engine approach is unsuitable.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower. The description still adds real value beyond them by disclosing that listing is 'Free' (no credit spend, unlike the actual scraper calls) and by naming the metadata each entry carries, including 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?

Two short sentences: the first front-loads what is returned, the second covers cost and the optional filter. Every clause carries information and nothing is padded.

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

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

With no output schema, the description correctly compensates by enumerating the fields returned per scraper. For a single optional-parameter, read-only listing tool, nothing an agent needs in order to call it 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 optional platform parameter is fully documented in the schema. The description only restates the filter with the same example given in the schema, adding no new syntax or matching semantics, 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 ('List the available scrapers') and enumerates the returned fields (platform, action, tool name, credit cost, parameters). This clearly distinguishes it from the many sibling action tools like instagram_profile or tiktok_posts, which perform scraping rather than describe 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?

The 'Free' note and the optional platform filter with an example ('e.g. "instagram"') make the intended discovery use case clear. It stops short of explicitly saying 'call this before invoking a scraper tool' or naming when not to use it, so it falls just short of full guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=true, so safety is covered. The description adds genuinely new behavioral context: an explicit cost of 2 credits per successful call with refunds on failure, and the 'public' scope restriction on which boards are reachable. It stops short of describing pagination semantics for `has_more` beyond listing the return keys.

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 segments — resource contents, cost, parameter requirement, return shape — with no filler sentences. The return-key list is compact and skimmable. Slight redundancy in restating the one-of parameter rule that the schema already enforces.

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 compensates by enumerating the return keys (board, pins, pins_fetched, has_more) and describing what the board object contains. Cost and the public-only scope round it out. The remaining gap is sibling disambiguation — nothing tells an agent why to pick this over pinterest_pins for a board's pins.

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% — every parameter already carries an example and explanation, including the /<username>/<board>/ URL format and the ~25-pin logged-out cap on `limit`. The description only repeats the one-of requirement that the schema's own object-level description already states, adding no syntax, default or format detail beyond it. Baseline 3 applies when the schema does all 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?

The description gives a specific verb-plus-resource picture: it names the resource (a public Pinterest board) and enumerates exactly what is returned — name, description, pin/follower/section counts, owner, cover image, plus first pins with images, links and engagement. That is far more concrete than a restatement of the title. It loses a point because it never distinguishes itself from the close siblings pinterest_pins and pinterest_profile, which plausibly surface overlapping data.

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 line 'Provide one of: `url` OR `username` + `board`' gives real invocation guidance about which parameter combinations are valid. However, there is no statement of when to reach for this tool rather than pinterest_pins, pinterest_profile or pinterest_search, and no exclusions or prerequisites beyond the 'public' qualifier. Usage is implied rather than directed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds genuinely new behavior beyond those annotations: a per-call cost of 1 credit with refunds on failure, plus a full field manifest, which matters because there is no output schema to disclose the shape of a result.

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?

Structure is front-loaded: identity of the resource, then cost, then the invocation rule, then the return fields. The long return list is verbose but justified, because there is no output schema and it is the only way the agent learns what comes back.

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

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

For a two-parameter, zero-required read tool with no output schema it covers the essentials: the accepted identifier forms, a stated exclusivity rule, a cost model and the complete response field list. Only mapping to the sibling list and board tools is left 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 description coverage is 100%, including an example URL and pin ID format, so the schema does the heavy lifting. The description restates the mutually exclusive 'url OR id' rule without adding format, precedence or normalization details beyond what the parameters already say, making the baseline 3 correct.

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 and envelope: a single Pinterest pin fetched by URL or ID, with an enumerated set of fields (title, description, image/video, outbound link, engagement counts, board, pinner). The word 'single' implicitly separates it from the plural pinterest_pins sibling, but no sibling is named explicitly, so this 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?

The only guidance is the input contract 'Provide one of: url OR id', which is an invocation rule rather than a when-to-use rule. Nothing tells the agent when to reach for pinterest_pins, pinterest_search or pinterest_board instead. For a straightforward single-entity lookup this is implied but not 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuinely new context the annotations cannot: a cost of 2 credits per successful call with refunds on failure, which is operationally important for an agent deciding whether to call. It stops short of explaining what happens on a private/nonexistent profile or how to page beyond the 50-pin 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?

Front-loaded with purpose, then cost, then a return-field inventory — a sensible order for a tool with no output schema. The long enumeration of return fields is justified by the absence of a structured output schema, though it is dense and could have been grouped by type rather than listed flatly.

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 field-by-field Returns list does the necessary work of telling the agent what comes back, and cost plus the 50-pin ceiling round out the operational picture. The remaining gap is pagination and error behavior: has_more is returned but there is no cursor parameter, so an agent cannot tell whether more pins are reachable or how.

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 documented, giving a baseline of 3. The description adds one real piece of meaning the schema lacks: pins are capped at 50 regardless of the requested limit, a constraint the schema does not encode (limit has only a minimum of 0 and no maximum).

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 clause names the exact resource and scope: 'A Pinterest profile plus its recent pins (up to 50) with images/videos, titles, descriptions, links and engagement counts.' That is specific enough to separate it from pinterest_pin (single pin) and pinterest_profile (bare profile), but it never names those siblings explicitly, so the differentiation is inferred 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 at all: no mention of when to prefer pinterest_profile, pinterest_pin, pinterest_search or pinterest_board, and no prerequisites or failure conditions. The only hint is the 'plus its recent pins' framing and the 50-pin cap, which implies usage but does not guide selection.

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 behavioral context: the cost model (1 credit per successful call, failed calls refunded), which affects how freely an agent retries or fans out calls. It also notes that several fields may be null, hinting that sparse or private profiles return partial data.

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 tightly packed lines: purpose, cost, return fields. The return enumeration is long but justified because no output schema exists, and the purpose is front-loaded ahead of the cost and field list.

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

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

With no output schema, the description correctly compensates by listing every returned field and its type/nullability, and it discloses the credit cost. The only gap is operational guidance on failure modes for private or missing profiles, which is a minor omission for a single-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 coverage is 100% and the single 'username' parameter is already documented with accepted forms (@handle, profile URL) and an example, so the baseline of 3 applies. The description adds no further parameter meaning beyond implying only public profiles are resolvable.

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 ('Public Pinterest profile') and enumerates the exact fields retrieved, so an agent knows this returns profile-level metadata rather than pins or boards. It does not explicitly contrast itself with siblings like pinterest_pins or pinterest_board, but the resource distinction is clear enough from the name plus field list.

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: 'Public Pinterest profile' suggests calling it when you need account-level stats, and the sibling names imply pinterest_pins/pinterest_board handle other content. There is no explicit when-to-use, when-not-to-use, or routing statement, and no mention of what happens for private or nonexistent profiles.

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 read-only, idempotent, open-world, non-destructive semantics, so the bar is lower. The description still adds genuinely useful context the annotations cannot convey: the 2-credit cost per successful call with refunds on failure, and the up-to-50 result ceiling. It does not explain how has_more should be acted on, which is the remaining behavioral 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?

Three tight lines, front-loaded with purpose, then cost, then return shape. Every sentence carries distinct information and nothing is repeated from the schema or annotations.

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 fields and flags has_more, and it discloses the credit cost. It is nearly complete for a two-parameter search tool, though it omits any note on how to retrieve additional pages when has_more is true.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the effective ceiling of 50 results, which the schema leaves unbounded (limit has only a minimum of 0, no maximum). It does not clarify how limit interacts with that cap or what happens when the cap is hit.

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 ("Search Pinterest pins by keyword"), which cleanly separates it from the single-item pinterest_pin and the list-oriented pinterest_pins. It does not explicitly name those siblings or state the contrast, so it stops short of full differentiation.

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?

Keyword search implies the usage context, but there is no explicit when-to-use guidance, no exclusions, and no reference to alternatives like pinterest_pins or pinterest_board for profile- or board-scoped retrieval. The agent must infer the routing decision.

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/non-destructive, so the safety profile is covered. The description adds genuinely new operational context: a cost model (1 credit per successful call, failed calls refunded) that an agent cannot get from annotations or schema. It stops short of describing error behavior for invalid identifiers.

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 resource and payload, then cost, then a compact typed return list. The return-field enumeration is long but earns its place because there is no output schema; wording is otherwise tight 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 a simple read-only fetch with no output schema, the description covers selection, accepted identifiers, billing, and return shape. Complete enough to invoke correctly; only failure-mode behavior is unstated, which is a minor 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%, and each property already documents its format and an example. The description's 'Provide one of: url OR id OR album' duplicates the schema-level description verbatim, so it adds no meaning beyond structured data; 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 the exact resource (a Spotify album) plus the identifier forms accepted and the payload returned (title, artists, release date, cover, full track list). This cleanly separates it from siblings like spotify_track, spotify_artist and spotify_playlist without 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?

Usage is implied rather than stated: you call it to fetch album detail when you already have a link/URI/ID. The 'Provide one of: url OR id OR album' line gives input selection guidance, but there is no explicit when-to-use-this-vs-sibling routing or mention of what to do if you only have a track 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 read-only, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds genuinely new information not present in annotations: a cost of 1 credit per successful call with refunds on failure, and the top-tracks cap of ~10. It omits failure/not-found behavior and any rate-limit context.

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 lines covering what it does, cost, and inputs/returns — easy to scan. Minor redundancy in restating the mutually-exclusive alias rule that the schema already declares.

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 return fields (id, link, name, image_url, top_tracks, top_tracks_count), which is a real service to the agent. However, it says nothing about what happens with an invalid ID or an artist with no top tracks, and does not clarify how top tracks are ranked.

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 fully documents all three aliases and their formats. The description's 'Provide one of: url OR id OR artist' duplicates the input schema's own top-level description rather than adding meaning, 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 names a specific resource (a Spotify artist) and enumerates contents: name, image, and ~10 top tracks with durations and preview URLs. It implicitly distinguishes itself from siblings like spotify_track and spotify_album by resource type, but never explicitly states the 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?

It gives an input-selection rule ('Provide one of: url OR id OR artist'), which is basic operational guidance. There is no when-to-use/when-not guidance relative to spotify_track, spotify_album, or spotify_playlist, and no indication of which alias form is preferred.

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

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

The description provides critical operational context beyond the annotations, specifically mentioning the cost (1 credit per call) and the refund policy. This is highly valuable behavioral insight for the agent.

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 reasonably structured, starting with a high-level summary, moving to operational costs, defining the input modes, and concluding with a full output specification. It avoids unnecessary fluff.

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

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

The description is extremely thorough, covering resource limits (~50 tracks), required input mechanisms (three formats), operational costs, and a detailed specification of the output fields and types, making it functionally complete for the agent.

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?

Since the schema coverage is 100%, the baseline is high. The description reinforces the constraint that only one of the three optional parameters must be provided, a constraint that adds clear meaning even if documented in the schema.

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

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

The description clearly identifies the tool as fetching details (title, owner, duration, tracks) for a public Spotify playlist, which distinguishes it from other music-related siblings like `spotify_track` or `spotify_artist`.

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

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

The description explicitly states the tool is for public playlists and dictates the required input format: providing exactly one of the three acceptable parameters. No specific exclusions (e.g., private playlists) are mentioned.

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, open-world, and non-destructive behavior, while the description adds the credit cost/refund policy and the exact nullable return fields. It does not cover authentication or rate limits, but the cost and output disclosure add meaningful context beyond annotations.

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

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

The definition is front-loaded and compact, with identifier requirements, cost, and return fields presented in short, relevant lines. Every sentence contributes to invocation or interpretation.

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

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

For a simple read-only lookup with no output schema, the description supplies accepted input forms, cost behavior, and a complete return-field summary. No major gap remains for correct invocation.

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 description only repeats 'Provide one of: url OR id OR track', which the input schema already states. It adds no extra syntax, precedence, or format guidance 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 identifies a specific Spotify track by link/URI/ID and enumerates the returned metadata, clearly distinguishing it from sibling tools such as spotify_artist, spotify_album, and spotify_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?

It specifies acceptable identifier forms and the credit cost, but does not explicitly say when to use this tool versus sibling resources or list any preconditions. The track-vs-album distinction is implied by the name and resource description rather than stated as 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), yet the description adds real value beyond them: a per-call cost of 1 credit with refunds for failures, and the constraint that this reads public channels only. It does not cover auth needs or rate limiting, which is why it is not a 5.

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

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

The core identity, cost, and input rule are front-loaded in short lines, which is good structure. The trailing "Returns:" enumeration runs to roughly sixteen fields on a single line, which is dense but largely justified since there is no output schema to convey that information 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?

With no output schema, the description compensates by enumerating return fields and their nullability, and it discloses the credit cost and public-channel limitation. Remaining gaps are minor for a read-only lookup tool: failure behavior and explicit routing to sibling listing tools are 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 description coverage is 100%, and each parameter already carries its own explanation and examples, so the description's restatement of the "one of url OR post OR username + id" rule duplicates the schema's own description field. Baseline 3 is appropriate; no additional syntax or format detail is added 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 first sentence names a specific resource and scope: "A single public Telegram channel message by link" with the data it carries (text, media, views, date, forward info, link preview, channel info). The word "single" implicitly separates it from the plural sibling telegram_posts, but no sibling is named explicitly, so it stops short of full differentiation.

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 through the input constraint "Provide one of: `url` OR `post` OR `username` + `id`", which tells the agent how to satisfy the call but not when to choose this tool over telegram_posts or telegram_profile. No exclusions, prerequisites, or alternatives are 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?

Annotations already establish read-only, idempotent, open-world, and non-destructive behavior. The description adds useful operational context beyond that: public-only scope, a cap of up to 100 messages, credit cost, and refund policy for failed calls.

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

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

The description is front-loaded and efficient. The return-field list is lengthy but justified because there is no output schema, though it could be slightly more compact.

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 compensates by listing return fields and clarifying cost/refund behavior. It covers the essentials for this two-parameter read-only tool, though pagination behavior beyond has_more is not explained.

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 username and limit. The description adds meaningful context by indicating that the tool returns the latest messages and that the maximum is 100, which refines the limit parameter 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 clearly states that it retrieves a public Telegram channel header plus its latest messages, including counters, text, media, views, and dates. This distinguishes it from telegram_post by making clear it returns multiple messages, though it does not explicitly name siblings such as telegram_profile.

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 implied use case is clear: fetching a channel overview and recent posts. However, it gives no explicit when-to-use guidance or alternatives, such as when to use telegram_profile versus telegram_posts, leaving the agent to infer 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 readOnly, idempotent, non-destructive and open-world behavior, so the bar is lower; the description adds genuinely new operational context by disclosing the 1-credit cost and the refund policy for failed calls. It does not cover failure modes (private/nonexistent handles) or rate limits, which keeps it short of a 5.

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

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

Purpose is front-loaded in the first sentence, followed by cost and then a return-field list; every element is informative. The return enumeration is long but justified because no 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?

With no output schema, the description compensates by listing every returned field with its type and nullability, and it also discloses the credit cost. An agent has everything needed to call the tool and interpret the response.

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 with 100% schema description coverage, including a concrete example ('durov'), so the schema carries the parameter semantics. The description adds nothing about accepted input forms beyond what the schema already states.

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+resource combination ('Telegram channel/group/bot/user card from t.me') and enumerates exactly which fields the card contains, which cleanly separates it from sibling tools like telegram_posts or telegram_post.

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 scope statement implies when to use this tool (profile-level metadata rather than content), but there is no explicit when-to-use/when-not guidance and no named alternative such as telegram_posts for retrieving messages.

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 read-only, idempotent, open-world annotations, it discloses the credit charge, refunds for failed calls, result cap, and response shape. Ordering, the default limit, and what an agent can do when `has_more` is true remain unstated.

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 front-loads scope and returned content, then presents cost, the invocation constraint, and a compact response-field list. It is dense but easy to scan, with nearly every clause supplying 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 simple three-parameter read tool without an output schema, the comment-content summary and explicit return fields make the definition largely complete. The remaining gaps are the default limit, ordering, exact nested comment-object fields, and guidance for handling `has_more`.

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?

Although schema coverage is 100%, the description adds the useful overall ceiling of 100 comments and prominently reinforces the mutually exclusive URL-or-ID requirement. It does not clarify the default `limit` or whether values above 100 are rejected or clamped.

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

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

The description clearly identifies retrieval of top-level comments for a single TikTok video, accepted identifier forms, and the information returned. Its platform, resource, and top-level scope distinguish it from tiktok_video, tiktok_posts, and the other platforms' comment tools.

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

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

The instruction to provide exactly one of `url` or `id`, together with the top-level-only scope and 100-comment ceiling, gives clear invocation context. It does not explicitly route agents elsewhere for replies, video metadata, or situations requiring more than 100 comments.

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

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

The annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds genuinely new operational context: a cost of 1 credit per successful call with refunds on failure, plus the nullable nature of most returned fields. It does not state what happens when a hashtag does not exist, which is the main remaining behavioral 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 opening clause and the Returns line both enumerate the same fields (id, title, description, video/view counts, cover), so the content is stated twice with only types added the second time. Cost and Returns are correctly separated and front-loaded, but the duplication wastes space.

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, documenting the return shape and the credit cost is exactly the right compensation, and it is done thoroughly with types and nullability. What is missing is edge-case behavior (nonexistent or private hashtags) and any note on empty/nullable field conditions, which matters for a single-parameter 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 coverage is 100% and the schema already explains that the hashtag may include or omit '#' or be a full tiktok.com/tag/... URL, with an example. The description adds nothing about the parameter, which matches the baseline 3 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?

The title/description pair identifies a specific resource (a TikTok hashtag) and enumerates the stats returned, which separates it from sibling tools like tiktok_profile, tiktok_posts, and tiktok_video. It lacks an explicit verb ("fetch" / "look up"), so the read intent is only implied by the field list and the annotations.

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 siblings such as tiktok_posts or tiktok_music, and no statement about when not to use it. The only implicit cue is that the input is a hashtag rather than a video or profile, which the agent must infer from the schema 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?

Annotations already establish a safe, idempotent, open-world read, so the description correctly spends its words elsewhere: the 2-credit cost with refunds on failure, the 12-video cap, and the fact that videos come from the public embed. That is exactly the kind of cost/limit context annotations cannot carry; only the lack of any error or rate-limit detail keeps it from a 5.

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

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

The purpose and cost are front-loaded in two short lines, and the field list is justified because no output schema exists. The "Returns:" line is a dense type dump (`string, nullable` repeated) that is slightly mechanical but not padded.

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 required parameters, the description carries its weight: it documents the return shape, the cost model, the video cap and the embed source. It is only short on edge cases such as url/id precedence and how `has_more`/`videos_fetched` interact with `limit`.

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

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

Schema coverage is 100%, so the baseline is 3. The description restates the url/id exclusivity already in the schema and adds only marginal meaning, e.g. the "max 12" ceiling for `limit`, while leaving open whether an explicit `limit` can exceed 12.

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?

"A TikTok sound by URL or ID" plus an enumeration of returned fields (title, artist, duration, is_original, cover, play_url, video_count) makes the resource and scope unmistakable, and it reads as clearly distinct from tiktok_video/tiktok_posts. It stops short of a 5 because it never explicitly contrasts itself with those siblings or states a verb like "fetch".

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 only guidance is an input constraint ("Provide one of: `url` OR `id`"), which is a parameter rule rather than a when-to-use rule. There is no mention of when to pick this over tiktok_video, no prerequisites, and no statement of what happens if both `url` and `id` are supplied.

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: a 1-credit cost with refunds on failure, and the important constraint that videos come from the public embed and cap at 12. It does not explain what has_more means or how pagination would work.

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?

Purpose is front-loaded in the first sentence, followed by cost and then returns, which is a sensible order for an agent. The returns list is long but each field earns its place because no output schema exists; only has_more is listed without explanation.

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 compensates by enumerating the return fields and their nullability. Combined with cost disclosure, the source limitation (public embed) and the 12-video cap, an agent has what it needs to call this correctly and predict 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 coverage is 100%, so the baseline is 3; username formats and limit are already documented in the schema. The description adds one real constraint the schema lacks, that the ceiling is 12 regardless of limit, but says nothing further about limit behavior such as what limit=0 returns.

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+resource: a TikTok profile summary plus its newest videos, with cover, play URL and play count. It distinguishes itself reasonably from tiktok_video (one video) by emphasizing the profile summary, but never names tiktok_profile, so the boundary with that closest sibling is left implicit.

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 by the phrase 'profile summary plus its newest videos'; there is no explicit when-to-use, when-not, or named alternative such as tiktok_profile for profile-only data or tiktok_video for a single clip. The agent can infer the case from the content list, but must do the routing work itself.

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 goes beyond them with a real operational fact the annotations cannot express: cost is 1 credit per successful call and failed calls are refunded. It does not say what happens on a private or nonexistent handle, which is the main remaining behavioral 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 sentences, both earning their place: the first front-loads purpose and payload, the second covers cost and return shape. The field list is long but dense and, since no output schema exists, is the only place that information lives.

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 compensates by enumerating every returned field with type and nullability, and it discloses billing. What it omits is failure behavior for private or nonexistent accounts and any notion of rate limits or caching, which matter for an open-world scraper 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?

Only one parameter exists and schema coverage is 100%, with the schema itself documenting that username accepts a handle, @handle, or profile URL and giving an example. The description adds no format or validation meaning beyond that, 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 names a specific resource (public TikTok profile) and enumerates exactly what data it yields (bio, verification, follower counts, avatar, region, creation date). The platform is explicit, so an agent can separate it from instagram_profile or youtube_profile, though it never explicitly frames the split against the closest sibling, tiktok_posts.

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 alternatives (e.g. use tiktok_posts for a profile's videos). The only usage signal is the word 'Public', implying private profiles are out of scope, which is implicit 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?

Annotations already cover read-only, idempotent, non-destructive, open-world, so the description adds genuinely new behavior: a cost of 1 credit per successful call with failed calls refunded, plus the caption origin and the language-selection behavior. This is exactly the context an agent needs that structured fields cannot supply.

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, then a cost line, an input constraint, and a compact Returns line — each sentence carries distinct information with no filler. The parenthetical return-type list is dense but scannable, and nothing is buried under preamble.

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 compensates by enumerating the return fields (video_id, language, is_auto_generated, available_languages, segments, text, segment_count). Cost, refund policy, and input constraint are all stated for a simple three-parameter read tool, leaving no material 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 coverage is 100%, so all three parameters (id, url, lang) are already fully documented in the schema, making the baseline 3. The description reinforces the either/or constraint and hints that available_languages enables a two-step language pick, but adds no format or syntax 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?

"Timestamped transcript of a TikTok video from its captions (auto-generated or creator-added)" states a specific resource and output artifact, and the caption-source parenthetical clarifies what kind of transcript. It does not name a sibling to distinguish itself from (e.g. tiktok_video, youtube_transcript), 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?

The description gives input-selection guidance ("Provide one of: `url` OR `id`" and "Pick a language with lang"), which is real usage help. It never says when to choose this over tiktok_video or youtube_transcript, nor what happens if the video has no captions at all — no exclusions or alternatives are offered.

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 read-only and open-world annotations, it discloses a charge of 1 credit per successful call, refunds for failed calls, and conditional watermark-free MP4 availability. The return list also communicates nullable fields, though failure modes and any rate or access limits are not described.

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?

Purpose, pricing, invocation, and results are presented in a predictable order with no filler. The exhaustive Returns list makes the text long, but it is largely justified because no output schema is supplied.

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 single-item lookup, the definition supplies the locator choices, cost behavior, and a typed, nullable field list sufficient to invoke and interpret most results. It leaves author/music object internals and concrete error behavior unspecified, which prevents full completeness in the absence of an output schema.

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

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

The schema already covers all three parameters with formats, examples, and the alias relationship, and the object schema also states the one-of input rule. The description repeats that rule and accepted locator types but adds little new parameter syntax or validation detail, so it sits at the high-coverage baseline.

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

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

The description identifies the resource and scope precisely: one TikTok video located by URL, short link, or ID, with metadata, media, author, and music returned. “Single” also separates it from collection-style siblings such as tiktok_posts, although it does not name that sibling 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 gives a clear use case—retrieving one known video when the agent has a URL, short link, or ID—and explicitly instructs the agent to provide one of url, video, or id. It does not state when to prefer tiktok_posts, tiktok_transcript, or tiktok_comments, so alternative selection remains inferential.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world, so the safety profile is covered without the description. The description adds genuinely useful operational context in the per-call credit cost and the refund policy for failed calls, but says nothing about rate limits, auth, or error conditions beyond 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 the purpose, then cost, then returns, which is good information ordering. The return-field enumeration is long but earns its place since no output schema exists; the leading name restatement ('Twitch channel info') is the only mild 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 correctly compensates by listing every return field with types and nullability, which is exactly what an agent needs to use the result. It stops short of describing the nested stream/last_broadcast object structure and failure cases for nonexistent channels.

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 username parameter is fully documented in the schema at 100% coverage, including a concrete example and the accepted 'login name or channel URL' forms. The description adds no parameter meaning beyond that, so the 3 baseline 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 (Twitch channel) and enumerates the exact fields retrieved, so the agent knows precisely what this returns. It never explicitly contrasts itself with twitch_videos or twitch_clips, but 'channel info' versus video/clip resources is distinguishable from the name and content.

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

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

Usage is implied rather than stated: an agent can infer this is the right tool for channel-level metadata and the wrong one for videos or clips, but there is no explicit when-to-use or exclusion language. No mention of behavior for missing or non-existent channels.

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, open-world), so the description's job is to add context — and it does, disclosing the credit cost model including refunds on failure, which is operationally important and not present in structured fields. It stops short of describing rate limits or what happens at the 50-item boundary.

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 tightly packed lines: capability first, then cost, then returns, each labeled and front-loaded. No filler, and the returns list is necessary because no 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?

With no output schema, the description correctly supplies return fields (user_id, username, display_name, period, clips, clips_fetched, has_more), and the credit cost rounds out operational needs. The main gap is the absence of any routing hint versus the sibling Twitch tools, which matters in a 41-tool surface.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds a constraint the schema lacks: the effective ceiling of 50 results for 'limit' (the schema declares only a minimum of 0 with no maximum). The period values are restated from the schema, so that portion is redundant rather than additive.

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 and scope — 'most viewed clips for a period' with an explicit field list (views, duration, creator, game, VOD timestamp) and a size cap. It is clearly distinguishable from twitch_channel and twitch_videos by resource noun, though it never explicitly says so.

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 by the resource name; there is no statement of when to choose this over twitch_videos or twitch_channel, nor any prerequisites. The period options and 50-clip ceiling give some practical framing, but no exclusions or alternatives are named.

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 behavioral context beyond that: a 1-credit cost with refunds on failure, a 50-video ceiling, and a note that results may be truncated (has_more, videos_fetched).

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, then labeled Cost and Returns lines. No filler, and the two highest-value facts (cap and cost) are surfaced 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?

With no output schema, the description carries the return contract and does so thoroughly, including nullable fields and pagination-style flags. It stops short of describing error cases or auth requirements, which keeps it just below full completeness for an open-world 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 coverage is 100%, and the schema documents type, limit, and username with examples. The description adds a constraint not present in the schema — the 'up to 50' cap on results — which materially informs how to set limit, plus the mapping of the three video kinds to the type parameter.

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

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

States a specific verb-and-resource ('A Twitch channel's latest videos') and enumerates the covered video kinds (past broadcasts, highlights, uploads) plus the returned fields, which separates it from twitch_clips by content type. It does not explicitly name twitch_clips or twitch_channel as alternatives, so sibling differentiation is implied 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?

The description implies the use case (fetch a channel's recent videos) but never says when to prefer this over twitch_channel or twitch_clips, nor any prerequisites. There are no exclusions or when-not-to-use 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 establish that this is a read-only, idempotent, non-destructive, open-world lookup. The description adds useful behavioral context by stating the credit cost, refund policy for failed calls, and the full set of returned 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?

The description is front-loaded with the core purpose, then cost, input rule, and return fields. The long return-field list is justified because there is no output schema, though 'engagement counts including views' is slightly redundant with the later view_count field.

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 single-post lookup with no output schema, the description supplies the key return shape, nullable fields, cost model, and input selection rule. Nothing essential for calling the tool correctly appears to be 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 url and id with examples and precedence. The description repeats 'Provide one of: url OR id' but does not add meaning beyond the schema.

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

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

The description clearly identifies the tool as retrieving a single X post by URL or ID and lists the post data returned. It distinguishes itself from the sibling list tool x_posts through the word 'single', though it does not explicitly name that alternative.

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 'A single X post (tweet) by URL or ID' and the instruction to provide either url or id. There is no explicit when-to-use guidance versus x_posts for multiple posts or x_profile for account data.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-derivable behavior: a cost of 2 credits per successful call with failed calls refunded, plus the 60-tweet cap and has_more flag. It does not explain how 'limit' interacts with the 60-item ceiling or what happens when the account is private and posts are withheld.

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 front-loaded: the capability and the 60-tweet cap appear in the first sentence, followed by clearly labeled 'Cost:' and 'Returns:' lines. The 20-field Returns enumeration is dense, but with no output schema it is doing necessary work rather than 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 a two-parameter read tool with no output schema, the definition covers the important gaps: return shape, credit cost and refund policy, tweet cap, and the has_more flag. What remains unstated is pagination behavior and how limit maps onto the 60-tweet ceiling, which is a real but minor omission given the otherwise thorough field list.

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 (username, limit) are already documented with examples in the schema. The description adds only indirect meaning, implying that limit governs the number of timeline tweets returned. Baseline 3 is appropriate where the schema carries the parameter burden.

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 resource and scope: an X profile plus its recent timeline, capped at 60 tweets including pinned, retweets and own replies, with text, media and engagement counts. That is much more precise than the bare name 'x_posts'. It does not explicitly contrast itself with the sibling x_profile, so an agent must infer that this tool is the profile-plus-timeline superset.

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: the phrase 'plus its recent timeline (up to 60 tweets)' suggests this is the choice when profile metadata and recent posts are both needed, while x_profile and x_post are the narrower alternatives. No sentence tells the agent when to prefer this over those siblings, and no exclusions or prerequisites are 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds a billing trait the annotations cannot express (1 credit per successful call, failed calls refunded) and enumerates nullable return fields, but says nothing about error/not-found handling or rate limits beyond 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?

Three front-loaded lines: what it returns, what it costs, and the exact return shape. The long field enumeration is dense but earns its place because no output schema exists. Slightly list-heavy but not padded.

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, spelling out every returned field and its nullability is the right compensation, and the cost/refund note covers billing behavior. Remaining gaps are minor: behavior when the account is private or nonexistent, and any rate limits, are unstated.

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 required parameter with 100% schema description coverage that already explains accepted forms ('@handle or profile URL', with an example). The description adds no meaning beyond the schema, 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 names a specific resource (public X/Twitter profile) and enumerates exactly what it fetches — bio, location, verification, follower/following/tweet/like/media/listed counts, avatar and banner. It is clearly distinct from siblings such as x_posts and x_post by virtue of the resource and the field list, though it never explicitly states 'retrieve' or names the sibling it excludes.

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 by the resource ('public profile'), with no explicit when-to-use, when-not-to-use, or routing to alternatives like x_posts. The cost line gives useful operating context but not selection guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and open-world behavior, so the safety profile is covered. The description adds information annotations cannot carry: a cost of 1 credit per successful call with failed calls refunded, which matters for agent budget decisions. It does not discuss rate limits or paging depth cost, keeping this below a 5.

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

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

Four compact, front-loaded lines: purpose first, then cost, then the input constraint, then the return shape. Every line carries distinct information and there is 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?

With no output schema, the absence of a return contract would be a serious gap, and the description compensates by naming the exact return keys including has_more and comments_fetched. Cost is also disclosed. What is missing is how limit interacts with has_more/pagination and whether comment replies are reachable at all, which leaves a small but real gap for a 4-parameter 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%, so every parameter is already documented, including the url/id constraint and the sort default. The description's "Provide one of: `url` OR `id`" repeats the schema-level rule rather than adding meaning. Baseline 3 applies where 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?

"Top-level comments of a YouTube video by URL or ID, sorted by top or newest" names a specific resource, its scope (top-level, i.e. not replies), and the retrieval modes. It also enumerates the returned fields, so the agent knows exactly what it gets. It stops short of naming a sibling it is not (e.g. youtube_video or youtube_transcript), so it is clear but not sibling-routing.

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 infers it should call this when it wants comment text for a specific video. There is no explicit statement of when to prefer youtube_video (metadata), youtube_transcript, or youtube_playlist instead, and no stated prerequisites such as the video needing comments enabled.

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 description correctly spends its words elsewhere: the 1-credit cost, the refund policy on failure, and the 100-video ceiling with has_more signalling. That is real behavior an agent cannot get from the structured fields. It stops short of describing ordering or pagination mechanics beyond the has_more flag.

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 resource and payload, then cost, then input rule, then returns — good ordering with no filler sentences. The returns line is a long field-by-field enumeration, but since no output schema exists it 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?

With no output schema, the explicit return-shape listing is genuinely necessary and is provided, along with cost and the video cap. An agent has enough to call it correctly; the remaining gap is what happens when a playlist exceeds 100 videos beyond the has_more flag.

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 id, url, and limit including examples, making 3 the baseline. The description adds only the max-100 video ceiling, and it is unclear whether that cap applies to the `limit` parameter or to the returned videos array, so the added meaning is marginal rather than decisive.

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 (a YouTube playlist) and enumerates exactly what is returned: title, description, owner channel, video and view counts, plus its videos. That is far more than a restatement of the name. It does not distinguish itself from siblings like youtube_videos or youtube_video, but the verb+resource 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?

The only routing guidance is 'Provide one of: `url` OR `id`', which constrains input shape rather than when to choose this tool over youtube_video, youtube_videos, or youtube_profile. The purpose is obvious enough that an agent can infer usage, but no alternative is named and no exclusion is 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?

Annotations already cover safe-read, idempotent and open-world behavior, yet the description adds genuinely new context: a 1-credit cost per successful call with refunds on failure. The enumerated return fields with nullability also set expectations for partial data, which annotations 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-loaded with purpose, then cost, then input constraint, then returns; each line is distinct and functional. The long return-field enumeration is justified because no output schema exists, though it reads as a slightly dense run-on.

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

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

For a two-parameter read tool with no output schema, the description covers purpose, cost, input selection and the full return shape including nullable fields. The only gap is behavior when both identifier parameters are provided or when a channel is not found.

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 both parameters carry their own descriptions and examples, so the schema does the heavy lifting. The description's 'by handle, channel ID or URL' and 'Provide one of' lines repeat what the schema already states, adding no new syntax or edge-case meaning (e.g. what happens if both are supplied).

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 (YouTube channel) and the identifying inputs (handle, channel ID or URL), plus the fields returned. An agent can distinguish it from youtube_videos or youtube_search by the resource alone, though the description never explicitly names those siblings.

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 only usage rule is 'Provide one of: `username` OR `channel`', which is an input constraint rather than when-to-use guidance. It does not say when to prefer this over youtube_search or youtube_videos, but the implied 'look up one channel' use case is discoverable from the purpose line.

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, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuine context beyond that: a per-call cost of 1 credit with refunds on failure, which affects how freely an agent retries or fans out. It stops short of stating rate limits or how has_more should be used to page.

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 lines: purpose, cost, returns. No filler. The returns line is somewhat list-like, but since no output schema exists it earns its place rather than repeating structured data.

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

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

With no output schema, the description correctly compensates by naming the response envelope (query, type, sort, upload_date, results_fetched, has_more, results) and the cost model. The remaining gap is that result objects are only described as array<object> with a loose mention of views/duration/channel, and the limit/has_more paging relationship is left 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 description coverage is 100%, with each of the five parameters (including query, type, sort, upload_date, limit) documented with accepted values and examples. The description only restates those filters at a high level and adds no format or interaction 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?

The description states a specific verb and resource ("Search YouTube by keyword") and enumerates the result kinds (videos, Shorts, channels, playlists) plus the fields carried back (views, publish time, duration, channel). That is enough to separate it from the fetch-specific siblings like youtube_video or youtube_playlist, but it never names those siblings or explicitly contrasts search with retrieval.

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 word "search" and by the mention of "Optional type, popularity sort and upload-date filters", which signals this is the discovery entry point. There is no explicit when-to-use/when-not statement and no routing to alternatives such as youtube_videos or youtube_profile for known-channel lookups, so the agent must infer the boundary.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds genuinely useful non-annotation context — the 1-credit cost with refunds on failure — and enumerates the return fields, but says nothing about failure modes such as videos lacking captions or rate limits. The cost disclosure is the strongest addition and lifts it above baseline.

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 purpose, then two compact labeled lines for cost/input and returns; no filler prose. Minor waste in restating 'Provide one of: url OR id', which duplicates the schema description verbatim, but overall it is tight and scannable.

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 explicit return-field enumeration (video_id, language, is_auto_generated, available_languages, text, segments) is a real contribution, and the cost line covers billing expectations. However, for a tool whose practical failure mode is 'no captions exist', the absence of any note on missing/auto-generated caption fallback leaves a meaningful behavioral 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 id, url and lang are fully documented in the schema itself, including examples and defaulting behavior. The description only echoes the one-of constraint and alludes to language selection through the return fields; it adds no syntax or format detail 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?

States a specific resource (YouTube video transcript from captions) plus the exact shape of what comes back: timed segments, joined plain text, chosen language, and available caption languages. That makes it trivially distinguishable from siblings like youtube_video (metadata) and tiktok_transcript (different platform) without opening 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?

Contains no when-to-use or when-not-to-use guidance relative to alternatives; the only directive is the input constraint 'Provide one of: url OR id', which merely restates the schema's own description. Nothing tells the agent when to prefer this over youtube_video, or what to do when captions are unavailable.

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' safe, read-only profile, the description discloses the meaningful billing behavior: one credit per successful call and refunds for failed calls. The return contract also documents nullable fields and status flags, although it adds little about error conditions or data freshness.

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 front-loaded with purpose, followed by cost, input requirements, and the return contract in a logical order. The initial metadata summary partly duplicates the longer Returns list, but the list is justified because no output schema is supplied.

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 three-parameter read tool, the definition covers lookup scope, input selection, pricing and failure refunds, and a typed return contract with nullability. The detailed Returns section is especially valuable given the absence of an output schema, leaving no significant invocation-critical 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%, including formats and examples for all three parameters, so the baseline is 3. The description repeats the useful one-of requirement and URL-or-ID semantics but adds no substantial parameter meaning beyond the structured 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 opening line clearly defines a single-video metadata lookup by URL or ID and enumerates the information retrieved. Specifying 'a single YouTube video' also distinguishes its scope from plural or adjacent siblings such as youtube_videos, youtube_comments, and youtube_transcript.

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

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

The description gives a clear usage context: use it for one known video identified by URL or ID, and provide exactly one of url, id, or video. It does not explicitly explain when to choose youtube_search or youtube_videos instead, so alternative-selection guidance remains 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 cover read-only, idempotent, and open-world behavior, so the description's job is to add context — and it does: billing ('1 credit per successful call, failed calls are refunded'), a hard cap of 30 uploads, and the caveat that views are 'approximate' and publish time is 'relative'. It stops short of explaining has_more/pagination mechanics or default limit 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?

Well front-loaded: purpose first, then cost, then required inputs, then return shape. The long return-field enumeration is verbose but earns its place because no output schema exists; the field-by-field nullability listing could be tightened into a shorter summary.

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?

Since there is no output schema, documenting the return fields (channel_id, handle, videos array, has_more, etc.) is genuinely necessary and done well. The remaining gap is behavioral: how pagination via has_more works and how `limit` interacts with the 30-video cap.

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. The description only contributes the 'max 30' ceiling and the username/channel exclusivity, both of which the schema already states, and it never clarifies whether `limit` can exceed 30 or what the default is.

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 names a specific verb+resource pair: 'A YouTube channel summary plus its latest uploads (max 30)' and enumerates the per-video fields returned. This is clearly distinct from youtube_video or youtube_comments, but it does not say how it differs from the closely related sibling youtube_profile, which an agent could easily confuse it with.

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?

'Provide one of: `username` OR `channel`' is a parameter constraint, not usage guidance — and it merely restates the input schema. The description never says when to pick this over youtube_profile, youtube_search, youtube_playlist, or twitch_videos, nor does it mention prerequisites or failure conditions.

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