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

readOnlyHint=true already establishes it is a safe read, so the description adds the cost model (1 token per call) and the fact that the body is length-bounded by default at 3000 chars. It does not describe truncation indicators, invalid-URI behavior, or what happens when body_len=0, so a small gap remains.

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

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

Three tight sentences, front-loaded with what the tool returns and the identifier it needs, then the usage condition, then the cost. Every clause carries information an agent needs; no filler.

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

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

For a two-parameter read tool with no output schema, the description covers the input source, the retrieval semantics, the default body length, and the cost. It leaves the response shape only implicitly described (article with body field), but an agent has enough 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%: both article_uri and body_len (with its 0-20000 range and default) are already documented in the schema. The description restates the default 3000 and the URI provenance but adds no syntax, format, 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 (get) and resource (one article) and scopes it to the URI returned by search_articles, which is the exact identifier the sibling produces. An agent can immediately tell this apart from search_articles, which returns headlines rather than full body text.

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

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

Gives an explicit sequencing rule: 'Use after search_articles when you need to read the article rather than just its headline.' It names the alternative and the condition that selects this tool, plus a cost signal (1 token per call) for budget-aware planning.

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 readOnlyHint=true, so the description carries real weight and delivers it: default view, mode switch, pagination default (5 per page), body truncation via body_len, and a concrete token cost per view that is "measured live." Cost and truncation behavior are not derivable from any structured field.

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

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

Three tight sentences, front-loaded with the identifying URI pattern, then mode behavior, then cost. No sentence can be removed without losing an actionable fact.

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 must characterize returns and does: summary info by default, a paginated article list otherwise, with truncation and cost specified. An agent has everything needed to call it correctly and predict the response shape.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by explaining that include_articles switches the entire response shape rather than merely adding a field, and by surfacing the pagination default and body_len truncation in prose. It stops short of explaining articles_page/articles_count interactions in depth.

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 one event by URI") and immediately distinguishes two operating modes: default summary info vs. an articles listing via include_articles=true. The reference to the `uri` from search_events makes it trivially separable from the sibling search_events and get_article tools.

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

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

Clearly routes the agent: obtain the URI from search_events, and choose include_articles when the goal is the covering articles rather than event info. It does not explicitly contrast itself with get_article for the articles view, so the alternative-selection guidance is slightly incomplete, but the context for use is unambiguous.

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 readOnlyHint annotation: it discloses the exact cost (10 tokens per call, regardless of count), warns that blog trends may be 'not computed' yet still billed, and explains the comparison window used to compute trends. This is precisely the kind of billing and failure-mode context an agent needs before calling.

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

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

Front-loads the purpose and computation, then layers source and cost caveats. It is dense with parentheticals and could be split for readability, but every sentence carries non-redundant 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?

Covers the essentials for a 3-parameter read tool with no output schema: what is returned, how it is computed, source behavior, defaults, and cost. The only gap is that it doesn't describe the shape of a returned trend entry, which is minor given there is no output schema to lean on.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: it explains that `source` switches the underlying data pipeline, calls out the blog-plan caveat not visible in the enum, and restates the default result shape (top 10 people/organisations/places in news). `count` and `concept_types` are left to the schema, keeping it at 4 rather than 5.

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

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

States a specific verb and resource ('get the concepts... trending right now in the news') and even explains the computation (last 2 days vs last 2 weeks). It does not explicitly distinguish itself from the sibling `suggest_concepts`, which is the one tool an agent might confuse it with, 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 a clear when-to-use signal ('trending right now'), a source-selection rule, and an explicit when-not-to-overuse instruction ('the priciest tool, use sparingly'). It does not name an alternative tool for non-trending concept lookups, so it lacks the explicit alternative routing that would earn a 5.

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

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

Beyond the readOnlyHint annotation it discloses that the call costs nothing, that it also reports the server session budget (NEWSAPI_AI_MAX_TOKENS_PER_SESSION, default 200), and — importantly — that calls exceeding that budget fail locally without reaching the API. That is exactly the kind of failure-mode context annotations do not carry.

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

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

