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

With no annotations provided, the description carries the full behavioral disclosure burden and does so well: it names the public API source, states no setup is needed, explains that results are in App Store relevance order, and caps the limit at 50. It does not mention rate limits, data freshness, or error behavior, but for a read-only search tool the disclosed behavior is reasonably complete.

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 organized with clear Args and Returns sections and keeps each parameter explanation short. The opening sentence is slightly awkward and could be tightened, but there is no redundant filler and the most important details are front-loaded.

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 search tool with no output schema and no annotations, the description is quite complete: it documents all parameters, explains the return fields, and notes ordering and the rating-count proxy. It could add edge-case behavior like empty results or country-specific quirks, but nothing essential is missing for calling 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 0%, so the description fully compensates by documenting every parameter: query with examples, country with ISO code format and default, and limit with its 50 cap. This adds meaningful semantics beyond the raw JSON schema types and defaults.

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 returning existing iPhone/iPad apps matching a query from Apple's public iTunes Search API. It conveys the search behavior and domain, though it lacks a crisp verb like 'search' and does not explicitly differentiate from sibling tools. The odd phrasing 'who already serves this need' slightly weakens clarity but does not obscure the purpose.

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

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

It explains the use case: finding apps that already serve a need and using rating count as a proxy for user base, plus 'No setup needed' signals ease of use. It does not provide explicit when-not-to-use guidance or name alternative tools, but the sibling list contains no direct app-store alternative, so the implied context is sufficient.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It openly describes the data sources, optional GITHUB_TOKEN requirement, rate-limit implications, and return structure including that GitHub results are the top 10 by stars. It does not mention edge cases or failure modes, but it is substantially transparent for a read-style search tool.

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

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

The description is well-structured with a clear purpose statement, setup note, alternative routing, and an Args/Returns breakdown. Every sentence contributes useful information, and the return format is compactly documented. It earns its length.

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

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

Given a single parameter, no annotations, and no output schema, the description is remarkably complete. It explains the query semantics, the result shape, per-item fields, the GitHub top-10 behavior, rate limits, and an important alternative for Product Hunt. An agent has enough information to invoke the tool correctly and interpret its 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?

Schema description coverage is 0%, so the description must fully explain the single query parameter. It does so clearly: 'search terms, e.g. a product category ("habit tracker") or problem.' This adds meaningful semantic guidance beyond the bare schema's type and required flag.

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's function: combining Hacker News stories and GitHub repositories into a 'builder signal'. It distinguishes itself from sibling tools by contrasting with 'search interest or community chatter' and mentions specific sources, making it easy for an agent to disambiguate from tools like related_topics or interest_over_time.

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 useful context for when to use the tool: when there is interest in real building/shipping activity rather than search interest or chatter. It also provides an explicit exclusion and alternative for Product Hunt launches, directing users to web search instead. It does not exhaustively enumerate when not to use it versus every sibling, but the guidance 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?

With no annotations, the description carries full behavioral burden, and it succeeds: it discloses token requirements, rate-limit context (~50/day, 200/month), behavior when the token is unset or invalid, return format, match limit, and empty-list behavior. This gives the agent a reliable model of tool 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?

The description is longer than average but every sentence serves a purpose: scope, exclusions, auth setup, arguments, and return contract. It is front-loaded with the core purpose and structured so an agent can quickly extract what it 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?

Despite having no output schema, the description specifies the exact returned fields, the cap of 5 matches, the empty-list case, and error/setup responses. For a lookup tool with only two parameters and one sibling-group mismatch, nothing material is missing 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 0%, so the description must define the parameters, and it does: it explains that name is the company name to search, and jurisdiction is optional with concrete examples like 'in' and 'us_de'. This adds real meaning beyond the raw schema.

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

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

The description states a specific verb and resource ('Company registration lookup via OpenCorporates') and immediately scopes it to registration facts only. It also explicitly distinguishes itself from funding/valuation/traction data, so an agent can tell exactly what this tool is and is not for.

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 explains when to use it (registration lookup) and when not to use it (funding, valuation, or traction data), noting that no free API exists for those. It also gives setup prerequisites for the required token, which is essential operational 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the output format, the scale (0-100) and its meaning, and the difference between 'concise' and 'full' response formats. It also notes the relative nature of interest scores. It does not mention potential limitations (e.g., rate limits, data availability), but the core behavior is transparent.

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 well-organized with a clear opening purpose, followed by args and returns. It is detailed but not verbose; every sentence adds value. The structure is logical, though the args/returns section is somewhat lengthy, but that is justified given the need to explain the output format.

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 tool has 4 parameters, no output schema, and no annotations. The description covers all parameters, explains the output structure precisely, and gives examples. It is complete enough for an agent to call correctly without further information. No critical information 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 0%, so the description must explain all parameters. It does so thoroughly: keyword (single search term), timeframe (with example 'today 12-m'), geo (ISO codes, '' for worldwide), and response_format (with definitions of 'concise' and 'full'). It adds meaning well beyond the schema's bare types.

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 tool's purpose: searching interest for a keyword broken down by state/region within a country, or by country when geo is empty. This is a specific verb+resource combination that distinguishes it from sibling tools like interest_over_time (time series) and related_topics (related queries).

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 clearly indicates when to use this tool: when you need regional breakdown of interest within a country, or by country worldwide. It does not explicitly state when not to use it, but the context is clear and the parameter descriptions (geo, timeframe) provide implicit guidance. The return format explanation further clarifies 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?

