agdata

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

Annotations already declare readOnly/openWorld/non-idempotent. The description adds valuable non-obvious behavior: each product is 'filled in from its product page' (i.e., an extra fetch per item) and the cap of 20 per call. It does not mention rate limits or latency, but the enrichment cost is disclosed.

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

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

Front-loaded with the core action, then limits, then the returned field list. Dense but every clause carries information; the field enumeration is long but justified given no output 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 no output schema, the description usefully enumerates the normalized product fields and notes per-item page enrichment. Minor gaps remain (e.g., no note on failure/empty results or language/store caveats), but it is sufficient to invoke correctly.

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

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

Schema coverage is 100% and the schema itself documents limit clamping (larger lowered to 20, 0/negative → default) and the query example. The description only restates 'Body: {query, limit}', adding nothing beyond the schema, so baseline 3 applies.

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

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

States a specific verb+resource+scope: 'Keyword search on Amazon.com (US store)', with per-call limits. This clearly distinguishes it from the amazon-reviews sibling and other search 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?

'Good for price checks and product comparison' gives concrete usage context, and the store scoping (US) implicitly rules out other locales. No explicit when-not or named alternative, but the intended use case is clear.

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

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

Annotations already cover the read-only, non-destructive, open-world profile, and the description adds genuinely new behavioral facts: the 50-review ceiling, that reviewer names and photos are omitted, and that a product with no reviews is not charged. The billing/charging behavior is especially useful given idempotentHint=false, though the cost model itself is only hinted at.

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

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

A single front-loaded sentence pair that leads with the core action and payload, then packs sort/filter/marketplace options and exclusions without redundancy. Every clause carries information an agent needs.

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

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

With no output schema, the description compensates by enumerating returned fields (rating, title, text, date, verified flag, helpful votes) and explicitly noting what is not returned. Combined with billing and filtering behavior, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so all five parameters are already fully documented in the schema, including the URL-sets-marketplace rule and the 1-50 clamping behavior. The description only restates the high-level capability (sort, star filter, marketplaces) without adding syntax or edge-case meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('send an ASIN or an Amazon product URL and get up to 50 customer reviews as JSON') and enumerates the returned fields. It is unambiguously distinguishable from sibling review tools like google-maps-reviews or youtube-comments, which target other platforms.

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 context is clear: use it to fetch customer reviews for an Amazon product, with sort/filter/marketplace options spelled out. There is no explicit when-not or named alternative, though among the siblings none competes for Amazon review data, so the gap is minor.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful behavior beyond that: an explicit cap of 20 places per call and a full list of returned fields, which tells the agent what a call yields.

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 scoping are front-loaded in the first sentence, the example is compact, and the return-field list and use cases follow in an efficient order. No sentence is wasted, though the field enumeration is dense.

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 return fields, and it covers parameters and use cases. It is essentially complete for a read-only search tool, with only pagination behavior beyond the per-call cap 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%, so query, location and limit are all documented in the schema (including the 1-20 clamp and default). The description restates the 20-place cap and shows an example invocation but adds no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb and resource: search Google Maps places for a term, optionally narrowed to an area, with a concrete example. It clearly conveys discovery of local businesses, but does not explicitly distinguish itself from the sibling google-maps-reviews, even though it lists totalScore and reviewsCount as fields.

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 offers concrete use cases (local lead lists, store/competitor mapping, checking hours or phone) which implies when to use it, but provides no when-not guidance or named alternatives such as google-maps-reviews for review 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 cover safety (readOnly, non-destructive, open-world), and the description adds substantial extra context: the 50-review cap, fields included vs deliberately omitted (reviewer names, profiles, photos), and billing behavior (unfetched/no-review requests not charged, paid-but-missing reviews refunded). This goes well beyond what annotations provide.

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

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

Front-loads the core action and output shape before billing detail, with no truly redundant sentences. The opening 'for AI agents' framing is mild filler and the sentence is long, but each remaining clause carries information an agent needs.

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

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

