Atmy air quality

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so the safety profile is covered; the description earns credit for adding computation semantics the annotations cannot express — the mean-of-latest-sensor-reading aggregation and the 60-minute staleness cutoff. It does not address rate limits or failure behavior when no sensor or city is in range, which the schema only partially covers via the 50 km rule.

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 return payload is front-loaded in the first clause and the invocation hint is a short separate sentence. The result clause is dense and run-on (nested parentheses listing seven weather fields), but essentially 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 carries the full return-shape burden and does so thoroughly — PM2.5 plus category, current weather sub-fields, and the prior-day summary. Combined with 100%-covered parameters and full annotations, 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 100%, so the schema already documents lat/lon/city/lang/country in detail, making the baseline 3. The description adds only the either/or framing of city vs lat/lon, with no extra syntax, precedence, or default behavior beyond what the schema provides.

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

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

States a specific resource (PM2.5 now for a city) plus the exact composite payload: EPA category, current weather fields, and the last completed day. The 'now' framing plus the explicitly named daily historical component inherently separates it from get_air_quality_history, get_air_quality_monthly, and get_city_forecast.

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 closing 'Pass city or lat/lon' gives concrete invocation guidance on the two mutually exclusive location modes, but there is no statement about when a caller should prefer this over get_air_quality_history, get_air_quality_monthly, or get_city_forecast. Usage is implied by the word 'now' 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the description only needs to add operational context. It does: UTC-day bucketing, sensors passing a quality check, a 2017 floor, a 400-day cap per call, and 'last completed day' as the implicit default. It does not cover truncation/pagination behavior when a range is near the cap.

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

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

Two sentences, resource and data source front-loaded, with the sibling routing last. The first sentence is densely nested with parentheticals and the 2026-01-19 clause, which costs some readability, but there is no filler.

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

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

For an 8-parameter, all-optional tool with no output schema, the description lists the returned measures (PM2.5 plus temperature/humidity/pressure/wind/gust/clouds) and the date semantics, which is what an agent needs to call it correctly. Remaining gaps are response shape details and the meaning of the 2026-01-19 reference.

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 100% schema description coverage the baseline is 3, and the description earns an increment by stating the 400-day span cap on from/to, a constraint absent from the schema's per-field bounds. It also reinforces that 'days' is ignored with from/to, though that particular fact is already in the schema.

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

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

The description names a specific verb+resource: daily PM2.5 values for a city from a named data source, enriched with same-day weather variables. It also differentiates itself from get_air_quality_monthly by pointing to it for whole-history needs. The only blemish is the ambiguous 'weather from 2026-01-19' clause, which can be misread as a start date and sit awkwardly next to 'since 2017'.

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 concrete modes of use (default last days, or an explicit from/to span), gives the hard constraint of at most 400 days per call, and names the alternative tool for whole history or records. The agent has an explicit routing rule rather than having to infer one.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuine context beyond that: the data source (Atmy Data Hub), the epoch (from 2026-01), that yearly means flag complete years, and that the response includes ranked dirtiest/cleanest months and days. The one miss is that 'whole measurement history' implies a potentially large payload with no note on response size or paging.

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, no filler, with the data-inventory front-loaded and the use-case framing second. The first sentence is dense with semicolon-chained clauses 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?

For a five-parameter, zero-required, no-output-schema read tool, the description covers what comes back (monthly PM2.5, weather, yearly means, extremes) well enough that absent an output schema an agent still knows the shape of the answer. The remaining gaps are ambiguity versus sibling tools and no stated behavior when the location resolves to nothing within 50 km.

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 lat/lon/city/country/lang semantics, the 50 km nearest-city rule, and the slug formats are already fully documented. The description mentions 'a city' but adds no parameter-level guidance such as how city and lat/lon interact or precedence. Baseline 3 is appropriate when the schema carries the load.

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

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

