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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety semantics are covered. The description adds useful content-level context (that a full body text is returned, not a summary), but says nothing about auth requirements, rate limits, or what happens when a URL cannot be mapped to an indexed article.

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 sentence that front-loads the verb and resource, then lists the lookup mechanisms and returned fields. No filler, no repetition of the title.

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

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

With no output schema, the description carries the return-value burden and does so by naming the returned fields. It is nearly complete, lacking only guidance on batching limits and partial-failure behavior for URLs not in the index.

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 67%, so the schema already documents uris, urls, body_chars and response_format. The description reinforces the two lookup keys but adds nothing about result_lang, include_concepts, or the practical caps (100 URIs / 20 URLs), so it neither compensates for nor extends the schema meaningfully.

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

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

States a specific verb (fetch) and resource (full articles) plus the two lookup keys (newsapi.ai URI from search results, or original article URL), and enumerates the payload (body text, authors, concepts, categories). This clearly separates it from newsapi_search_articles, which returns the URIs this tool consumes.

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 parenthetical '(from search results)' establishes the intended workflow: run newsapi_search_articles first, then hydrate results here. There is no explicit when-not guidance or mention of the sibling alternatives (e.g. when to prefer raw_request), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so the safety profile is covered. The description adds useful substance by naming the returned fields (summary, concepts, location) and the optional article inclusion, but says nothing about payload size, language fallback, or cost of pulling articles.

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 that names the resource first and the optional add-on second, with no filler. It is appropriately sized, though it is arguably too thin given the seven parameters it governs.

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's list of returned fields is genuinely valuable and covers the main shape of the response. However it leaves the two undocumented parameters (notably body_chars and its -1 sentinel) and any language behaviour unaddressed, which is thin for a seven-parameter tool.

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

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

Schema coverage is 71% and the description adds no parameter meaning at all. Two parameters are undocumented even in the schema — body_chars (whose minimum of -1 is unexplained and whose effect on the 'summary' is unstated) and result_lang — so the description fails to compensate for the coverage gap.

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 ('Details for one event') and enumerates the payload (summary, concepts, location, plus optional articles), which separates it from newsapi_search_events at a glance. It does not explicitly name a sibling, 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?

There is no when-to-use or when-not-to-use guidance and no named alternative; the reader must infer from 'one event' that this follows a search and takes an event_uri. 'Optionally its top articles' hints at the articles_count parameter but is not framed as guidance.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true and idempotentHint=false, so safety and scope are partly covered. The description adds genuinely useful behavior beyond that: the API key is injected automatically (so no auth param is needed) and the path is constrained to the /api/v1/ namespace. It does not mention rate limits or explain why the operation is not idempotent, which keeps it short of a 5.

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

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

Two sentences, zero waste. The escape-hatch nature and the endpoint scope are front-loaded, and the routing advice comes last where it is most actionable.

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 an intentionally open-ended passthrough tool with only two parameters and no output schema, the description covers identity, scope, auth handling and routing to siblings. It could say a bit more about what a caller gets back or how errors surface for invalid paths, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes further by showing what a valid path looks like and demonstrating a body parameter in context (resultType=conceptTrends), which is meaningful guidance for the free-form 'params' object that the schema can only describe as an unconstrained map.

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 mechanism (POST arbitrary parameters to any newsapi.ai endpoint under /api/v1/) and gives three concrete endpoint examples including one with a query-style parameter. It explicitly differentiates itself from the sibling tools by framing itself as an 'escape hatch' and telling the agent to prefer dedicated tools when they fit.

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

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

It gives a clear when-not rule: 'Prefer the dedicated tools when they fit,' which tells the agent this is the fallback for endpoints/parameters the dedicated tools don't cover. What's missing is an explicit mapping of which sibling covers which endpoint (e.g. that getArticles maps to newsapi_search_articles), so the agent must infer that from the sibling names.

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, so the bar is lowered, and the description still adds real behavioral context: token consumption per call, higher cost for archive queries beyond 31 days, and the default compact vs raw response shape. It does not describe pagination limits or rate limits, but the added cost/return-shape disclosure is substantive.

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

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