With no output schema, the description carries the burden of describing returns and does so fully: star ratings, text and translation, date, likes, owner reply, plus place name/address/rating, and it flags excluded data. An agent has everything needed to call and interpret 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 description coverage is 100% and the parameter docs are rich (place_id format, limit clamping, language enum). The description only restates the sort options and the 50 cap, adding no syntax or format detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource (fetch Google Maps reviews for a place) plus the input forms (place_id or Maps URL) and sort options. It is clearly separable from siblings like google-maps (place lookup) and amazon-reviews (different source).

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 usage via the input formats and sort values, and notes the no-review/refund billing case, but never states when to choose this tool over siblings such as google-maps or when it is inappropriate. Context is implied rather than explicit.

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

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

Annotations already declare readOnly, openWorld, non-idempotent and non-destructive characteristics, so the safety profile is covered. The description adds genuinely new behavioral context: a result cap of 30, the shape of returned records, and a billing/refund note about paid-but-unreturned articles, which is information no annotation supplies.

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 capability and return payload are front-loaded, followed by the edition note and refund clause. It is dense but every clause carries information; slightly compressed prose keeps it from a 5.

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 naming the returned fields, and the annotations cover the safety profile. The only minor gap is absence of guidance on pagination or result freshness relative to sibling search tools, but nothing needed to call the tool correctly is missing.

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

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

Schema description coverage is 100%, so all four parameters are already documented with defaults, ranges and patterns. The description corroborates the 30-item cap and the language/country edition concept but adds no syntax or format detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource: search Google News for a keyword and return up to 30 current articles. It enumerates the returned fields (headline, publisher, publish time, description, link), which lets an agent distinguish it from google-search and web-search siblings that return general web results.

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

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

Gives clear invocation context (send a keyword or phrase; choose language and country edition) and implies the use case of current news retrieval. It stops short of explicit when-not or alternative-tool guidance versus google-search/web-search, so it earns a solid 4 rather than a 5.

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

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

Annotations already declare readOnly (safe read) and openWorld, so the bar is lower. The description adds valuable non-obvious behavior: limit is billed in pages of ~10 and rounded up, so requesting 11 yields two pages — this billing/quota behavior is not in the schema or annotations.

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

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

Front-loaded with the core purpose and return shape, then params, then use cases. Dense but every sentence carries information; the field enumeration is long yet useful given no output 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 no output schema, the description usefully enumerates the returned record structure (organicResults, paidResults, relatedQueries, peopleAlsoAsk, metadata). Safety profile is covered by annotations. Complete enough to invoke correctly; could mention rate limits or result freshness.

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 nonetheless adds meaning by clarifying the rounding/billing semantics of limit beyond the schema's own note, and confirms the required body shape {query, limit}.

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

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

States a specific verb+resource (Google Search results, SERP) for a query, returned as JSON, and enumerates the exact fields returned. An agent can distinguish it from siblings like web-search or google-news without opening the schema.

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

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

Gives concrete use cases — rank checks, source discovery, grounding answers — which implies when to invoke it versus generic web-search. It does not explicitly state when NOT to use it or name the closest alternative (web-search), so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower; the description still adds real value by disclosing the result shape (title, employer, location, posting date, job types, benefits, salary, description) that no output schema provides, plus the notable billing guarantee that paid-but-unreturned jobs are refunded. It omits rate limits and how the non-idempotent nature plays out across calls, keeping it out of 5 territory.

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

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

It is a single dense sentence with the core action and return payload front-loaded and no filler. The trailing refund clause is slightly tangential to selection, but each clause carries information.

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

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

With no output schema, the description correctly compensates by enumerating the returned fields, and all five parameters are documented in-schema, so an agent can call it correctly. It lacks only edge-case behavior (empty results, error handling, whether the full listing text is truncated), which is a minor omission for a read-only search 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 (including the limit cap-slash-default quirk, the posted enum, and the country list) is already documented in the schema. The description's mention of title, location, country, and recency filtering largely restates the schema, which is the correct baseline 3 rather than a value-added score.

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

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

The description names a specific verb and resource ('Indeed jobs search API... send a job title... get up to 50 job listings as JSON') and even enumerates the returned fields, so the tool's function is unmistakable. However, it never distinguishes itself from its closest sibling (linkedin-jobs) or from general job-seeking via web-search, so it stops short of a 5.

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

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