Front-loaded with purpose, then usage, then the cost table, then the session-budget caveat. Every sentence carries actionable content, though the parenthetical cost list and the session-budget note make it longer than a purely minimal definition.

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 parameters, no output schema, and only a readOnlyHint annotation, the description still tells the agent everything needed: what it returns, when to call it, what it costs, and how the session budget can cause a local failure. Nothing material is missing.

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

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

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing further the description could add about parameter meaning, and it appropriately spends its words on cost behavior instead.

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 the token budget of this NewsAPI.ai account' — and immediately enumerates what is returned (available, used, remaining for the current period). It is clearly distinct from the search/get/suggest siblings in the sibling list.

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

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

Explicitly prescribes when to call it ('before a batch of searches') and supplies a concrete cost table for the alternatives (search_articles/get_article 1, search_events/get_event 5, get_trending_concepts 10), plus the note that suggest tools are free. That is a direct decision aid for choosing among 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?

With readOnlyHint=true already covering safety, the description adds substantial behavioral context: token cost per call, extra archive cost per year touched, the 31-day default window, duplicate skipping, compact result shape, and pagination behavior. These are operational traits an agent needs before calling the 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 dense but appropriately sized for a 22-parameter search tool, and the core action plus cost model are front-loaded. There is some slight repetition around suggest_concepts/concept_uris, but it is 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?

For a complex search tool with no output schema, the description covers query requirements, cost constraints, default time window, result fields, truncation behavior, deduplication, sorting defaults, and pagination. It gives the agent enough context to call the tool correctly without needing to inspect sibling tools first.

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 adds meaningful cross-parameter semantics beyond the schema, especially the any-of requirement across keyword/concept_uris/category_uris/source_uris/location_uris and practical guidance on concept-vs-keyword usage, archive cost, and pagination.

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 news articles via NewsAPI.ai / Event Registry. It also makes the article-search scope clear against article-fetching and event-search siblings by focusing on article retrieval and naming the suggest_* tools used to resolve search filters.

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

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

It gives explicit invocation guidance: at least one of keyword, concept_uris, category_uris, source_uris, or location_uris is required. It also states when to prefer concept_uris over keyword and directs the agent to suggest_concepts for named entities, while explaining archive-cost tradeoffs and pagination.

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 readOnlyHint, it discloses a concrete cost model (5 tokens per call in the 31-day window, extra per archive year), the at-least-one-filter requirement that the schema's empty `required` array does not convey, and the default ordering. It stops short of describing pagination limits or result-count behavior for the event list, but the operational constraints are unusually well surfaced.

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 definition and the payoff ("one event replaces dozens of near-duplicate articles"), then cost, then the required-filter constraint, then routing guidance. Dense but nearly every sentence carries decision-relevant information; the token-cost phrase is slightly parenthetical 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?

For a 15-parameter, no-output-schema search tool, the description covers the resource model, cost model, mandatory filter rule, defaults, sorting strategy, and per-filter routing to sibling suggest_* tools. An agent can construct a correct call without consulting 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 coverage is 100%, so baseline is 3; the description still adds selection guidance the schema cannot, e.g. preferring concept_uris over keyword because of homonym noise and choosing sort_by="size" for biggest stories. The per-year archive cost implication of allow_archive also extends the schema's terse note.

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 news EVENTS") and immediately defines the resource as clusters of articles about one real-world happening, listing the fields returned. It explicitly separates itself from search_articles (event vs article granularity) and points to get_event for single-event detail.

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

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