Four tight sentences: scope first, then filtering, then the entity-resolution rule, then cost and return-format caveats. No filler, and the most decision-relevant facts 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 35-parameter tool with no output schema, the description covers scope, key filtering dimensions, the resolution workflow for URI parameters, cost implications and return format. It omits guidance on the advanced_query override interaction with simple filters and on pagination depth, but is otherwise sufficient to call 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 86%, so the schema already documents nearly every parameter, including that source_uris/concept_uris come from newsapi_suggest. The description's URI-resolution advice largely repeats what the schema already says, so it adds little beyond 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 (search) and resource (news articles) with concrete scope: ~150k sources, filterable by keywords, concepts, categories, sources, locations, language and date. It also implicitly distinguishes itself from newsapi_suggest, which it names as the prerequisite for entity resolution.

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 actionable routing guidance: prefer concept_uris over keywords for entities and resolve them first with newsapi_suggest. Adds a cost-aware usage rule (each call consumes tokens; queries older than 31 days cost more). It does not, however, say when to use this vs newsapi_search_events, so it 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 readOnlyHint, idempotentHint, and openWorldHint, so safety and determinism are covered. The description adds the cross-language nature of event clusters, which hints at multilingual results, but says nothing about pagination, result shape, or the token cost implied by the archive window.

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

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

Three short sentences, front-loaded with the definition of an event before the use-case hint. No filler or repetition of the title.

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

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

For a 29-parameter, no-output-schema tool this is thin: the agent gets a definition of events but no sense of the returned structure (clusters, summaries, counts) or the practical cost/pagination considerations. The schema carries parameter detail, but the description leaves notable gaps for a complex 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 83%, so the schema already documents nearly all 29 parameters, including the time-window and filter semantics. The description only says filters are the same as article search, adding no new parameter meaning, which matches the baseline for high coverage.

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 (search) and resource (events), and uniquely defines the resource as 'clusters of articles (often across languages) reporting on the same real-world happening.' This definition is what lets an agent distinguish it from newsapi_search_articles, which is named explicitly.

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

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

Offers usage context ('good for what happened around X' and spotting broad coverage), which is helpful but not a routing decision. It never states when to prefer this over newsapi_search_articles or newsapi_get_event, so the agent must infer the choice from the definition of an event.

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

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

Annotations already declare readOnly/idempotent/openWorld, so safety is covered. The description adds the important precondition that this is a lookup that feeds downstream filters, but says nothing about result format, how many results, or failure behavior when a prefix has no match. With annotations covering the profile, a 3 is appropriate.

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?

Tight and front-loaded: the core purpose is stated first, then the enumerated kinds, then the ordering instruction. Slightly long in the enumeration but every clause is informative.

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?

Complete for an autocomplete-resolve tool: it names every kind, the URI target, and the sequencing relative to search tools. No output schema exists, but for a lookup tool the missing piece (what a result looks like / how many) is minor given annotations cover read-only open-world behavior.

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

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

Schema coverage is 50%; 'lang', 'count', and 'prefix' are documented in-schema (with examples), but 'kind' only appears as an enum in the schema with no in-description explanation. The description does list the concept/source/etc. values but does not map them to the 'kind' parameter, so it adds marginal value over 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?

The description states a specific verb (resolve/autocomplete) and resource (names → URIs) and enumerates exactly what each 'kind' resolves to (concepts→Wikipedia, sources→domain). It distinguishes itself from all siblings, which are search/retrieval tools that consume these 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?

Explicitly says 'Call this BEFORE filtering by entity, source or category,' which tells the agent the ordering constraint relative to the search tools. That is the key when-to-use guidance for this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint, so safety and repeatability are covered. The description adds genuine value beyond them by stating what the call reports — token availability and consumption scoped to the current plan — which the annotations do not convey.

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

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

A single, front-loaded sentence that states the resource and scope with zero filler. Nothing is wasted and nothing essential is omitted.

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 hint at the return content, and it does so by naming token availability, consumption and plan scope. It stops short of specifying the exact fields or units returned, but for a zero-parameter reporting tool this is close to 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly implies no input is needed.

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

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

The description gives a specific verb ('Show') and a precise resource (newsapi.ai API tokens available and used on the current plan). This clearly differentiates it from retrieval siblings like newsapi_search_articles and newsapi_get_event, though it does not name 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 only implied: an agent can infer this is a quota-check tool to consult before or after making requests. There is no explicit statement of when to call it versus alternatives, nor any prerequisites, so it lands at the minimum-viable level.

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