It gives concrete usage context -- filter by posting recency, coverage of 60 countries, up to 50 results -- but offers no explicit when-to-use or when-not-to-use guidance relative to siblings like linkedin-jobs. Usage is implied rather than routed.

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/openWorld/idempotent=false/destructive=false, so safety is covered. The description adds real value by stating no Instagram login or API key is required and by listing the normalized output fields, though it omits rate limits or failure behavior.

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

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

Front-loaded with the resource and modes, then parameters, then return shape, with no filler. A few clauses duplicate the schema's mode descriptions, costing it the top mark.

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 normalized post fields (caption, likes, comments_count, views, media_url, etc.) and covers modes, parameters, and the auth model. An agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100% and the schema already documents mode, limit, and query thoroughly. The description's restatement of mode semantics and the 1-20 limit is largely redundant with the schema, so it lands at the 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?

States a specific verb+resource (fetching Instagram posts as JSON) and enumerates the four modes it supports. An agent can tell this retrieves posts rather than comments, but the description never explicitly contrasts itself with siblings like instagram-comments or tiktok.

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

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

It clearly maps each mode to a use case: profile for an account's posts, hashtag for a tag, search/user for keyword-driven discovery. That is strong conditional guidance, though it stops short of naming exclusions or rival tools to prefer instead.

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

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

Beyond the readOnly/openWorld annotations, it discloses a hard cap of 100 comments per call, that commenter names and handles are deliberately not returned, and an unusual payment model (pay-per-call in stablecoins with refunds for undelivered comments). These are behavioral traits an agent could not infer from annotations or schema.

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

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

Three tight sentences: purpose and invocation first, then result shape, then constraints and payment. Every sentence carries information an agent needs and none repeats 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 no output schema, the description compensates by naming the returned fields (text, time, likes, reply count) and flagging the missing commenter identity. Combined with the cap and refund behavior, an agent has everything needed to call this correctly and interpret the result.

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 both parameters are fully documented in the schema, including default, min/max, and clamping behavior. The description only echoes the 100-comment cap, adding no syntax beyond what the schema already provides, so the baseline 3 applies.

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

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

The description states a specific verb+resource: send a post/reel URL and receive its comments as JSON. The title and resource scope (comments under a post) make it clearly distinct from the sibling instagram tool (post data) and from tiktok-comments/youtube-comments, so an agent can pick it without opening the schema.

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

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

It implies when to use it ('send the URL of a post or reel and get its comments') but offers no explicit when-not or alternative routing, e.g. to the sibling 'instagram' tool for post metadata. Usage context is present but entirely inferred.

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 (readOnlyHint, destructiveHint), but the description adds useful non-schema context: 'public' profiles only, 'one per call,' 'no limit field,' and that email addresses are not returned. This enriches understanding beyond what annotations provide.

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

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

Two sentences, front-loaded with the key action and scope. The second sentence lists many return fields, which is informative but somewhat verbose; however, every element is relevant to understanding the output.

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 returned fields (name, headline, experience, education, etc.). It also notes email exclusion. The only missing element is explicit guidance on failure modes or rate limits for a non-idempotent, open-world 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?

The schema description for 'query' (100% coverage) already describes acceptable formats. The description repeats this but adds the concrete username example 'jane-example' and clarifies that a limit field is absent, which slightly exceeds the schema but is largely redundant.

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?

Strong, specific verb+resource: 'Look up one public LinkedIn profile per call.' Distinguishes itself from the sibling 'linkedin-jobs' by focusing on profiles rather than job listings, and the scope notes (one profile per call, public only) add precision.

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

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

Implies correct usage with 'Pass {query} as a username, profile URL or URN; there is no limit field,' which tells the caller what to supply. However, it doesn't explicitly name or exclude alternatives like a hypothetical 'linkedin-search' sibling or explain when looking up en masse would be inappropriate.

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, openWorld and non-destructive behaviour, so the description only needs to add context — and it does: results are capped at 50, only public listings are returned, recruiter names are never included, and billing is refunded for unfulfilled paid jobs. The cap and the public/recruiter caveats are behaviour an agent cannot infer from the annotations.

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

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

Purpose is front-loaded in the first clause, followed by return fields and constraints in one dense paragraph with no filler sentences. The billing/refund sentence is slightly tangential to tool selection but is short and self-contained.

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

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