With no annotations, the description carries full behavioral disclosure. It reveals key quirks: extra keywords beyond 5 are silently dropped, 'concise' mode thins to ~26 evenly spaced points with rounding, and 'isPartial' appears only for incomplete periods. This is unusually transparent and useful for an 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 long but every section earns its place: purpose, parameter semantics, and return format. It is front-loaded with the core purpose and structured into Args/Returns, making it easy for an agent to scan.

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 return-structure explanation is essential and provided in detail: date, isPartial semantics, and per-keyword interest values. All four parameters are covered, and the behavioral nuances are disclosed. Nothing critical is missing for an agent to invoke the tool correctly.

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

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

Schema coverage is 0%, so the description must document all parameters. It does so comprehensively: keywords with the 1-5 limit and drop behavior, timeframe with pytrends string examples, geo with country-code examples and default, and response_format with both modes fully explained.

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: it retrieves relative Google search interest (0-100) over time for up to 5 keywords. It also communicates the comparative, time-series nature that distinguishes it from siblings like interest_by_region or related_topics.

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 clearly conveys the tool's context: search-interest trends over time, compared across keywords, with geographic filtering. It also gives specific guidance on when to use 'concise' vs 'full' response formats. It does not explicitly name alternatives or exclusion conditions, but the intended use is strongly implied.

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

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

With no annotations, the description carries full responsibility for behavioral disclosure, and it delivers: it explains the data source (Google News), the capped result set, how 'total' and 'last_30_days' should be interpreted as rough gauges rather than exact counts, the newest-first ordering, and the use of Google News' `when:` filter. This is strong transparency beyond the bare 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?

The description is well-structured with a clear lead sentence, an Args section, and a Returns section. It is somewhat longer than strictly necessary, but the extra details (cap caveat, newest first, rough attention gauge) are genuinely useful and not redundant 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?

Even with no output schema, the description fully specifies the return structure, field semantics, and important caveats about counts. It also covers setup expectations ('No setup needed') and the tool's intended analytical uses, so an agent has enough context to select and 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 0%, so the description must compensate, and it does thoroughly: query is defined as search terms, geo as an ISO country code with examples, recent as a time range with the underlying filter explained, and limit as a max-headline count with a note about Google's ~100 cap. It adds meaning and usage guidance that the schema alone does not provide.

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: 'Recent news coverage from Google News' and immediately frames the purpose ('is the press writing about this, and what angle are they taking?'). The use cases (funding rounds, regulation, launches, attention trends) make it clear what this tool does and how it differs from the sibling tools like related_topics or interest_over_time.

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 clear context for when to use the tool ('Usable for spotting funding rounds, regulation, launches, and whether a topic is getting more or less attention') and notes 'No setup needed.' It does not explicitly name alternatives or say when not to use it, but the stated use cases are sufficient orientation.

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

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses rate limits, mode differences (public feed omits scores; API adds score and comment counts), setup prerequisites via /gutcheck setup, and the loose-matching/ranking behavior of the keyless search. This is strong behavioral disclosure beyond typical one-line definitions.

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?

Despite length, the description is front-loaded (purpose first) and every section earns its place: signal type, mode setup, args, querying heuristics, and return format. The structured Args/Returns layout makes the extra behavioral context navigable rather than 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?

Because there is no output schema, the description supplies the return record fields and mode-dependent omission of score/num_comments, which is essential. It also covers prerequisites, rate limiting, and parameter behaviors, leaving little an agent needs to infer before calling.

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

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

Schema description coverage is 0%, so the description must compensate, and it defines all four parameters: query as search terms, subreddits as optional restriction with examples, limit as max results capped at 100, and time_filter with valid values and default. The only schema-default it omits is limit's 25, which the schema itself exposes.

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 identifies the resource (Reddit), the kind of data (qualitative posts by real people), and explicitly contrasts it with 'Trends/Wikipedia's passive search/reading numbers,' making sibling differentiation obvious. The query argument and return record names make it clear this is a Reddit post-search/signal tool.

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 positions the tool as qualitative community signal versus Trends/Wikipedia numeric data and gives concrete query/subreddit guidance ('Keep the query short (2-4 words) and pass subreddits when obvious communities exist'). It clearly explains when API mode will be used versus the keyless feed, but it never states an explicit 'use when / do not use when' rule, so no hard exclusion is given.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does well by explaining the response_format behavior (concise vs full), the sorting and rounding behavior, and the critical Breakout marker semantics. It doesn't mention rate limits or auth, but for a read-only query tool, the behavioral details provided are substantial.

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 well-structured with clear sections for args and returns. It is somewhat verbose but every sentence earns its place, especially the Breakout marker explanation. The front-loaded purpose statement is clear, and the formatting is 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?