The description names a specific resource and scope: 'the whole measurement history of a city' with monthly PM2.5, weather, yearly means and extremes. It does not, however, distinguish itself from the clearly related siblings get_air_quality and get_air_quality_history, so an agent cannot tell from the text alone which of the three to pick.

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 second sentence implies usage with two example question shapes ('how has the air changed', 'the most polluted month on record'), which is helpful framing. But there is no explicit when-not guidance and no named alternative among get_air_quality / get_air_quality_history, which is the main ambiguity an agent faces here.

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 disclose read-only, idempotent, non-destructive behavior, so the description's job is to add semantics — and it does, defining the accumulation index as 'how strongly the weather keeps particles near the ground' and warning that it is an estimate rather than a measurement. That pre-empts the main misuse risk (treating the index as a PM2.5 reading), which is genuine added context beyond 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?

Two sentences, no filler. The payload enumeration and the index definition come first, and the crucial disambiguation lands last, so an agent can skim and still get the scope right.

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 six optional parameters, the description is responsible for telling the agent what comes back, and it lists all five output quantities. It stops short of units, ordering, or how lat/lon versus city selection is resolved, but those gaps are minor for a read-only forecast call.

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 83%, so the baseline is 3: lat, lon, city, lang and country are already documented in the schema. The description only gestures at the forecast horizon with 'the next hours' and never explains that 'hours' is configurable up to 72 — the one undocumented parameter — so it does not meaningfully compensate for that 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?

The description names the resource (a city's next-hours forecast) and enumerates the returned quantities: temperature, wind, humidity, precipitation and a 0–100 pollution accumulation index. It also draws a clear line against a PM2.5 forecast, which implicitly separates it from the get_air_quality sibling, though the sibling is never named.

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 final clause 'A weather estimate, not a PM2.5 forecast' gives an implicit exclusion that routes agents toward get_air_quality for actual pollutant levels. However, there is no explicit when-to-use statement and no mention of get_air_quality_history or search_cities as alternatives, so the routing is left 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 readOnlyHint, idempotentHint, non-destructive and closed-world, so the safety profile needs no repetition. The description still adds real value by pinning the data window to the last completed day (i.e., not live) and naming the upstream source, Atmy Data Hub.

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?

One sentence, front-loaded with the resource and ranking key, with the ordering note appended where it is most useful. No filler or restated field names.

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 5-parameter tool with no output schema, the description covers the core question (what is ranked, over what period, in what order) but leaves the return shape, units, and behavior on an unrecognized country to inference. Adequate, not 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 coverage is 60%: country, lang and settlements are already documented in the schema, so the description only meaningfully reinforces the order values ('most polluted or cleanest first'). The limit parameter (min 1, max 50, default 10) is never explained in either place.

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: cities within a country ranked by daily PM2.5 for the last completed day, with an explicit ordering dimension. That is enough to tell it apart from get_air_quality (single place) and search_cities (lookup), though it never names those siblings 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: the 'last completed day' framing suggests a retrospective snapshot rather than a forecast or live reading, which implicitly rules out get_city_forecast. There is no explicit statement of when to pick this over get_air_quality_history or what happens for an unknown country.

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=false, so the safety profile is covered. The description adds that matching works across any language and that the payload is a list of slugs, but says nothing about match semantics (prefix vs substring), empty-result behavior, or how limit truncation works.

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 filler, and the capability statement is front-loaded ahead of the return-value hint. Nothing repeats the tool title verbatim.

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 states what comes back (slugs for other tools), which is the single most important thing an agent needs to chain calls. Minor gap: no mention of result limits/pagination even though a limit parameter exists.

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 75% and lang, query and country each carry their own descriptions; only limit is undocumented. The description restates the query/country dimensions 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?

States a concrete verb and resource ("Find the cities with an Atmy air-quality summary") plus the lookup dimensions (name in any language, or country). The closing clause "Returns slugs to pass to the other tools" positions it as the discovery step feeding the other tools, which implicitly separates it from get_air_quality and siblings, though no sibling 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?

"Returns slugs to pass to the other tools" gives clear workflow context: call this first to resolve a city slug, then call the retrieval tools. There are no explicit exclusions (e.g. when to use get_country_ranking instead), so it stops short of the 5 band.

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