With no output schema, the description carries the return-value burden and discharges it by naming the JSON fields (title, company, location, date, type, seniority, salary, URL, description). Pagination behaviour beyond the 50-item cap and error/empty-result behaviour are unstated, which is the only real gap for a 4-parameter read tool.

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

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

Schema description coverage is 100%, so the schema already documents limit clamping, the posted enum values and location format. The description only restates these at a high level (up to 50, filter by recency, optional location) without adding format or edge-case detail beyond the schema — baseline 3.

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 (LinkedIn jobs search) plus the exact retrieval scope: up to 50 public listings from a title/keyword plus optional location. It also enumerates the returned fields, so an agent can distinguish it from indeed-jobs (different source) and from the plain 'linkedin' profile tool without opening the schema.

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

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

Clear context for when to reach for it: pass a job title or keywords, optional location, and optionally narrow by recency. It does not name alternatives (e.g. indeed-jobs) or say when this source is preferable, so the routing guidance stops short of explicit alternatives.

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/openWorld/destructive=false, so the safety profile is covered. The description adds genuinely new behavioral facts: comments are never fetched, upvotes and comments_count may be null, and subreddit mode can return a community record with its description. These are the kind of edge-case disclosures that prevent wrong downstream assumptions; only auth/rate-limit/pagination context is absent.

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

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

Three dense sentences, correctly front-loaded with mode selection before the return-shape detail. Every sentence carries information, though the second and third sentences are run-on and could be split for faster scanning.

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

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

With no output schema, the description correctly picks up the burden of describing the returned normalized record (kind, title, body, author, subreddit, url, created_at, upvotes, comments_count) plus nullability and the community record case. Minor gaps remain: the enumeration of possible 'kind' values and expected result-count behavior are not stated.

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 mode, limit, and query are already fully documented in the schema, and the description largely restates them ('limit 1-20', '(no r/)'). It adds no format or syntax detail beyond what the schema provides, 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 opening sentence pairs specific verbs with a specific resource ('Search Reddit or read a subreddit'), and the title plus the mode list make the three retrieval paths explicit. An agent can distinguish this from twitter, instagram, or web-search siblings purely on the resource named, without opening the schema.

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

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

It tells the agent how to select each mode ('Use mode hashtag with a subreddit name (no r/), profile with a username, or search with keywords'), which is clear operational context. It also implicitly excludes a use case via 'Comments are not fetched', steering the agent away from expecting comment threads. It stops short of naming an explicit alternative or a when-not condition, so it falls below the top band.

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

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