Given the tool has no output schema and no annotations, the description does a strong job of explaining the return structure and key value semantics. It covers the main parameters and the critical edge case (Breakout). Minor gaps include lack of error handling or pagination details, but for a single-keyword query tool, the description is largely complete.

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

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

Schema description coverage is 0%, so the description must compensate. It explains keyword, timeframe, geo, and response_format with examples and defaults. The description adds meaning beyond the schema by explaining the response_format values and the geo default. It doesn't detail every nuance of timeframe strings, but provides a representative example.

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 tool returns 'Top and rising related search queries for a single keyword,' which is a specific verb+resource combination. It distinguishes itself from siblings like related_topics by focusing on queries rather than topics, and the scope is unambiguous.

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

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

The description provides clear context on when to use the tool: for a single keyword's related search queries. It doesn't explicitly name alternatives or exclusions, but the sibling list and the focused scope imply usage. The 'IMPORTANT' note about the 5000% Breakout marker adds critical usage guidance for interpreting results.

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

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

With no annotations, the description carries the full burden and excels: it defines the output dictionary structure, explains the 'concise' vs 'full' formatting behavior, and explicitly warns that a value of 5000% is Google's Breakout marker, not a literal percentage increase. This goes well beyond a bare statement of what the tool does.

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 well structured with Args and Returns sections, front-loads the primary purpose, and every sentence adds meaningful detail. The Breakout warning is prominent but earned, not 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?

There is no output schema, so the description must explain return values; it does so with the dict keys, record fields, value scale, and format differences. For a tool with four parameters and no annotations, this is a complete and self-sufficient definition.

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

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

Schema description coverage is 0%, and the description compensates completely. Every parameter is documented: keyword is a single search term, timeframe gets a pytrends example, geo gets ISO country examples and 'worldwide' behavior, and response_format gets detailed formatting and sorting rules.

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

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

The description names the resource: top and rising related topics for a single keyword, and adds the crucial disambiguation 'Google's topic clusters, not raw query strings' against the related_queries sibling. It lacks an explicit verb like 'returns' or 'retrieves', so it stops just short of a perfect purpose statement.

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 clear context: use for a single keyword and for Google topic clusters rather than raw query strings. The exclusion of raw query strings is an explicit when-not signal, though it never names related_queries directly or gives a fuller when-to-use/alternative comparison.

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

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

With no annotations provided, the description carries the full burden and does so thoroughly. It discloses free/no-auth access, monthly granularity, human-only traffic (bot traffic excluded by Wikimedia's 'user' agent filter), all access methods, and the behavior of response_format. It also notes automatic space handling and supported duration forms.

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 well-structured: purpose first, then usage context, then parameter details, then return format. Every sentence contributes useful information without filler or redundancy, and the sections are easy to parse.

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?

Given no output schema and no annotations, the description is operationally complete. It specifies all inputs with defaults, explains the output record structure, and documents behavioral caveats such as bot filtering and response format differences. An agent can invoke it correctly without additional documentation.

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

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

Schema description coverage is 0%, but the description fully compensates. For article it gives title format and space-handling behavior; for timeframe it lists duration examples, the default, and supported forms; for response_format it explains 'concise' vs 'full' and the default. This adds significant meaning beyond the bare 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 opens with a specific verb and resource: 'Monthly Wikipedia pageview counts for an article.' It further distinguishes itself from Google Trends' search-interest signal by framing it as a free, no-auth reference/reading-interest signal, making its purpose and differentiation clear.

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

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

It clearly positions the tool as complementary to Google Trends and explains that divergence between the two signals can be worth flagging, giving the agent context on when to use it. It does not explicitly name sibling tools or state when not to use it, but the guidance is sufficiently 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?

With no annotations, the description carries the full burden and does well: it discloses the required YOUTUBE_API_KEY, quota consumption of about 101 units per call, and the fallback behavior of returning setup instructions if no key is saved. It does not cover API error cases, but the main behavioral traits are transparent.

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 well organized into purpose, preconditions, arguments, and return value, with the main purpose front-loaded. There is slight redundancy in repeating view/comment counts in both the opening and the Returns section, but overall it is compact 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?

For a 3-parameter tool with an output schema, the description is complete: it covers setup, quota, parameter semantics, return shape, and the no-key fallback. An agent has enough context to select and invoke the tool correctly without needing additional documentation.

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

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

Schema description coverage is 0%, so the Args section is essential and fully compensates. It defines query as search terms, explains limit is capped at 25, and clarifies published_after_days filters to the last N days or can be omitted for any time period. This adds real meaning beyond the bare schema types and defaults.

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: 'YouTube videos matching a query, with view and comment counts.' It also clarifies the tool's role as a consumer-interest signal compared to search volume, making it distinct from unrelated siblings like reddit_signal, news_coverage, and related_topics.

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 clear use context: to measure how much people watch content about a topic, with examples like tutorials and reviews, and notes this is often stronger than search volume. It includes the important API-key prerequisite, but does not explicitly say when to prefer an alternative sibling or when not to use this tool.

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