UK Data: UK air quality (Defra)

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

Annotations already declare read-only, idempotent, non-destructive, open-world, so the description goes further and adds the traits that actually matter: only the latest 100 hourly rows are returned while aggregates span the full period, data are provisional rather than the ratified archive, and the call costs 1 credit. That truncation rule plus the data-quality caveat is exactly the kind of behavior an agent cannot get from annotations.

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

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

Front-loaded with the core contract (what is returned and how much), then scope, then caveats and cost — good ordering. The persona list ('councillors, campaigners, schools, journalists and researchers') is slightly padded, but the rest is dense and 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?

There is no output schema, so the description carries the burden of describing the response, and it does: the row cap, which statistics are computed over the whole period (min, max, mean, peak hour, daily means), and the provisional-data caveat. An agent could decide and call correctly on this alone.

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 does reinforce the either/or nature of timeseries_id vs station_id and the 1–168 hour window, but it adds no format, default, or edge-case detail beyond what the schema fields already state.

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?

Opens with a concrete verb-and-resource statement: hourly readings of one pollutant at one Defra UK-AIR monitor over 1–168 hours. It is clearly distinguishable from the sibling current-level tools (no2_level_near, pm25_level_near, air_quality_index_near) by being explicitly historical, and it names where the identifier comes from.

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 concrete use context ('when was pollution highest this week' for councillors, campaigners, journalists) and points at the other air quality tools as the source of the timeseries_id/station_id. It stops short of an explicit 'use this instead of X when…' exclusion against the current-level siblings, but the historical framing makes the split inferable.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), and the description adds substantial context beyond them: the 1-credit cost, the DAQI band and averaging methodology, the use of the nearest working AURN monitors, the fact that different pollutants may come from different nearby sites, and the explicit caveat that this is not Defra's published index or the forecast. That is meaningful provenance and expectation-setting for a read 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 answer the tool provides is front-loaded, and the second clause packs provenance, methodology and caveats without filler. It is a dense run-on sentence with a parenthetical cost note, slightly harder to scan than a short set of bullet-style clauses, but every element 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 tool with no output schema, the description sufficiently describes what comes back (index, band, health advice, driving pollutant) and how it is computed. The main omission is behavior when no working monitor falls within max_km (error vs. degraded answer), and the required/optional status of lat and lon is left slightly ambiguous versus the schema.

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 schema already documents lat, lon and max_km including ranges and the default of 25 km. The description still adds semantic value by explaining that monitors are 'nearest working' sites and that the km radius is applied per pollutant across possibly different sites, which clarifies how max_km actually behaves. It does not add anything for lat/lon, hence not a 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?

The description names a specific verb-like outcome (return the overall UK DAQI for a location) and a concrete resource (Defra AURN monitor measurements of NO2, ozone, PM2.5, PM10), plus what the response contains (index 1-10, band, health advice, driving pollutant). It is distinguishable from per-pollutant siblings such as no2_level_near or pm25_level_near because it explicitly presents itself as the aggregate 'one answer' rather than a single measurement.

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 framing 'what is the air quality near me today' gives clear when-to-use context and implicitly routes agents wanting a single headline answer here rather than to the per-pollutant or history tools. It also excludes the forecast and Defra's own published index as alternatives. It never explicitly names those sibling tools or states when not to use this one, so it falls short of a 5.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the bar is lower, yet the description still adds real behavior: each id is checked against its latest reading and tagged current/not_reporting/retired, and retired-only sites are excluded from results. It also discloses the credit cost, which no annotation conveys.

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

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

Purpose and ordering are front-loaded, followed by the status-tagging mechanism, the sibling hand-off, and audience framing. It is dense but each clause carries information; the audience list ('residents, schools, researchers and property buyers') is the one mildly expendable element.

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-shape burden and does so: it names the station id, current status values, and pollutants covered. Coverage limits and cost are also stated, so an agent has everything needed to call it and interpret the result correctly.

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

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

Schema coverage is 100%, with lat/lon ranges, limit default 10/max 10, and radius default 10/max 50 all documented in the schema. The description adds only the implicit notion of nearest-first ordering from the point; it contributes no extra meaning about limit or radius trade-offs beyond 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?

States a specific verb and resource ('Lists the official Defra AURN air quality monitoring sites near a UK point') plus ordering ('nearest first') and payload ('headline pollutants each currently measures'). It also scopes the source network explicitly, which separates it from generic pollution-index or single-pollutant siblings.

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

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

Gives an explicit downstream use ('so you know which id to pass to air_pollutant_history') and an audience framing for 'where is air pollution measured near me'. It also states a when-not: only the national automatic network, not local council diffusion tubes or low-cost sensors. It stops short of contrasting with the closest sibling, air_quality_index_near, leaving the agent to infer station-discovery vs index-value.

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 destructiveHint=false, so the safety profile is covered. The description adds genuinely new context: the Defra UK-AIR source, hourly freshness ('latest hourly'), a 1-credit cost, and the important caveat that a single monitor can be several km away and not represent your street.

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 return payload (value, units, band, advice) before the interpretive and audience framing. The middle sentence about diesel pollution and cyclists is longer than strictly necessary but earns its place as usage guidance; nothing is redundant with the annotations.

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 does the work of describing the return payload (reading in ug/m3, DAQI band 1-10 with Low to Very High, health advice) and adds a source and accuracy caveat. The main gap is edge-case behavior: it does not say what happens when no working monitor falls within max_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%, including lat/lon bounds and the max_km default of 25 with a 100 km cap, so the schema carries the parameter burden. The description mentions a 'nearest working monitor' but does not explain the search radius behavior or how max_km trades distance against representativeness, adding little beyond 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?