Gives an explicit use case ("what is happening with X"), an explicit exclusion (don't use keyword for named entities), and names the routing tools: suggest_concepts for entities, suggest_sources/suggest_categories/suggest_locations for other filters, get_event for details. It also explains the cost trade-off that governs when to use allow_archive.

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

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

Annotations already establish readOnlyHint=true, so the safety profile is covered. The description adds a non-obvious operational trait — that this call does not consume search tokens — which is exactly the kind of cost/quota context annotations cannot express. It omits pagination/ordering behavior, but that is minor here.

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

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

Three tight sentences, front-loaded with the core resolution behavior, followed by the integration instruction and the quota note. No filler or redundancy.

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

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

With no output schema, the description usefully implies the return shape (items carrying a uri such as news/Business) and how to consume it downstream, which is the most important thing an agent needs. Minor gaps remain around ordering/pagination and the relationship to sibling suggest 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% (page, count, and prefix all documented in-schema), so the baseline is 3. The description adds no format or constraint detail about prefix, page, or count beyond the schema, nor does it clarify the default paging semantics.

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

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

States a specific verb and transformation: resolve a topic name into category URIs, with two concrete example outputs. It stops short of differentiating itself from the near-identical siblings suggest_concepts / suggest_sources / suggest_locations, so the agent must infer that this one is specifically for category URIs.

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

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

It gives a downstream workflow hint (pass the returned uri as category_uris to search_articles / search_events), which is genuinely useful. However it never says when to choose this tool over the sibling suggest_* tools or what input shape is expected beyond the schema's prefix description, so usage is implied rather than stated.

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

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

Annotations already declare readOnlyHint=true, but the description adds useful behavioral context: results are sorted by news prominence, and callers should inspect `type` and `label` to disambiguate homonyms. It does not mention pagination or result volume, but the core behavioral traits are well surfaced.

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

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

The description is front-loaded with the core purpose, followed by precise downstream usage and a single disambiguation note. Every sentence adds signal, with no repetition or filler.

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

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

For a read-only suggestion tool with full parameter schema coverage, the description covers the essential gaps: what the output is, how to use it, token behavior, ordering, and homonym handling. No output schema exists, but the returned fields are adequately described.

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 five parameters are already well documented. The description adds only indirect guidance about the returned `uri`, `type`, and `label`, not the `prefix`, `lang`, `page`, `count`, or `types` inputs, so the 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-resource pair: resolve a name to concept URIs, with the resource kinds enumerated (people, organisations, places, Wikipedia topics). This clearly distinguishes it from sibling suggestion tools like suggest_sources or suggest_categories.

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

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

Explicitly says to pass the returned `uri` as `concept_uris` to search_articles / search_events and contrasts this with keyword search. It also states that the tool does not consume search tokens, giving a clear operational reason to use it.

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

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

Annotations cover only readOnlyHint=true; the description adds genuinely useful behavioral context beyond that ('Does not consume search tokens') and clarifies the return type is a location URI, which matters for a resolver tool. It omits pagination/limit nuance, but the token-cost note is a meaningful addition.

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

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

Three tight sentences, front-loaded with purpose, followed by the integration path and the token-cost caveat. No filler.

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

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

With no output schema, the description correctly explains what is returned (a location URI) and how to use it, plus the token-cost trait. It is complete enough to invoke correctly, missing only edge-case behavior (empty results, pagination).

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 lang, page, count and prefix are already documented with defaults and ranges. The description only references the output `uri`, adding nothing about input parameter semantics; baseline 3 applies.

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

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

The description gives a precise verb+resource ('Resolve a city or country name to a location URI') and immediately names the siblings that consume the result. An agent can distinguish this from suggest_concepts/suggest_categories/suggest_sources without opening any schema.

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

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

Explicitly states the usage path: pass the returned `uri` as `location_uris` to search_articles/search_events. It gives clear context for when to reach for this tool, though it does not state when NOT to use it or how it differs from the other suggest_* tools.

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, so the safety profile is covered. The description adds useful context that it 'does not consume search tokens,' but does not describe the return format or pagination, which are left implicit.

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 with zero waste, front-loaded with the purpose and followed by actionable integration guidance. Every sentence earns its place.

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

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

For a read-only suggestion lookup with full schema coverage and no output schema, the description gives enough: what it returns (source URIs), how to use them downstream, and the token-cost note. A minor gap remains around result list structure and pagination, but that is largely inferable from the page/count parameters.

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 (prefix, page, count, data_types) are already documented. The description adds no parameter-level detail beyond the example 'bbc.co.uk', 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 (Resolve) and resource (publication name or domain to news source URIs), with an example. It does not explicitly distinguish itself from sibling suggestion tools like suggest_concepts or suggest_categories, but the resource is clear enough for an agent to pick it correctly.

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

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

Explains what to do with the result: 'Pass the `uri` as source_uris to search_articles / search_events.' This gives clear downstream context without naming when not to use it or alternatives among the suggest_* siblings.

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