Annotations only declare the read-only/open-world/idempotency profile; the description goes further by disclosing the return payload shape (final URL, byte size, pixel size), the billing rule ('a page that can't be captured, or renders blank, is not charged'), and a real capability limit around bot protection. These are exactly the traits annotations cannot convey.

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

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

Three sentences, front-loaded with the input/output contract before options and caveats. Dense but each sentence carries distinct information (payload, options, limitation/billing); the capability list is slightly compressed but not wasteful.

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 10 parameters, the description supplies the missing return-value and failure semantics, which is the main gap it needed to fill. It stops short of mentioning auth/API-key requirements or rate limits, which are the only remaining unknowns for an agent 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 description coverage is 100%, so every one of the 10 parameters is already documented with ranges, defaults and enums. The description's recap of viewport/fullPage/dark mode/delay/selector adds grouping but little syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

States a specific verb (capture/screenshot) and resource (a page at {url}) plus the exact output artifacts (JPEG/PNG/WebP/PDF as base64 JSON). It also differentiates itself from the sibling 'unblock', so an agent can route between them without opening either schema.

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

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

Explicitly states the condition under which this tool is the wrong choice ('does not get past bot protection') and names the alternative to use instead ('use unblock for those pages' text'). That is a clear when/when-not/alternative triad, not mere implied usage.

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, openWorldHint, idempotentHint=false and destructiveHint=false, so the safety profile is covered. The description adds context the annotations do not: a cost model ('pay per call in stablecoins'), a latency expectation (~1 second), and result-shape detail. It omits rate limits or failure behavior, so not a 5.

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

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

A single dense paragraph that front-loads the core purpose before filters, latency and pricing. Almost every clause earns its place; the 'Search API for AI agents' preamble is slightly redundant but harmless.

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 carries the burden of describing return values (title, URL, query-relevant excerpt) and covers type, limits, categories, domain filtering, cost and latency. The main missing piece is the relationship to the many sibling search tools.

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

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

Schema description coverage is 100% and every parameter (type, limit, query, category, include/exclude_domains) is already documented in the schema, including billing in pages of 10 and the mutual exclusivity of include/exclude domains. The description restates category meanings and site filtering but adds no syntax or format 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 verb and resource (web or news search) plus the result shape (title, URL, excerpt) and count. However, in a sibling set that already contains web-search, google-search and google-news, it never says how it differs from those, so the agent cannot distinguish it from its closest alternatives without extra work.

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. It never tells the agent when to pick this over web-search, google-search or google-news, and no prerequisites or exclusions are given. 'Fast, about a second' is a selling point, not routing guidance.

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

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

Annotations already cover the safety profile (readOnly, destructive=false, idempotent=false, openWorld), so the bar is lower. The description adds real context beyond them: the @/# prefix stripping, the 1-20 limit clamping semantics, and the full set of returned record fields — the latter is particularly valuable since there is no output schema. It does not mention rate limits, latency, or auth needs for the underlying scraper.

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?

Information-dense and front-loaded: the purpose and mode options come first, then the parameter shape, then the return fields. The field enumeration runs long as a single comma-delimited sentence, but given the absence of an output schema that space is earned rather than wasted.

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

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

With no output schema, the description properly compensates by listing return field names, and it covers mode selection, query normalization, and limit clamping. It stops short of describing failure behavior (invalid username, empty hashtag, blocked scraping) which an agent calling a live open-world scraper would benefit from knowing.

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 still adds meaning beyond the schema by disclosing the body structure as {mode, query, limit} and by stating that a leading @ or # in the query is stripped — a normalization behavior the schema does not document (the schema only says 'hashtag without #').

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 ('Get TikTok videos') and immediately enumerates the three supported lookup modes (username, hashtag, search keyword), which maps directly onto the tool name and title. The 'videos' framing also implicitly separates it from the sibling tiktok-comments tool without needing to name 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 opening sentence tells the agent which query types this tool handles and the schema-level mode enum clarifies which mode corresponds to each query shape. It does not name alternatives (e.g. tiktok-comments, instagram) or state when NOT to use it, so the routing guidance is clear but not exhaustive.

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

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

Goes well beyond the annotations by disclosing the payment model ('Pay per call in stablecoins'), the refund guarantee for undelivered comments, the 100-comment ceiling, and the deliberate omission of commenter names/handles. These are exactly the operational and output-shape facts an agent cannot get from readOnlyHint/idempotentHint.

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

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

Front-loads the core action and output fields, then layers limits, omissions, and billing in short clauses. Only the 'for AI agents' framing is mild filler, but nothing is redundant or bloated.

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

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

With no output schema, the description carries the return-value burden and does so by naming the exact fields returned and the fields withheld. Combined with the limit and billing/refund disclosure, an agent has everything needed to call and interpret the 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 both parameters are already fully documented, including the coercion rule for out-of-range limit values. The description only restates the 100-comment cap, adding 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?

Names a specific verb and resource ('send the URL of a video and get its comments as JSON') and enumerates the returned fields (text, time, likes, reply count). An agent can distinguish this from the sibling 'tiktok' (video data) and 'youtube-comments' without opening the schema.

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

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

Usage is implied by 'send the URL of a video', and the 100-comment cap is stated, but there is no explicit when-to-use guidance and no routing to alternatives such as 'youtube-comments' or the generic 'tiktok' tool. The agent must infer platform selection from the name 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 cover the safety profile (readOnlyHint, destructiveHint=false, openWorldHint, idempotentHint=false). The description adds genuinely non-obvious context: no X developer account is required and calls are paid per call in USDC, which matters for cost-sensitive planning. It omits rate limits, pagination, and failure behavior, so 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?

Front-loads purpose and the mode example, then the limit rule and payment note. The long enumeration of returned fields is justified because no output schema exists, though it makes the sentence dense.

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 the returned tweet and author fields, and it covers modes, limits, auth requirements, and cost. Missing pagination and error/empty-result handling keeps it from a 5.

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 mode, query, and limit semantics (including the clamping behavior for limit). The description echoes mode/query and the 1-20 limit range and adds a concrete example, but adds little beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Tweets from X for one account or a search query') and separates the two operating modes. It doesn't explicitly differentiate itself from the sibling x-replies tool, which is the closest alternative, so it stops short of a 5.

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

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

Gives clear mode-selection guidance (profile returns an account's tweets, search takes keywords) and bounds the limit to 1-20. It does not say when to prefer this over x-replies or what to do when a profile yields no results, so no exclusions 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 this a read-only, non-destructive, open-world call. The description adds genuinely new behavioral context the annotations cannot convey: bot-protection bypass, JavaScript rendering, no charge when a fetch fails (blocked, error, or empty), and the payment/auth model (no API key, pay per call in USDC over x402 or MPP). That is a rich disclosure of cost and failure semantics.

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 sentences with the core behavior front-loaded, then modifiers (format overrides), then cost semantics. Every clause earns its place; nothing is redundant 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?

With no output schema, the description compensates by naming the returned fields, and it additionally covers failure handling and the payment path. For a two-parameter page-fetch tool, an agent has everything needed to call it and interpret results.

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

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

Schema description coverage is 100% and the schema itself documents url format, maxLength, the format enum and its default. The description only restates what format can be set to, adding no syntax or edge-case detail beyond the structured fields, 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 ('send {url} and get the page back as clean Markdown') and enumerates the return payload (title, description, language, final URL, HTTP status). It is clearly distinguishable from siblings like screenshot or web-search, which target images and search respectively rather than single-page extraction.

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 usage context (fetching a public page, including Cloudflare-protected or JS-heavy ones) and covers the format switch, but it never says when to pick this over sibling tools such as screenshot or web-search, nor does it state any exclusion beyond 'public page'.

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

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

Beyond the annotations (readOnly, openWorld, non-idempotent, non-destructive), the description discloses operationally important behavior: a hard cap of 5 results, per-page truncation at 20,000 characters, that unfetchable pages are dropped and refunded, and that the call is paid in stablecoins. These cost and failure-mode details are exactly what an agent needs and are not derivable from the annotations.

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

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

The core is a single dense, front-loaded sentence, and follow-on sentences cover limits, refunds, and pricing. It is slightly run-on and the 'for AI agents' framing is filler, but virtually every clause carries usable 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?

With no output schema and only two parameters, the description fully compensates: it enumerates the returned fields, the truncation limit, the result cap, the failure/refund behavior, and the payment model. An agent can call this correctly without opening anything else.

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

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

Schema description coverage is 100%, so both parameters are fully documented in the schema including the limit clamping rules and the query format. The description only lightly reinforces this ('Up to 5 results'), so the baseline 3 applies — it neither adds much nor is needed to.

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 ('web search with page content'), and specifies the return shape: title, URL, short description, and page text as Markdown. It does not explicitly differentiate itself from the sibling 'google-search' or 'google-news', leaving the agent to infer that this tool fetches full page content while those return listing-style results.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'for AI agents' and 'in one call' hint at the value proposition but never name an alternative tool or state the conditions that select this one over the many search-shaped siblings.

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/openWorld/non-idempotent/non-destructive, so the safety profile is covered. The description adds genuinely useful behavior beyond that: a hard cap of 50 replies per call, a pay-per-call stablecoin cost model, and a refund guarantee for paid-but-undelivered replies. It does not mention auth/credential requirements, keeping 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?

Two sentences, front-loaded with verb+resource, then output shape, cap, and billing terms. Each clause carries distinct information, though the sentence runs long with the billing/refund details packed in.

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 returned fields (text, time, likes, reposts, replies, views, author handle), and it covers cost, cap, and refund behavior. Only caller-side prerequisites (credentials, error behavior) are left 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 coverage is 100%, so both parameters (url, limit) are already fully documented, including limit's clamp-at-50 and default-handling rules. The description only echoes 'up to 50 replies per call,' adding no syntax or format detail beyond the schema; baseline 3 is appropriate.

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

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

States a specific verb and resource: 'Replies to a post on X' plus the concrete input (post URL) and output (JSON with text, time, likes, reposts, replies, views, author handle). It is clearly distinct from generic siblings like 'twitter' or other comment-fetching tools, though it never names them 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?

Usage is implied by the 'send the post's URL and get the replies' framing and the 50-per-call cap, but there is no explicit when-to-use/when-not guidance or reference to an alternative sibling (e.g. 'twitter' for other X data). Adequate but leaves routing to inference.

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

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

Annotations already declare readOnly/openWorld/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: limit is capped at 20 and excludes Shorts and live streams, and it enumerates the normalized fields returned per video despite the absence of an output schema. It stops short of covering failure modes or ordering guarantees.

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

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

Two tight sentences, front-loaded with purpose and mode routing before the return-shape list. The field enumeration is long but justified given there is no output schema, so every clause earns its place.

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

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

With no output schema, the field list is a valuable substitute and the mode/limit/exclusion details are all present. It omits error handling and what happens with an invalid channel handle, so it is strong but not fully complete for a two-mode 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 all three parameters are self-documented in the schema, so the baseline is 3. The description largely restates the schema (mode semantics, channel handle without @, limit range) and adds no syntax or format detail the schema lacks.

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 ('YouTube video search by keyword, or the videos of one channel') and pins down the two operating modes. It clearly distinguishes this from siblings like youtube-comments and youtube-transcript, which cover different resources.

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

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

It states which input each mode expects ('mode search takes keywords; mode profile takes a channel handle without the @'), giving clear routing between the two modes. However, it never states when to prefer this tool over the sibling youtube-transcript/youtube-comments tools or any exclusion criteria.

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 read-only, non-destructive, open-world profile, yet the description adds genuinely new operational facts: a hard 100-comment ceiling per call, the deliberate omission of commenter names and handles, per-call stablecoin billing, and a refund guarantee for paid-but-undelivered comments. That is exactly the behavioral context annotations cannot express.

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 tightly packed sentences with no filler. Capability and return shape come first, then the operational caveats (data omission, pricing, refunds), which is the right front-loading for an agent scanning for a match.

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

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

With no output schema, the description carries the return-value burden and does so (field list plus the explicit note that author identities are absent), and it covers cost and refunds. It stops short of describing failure modes for an invalid or non-video URL, which is the one remaining gap for a paid open-world fetch.

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 documents url, sort (with enum) and limit (with defaults, bounds, and clamping behavior). The description only echoes the 100-comment cap, adding no meaning beyond what the schema provides, 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 (get) and resource (comments under a YouTube video) and enumerates the return fields: text, time, likes, reply count. This cleanly separates it from the sibling youtube-transcript and from review-comment tools for other platforms, so an agent can route correctly without opening the schema.

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

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

Usage is implied by the input shape ('send the URL of a video'), and the per-call cap of 100 comments hints at scope, but there is no explicit statement of when to use this over youtube-transcript or when-not to use it at all. Adequate but leaves routing to inference.

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

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

Beyond the annotations (which already mark this read-only, open-world and non-destructive), the description adds meaningful behavioral context: the no-speech-to-text constraint and the cost rule that a video lacking the requested language is not charged. It does not cover rate limits or pagination, but the added cost/limitation disclosure is real value over structured fields.

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

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

Dense but front-loaded: capability, inputs, outputs, constraints and cost are each covered in one tight sentence with little waste. Slightly packed, but every clause carries information an agent needs.

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

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

With no output schema, the description usefully names the returned fields (segments, title, channel, duration, views, publish date) and the available formats, so an agent knows what it gets back. Only edge behavior (errors, empty results) is left unaddressed, which is minor here.

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

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

With schema coverage at 100% the baseline is 3, and the description goes further by restating that video accepts a URL or 11-char id, that lang spans ten languages plus 'any', and that format yields timed JSON or a single SRT/VTT/text string. This adds format semantics beyond the raw enum lists.

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 ('send a video URL or 11-character id and get its published subtitles'), and its scope as a transcript-only tool is clear against siblings like youtube (metadata) and youtube-comments. An agent can tell it apart without opening the schema.

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

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

The description discloses a key when-not ('No speech-to-text') and the schema routes input away from channels/playlists/search, giving clear context. However, it never names an alternative tool or the condition that would send the agent to youtube comments or plain youtube instead, so routing is inferred rather than explicit.

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