Names a specific pollutant, metric and source: latest hourly NO2 in ug/m3 from the nearest working Defra AURN monitor, plus DAQI band and health advice. The pollutant is embedded in the tool name and restated with domain framing ('traffic and diesel pollution'), which cleanly separates it from the pm25_level_near / pm10_level_near / ozone_level_near siblings.

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

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

Gives clear usage context by naming the exact question it answers ('how bad is the traffic pollution near me right now') and the audiences it suits (cyclists, school-run parents, people with asthma). It stops short of explicit alternatives or when-not-to-use rules, e.g. it never says to prefer air_quality_index_near for an overall index or pm25_level_near for particulates.

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/openWorld, so the safety profile is covered. The description adds genuinely non-structured context: the upstream source (Defra UK-AIR), that the figure is a measured hourly reading rather than a forecast, that the monitor must be 'working', and a 1-credit cost. It stops short of saying what happens when no monitor falls within max_km.

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 key output and its units are front-loaded in the first clause, and source, non-forecast caveat and cost are tacked on compactly. The middle sentence about summer smog and countryside-versus-city levels is interpretive padding, but it is short and helps an agent relay the value sensibly.

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 does the necessary work by spelling out the returned fields (reading, 8-hour mean, DAQI band, health advice) and the data provenance. The main gap is the no-nearby-monitor case and data staleness, which an agent cannot infer.

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

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

Schema coverage is 100% and all three parameters carry their own descriptions, so the baseline is 3. The description reinforces the 'nearest' semantics behind lat/lon and max_km but adds no range, unit or fallback detail beyond what the schema already states.

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: 'Latest hourly ground-level ozone (O3) reading in ug/m3 at the nearest working Defra AURN monitor', and enumerates the extra returns (8-hour mean, DAQI band, health advice). An agent can distinguish it from no2_level_near/pm10_level_near/pm25_level_near purely from the named pollutant and units, without opening the schema.

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

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

It gives audience framing ('suits runners and people with lung conditions in heatwaves') and an explicit exclusion ('Not a forecast'), which implies when it is appropriate. However, it never routes the agent between this and the close siblings air_quality_index_near, no2_level_near, pm10_level_near or pm25_level_near, so the choice among pollutant tools 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?

The annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the description's job is to add context -- and it does, disclosing the upstream source (Defra UK-AIR), a 1-credit cost, and the important caveat that a single monitor may not represent the user's street. It stops short of saying what happens when no working monitor falls inside max_km, which is the main unresolved behavioral question for a nearest-monitor lookup.

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 short sentences, each doing distinct work: what is returned, when it is useful, provenance, and the caveat plus cost. The pollutant and time resolution are front-loaded and nothing is redundant.

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 it well by enumerating the reading, the 24-hour mean, and the DAQI band with health advice. The gap is edge-case coverage -- behavior when the nearest monitor is beyond max_km or offline is unstated.

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

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

Schema description coverage is 100%, and the schema already documents lat/lon UK bounds and the max_km default of 25 with a 100 km cap. The description only restates the radius concept via 'nearest working ... monitor' and adds no format or tolerance detail beyond the schema, so the baseline 3 applies.

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

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

States a specific resource and measurement: the latest hourly PM10 reading in ug/m3 at the nearest working Defra AURN monitor, plus the 24-hour mean and the DAQI band with health advice. The pollutant is named outright, which lets an agent separate it from pm25_level_near, no2_level_near and ozone_level_near 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?

Gives concrete use contexts (Saharan dust episodes, construction and road dust) and an explicit exclusion, 'Not a forecast', which steers the agent away from forecast-style questions. What it does not do is name the specific alternative to call instead, so the routing is implied rather than spelled out.

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, and the description adds genuinely new behavioral facts: data source (Defra UK-AIR), that only the nearest *working* monitor is used, the representativeness caveat ('one monitor may not represent your street'), the not-a-forecast limitation, and a per-call cost of 1 credit. These are the constraints an agent needs before committing a call, and none are inferable from the annotations.

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

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

Front-loaded with the core result and the data source, then caveats and cost at the end where they belong. The parenthetical list (smoke, wood burners, traffic, bonfire night) is slightly decorative, but it earns its place by justifying the health-use framing in the same sentence.

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 return-value disclosure and does it well: hourly reading with units, 24-hour mean, DAQI band and health advice. The main omission is what happens when no monitor exists within max_km (error vs. empty), which matters given the 'nearest working monitor' framing.

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

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

Schema description coverage is 100% and all three parameters (lat, lon, max_km) carry ranges and defaults in the schema. The description reinforces that the search is 'nearest working monitor', but adds no syntax, units, or behavior for max_km exhaustion beyond what the schema states, so the baseline of 3 applies.

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

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

States a specific verb and resource: 'Latest hourly fine particulate (PM2.5) reading in ug/m3 at the nearest working Defra AURN monitor', plus the 24-hour mean and DAQI band returned alongside it. The pollutant is named explicitly, which cleanly separates it from siblings like no2_level_near, pm10_level_near and air_quality_index_near without needing to open 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?

Gives a clear use context ('suits asthma and COPD sufferers, runners and parents') and an explicit exclusion ('Not a forecast'), which routes agents toward forecast tools when prediction is wanted. It stops short of naming the sibling alternatives (e.g. pm10_level_near, air_quality_index_near) or when a different pollutant would be the better call, so it is clear context rather than full routing.

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