@cyanheads/epa-mcp-server 0.3.3 → 0.4.0

package/AGENTS.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** epa-mcp-server
-**Version:** 0.3.3
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
+**Version:** 0.4.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
 **Zod:** ^4.6.5

package/CLAUDE.md

@@ -1,8 +1,8 @@
 # Developer Protocol
 
 **Server:** epa-mcp-server
-**Version:** 0.3.3
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.13`
+**Version:** 0.4.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.14`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.2.0
 **Zod:** ^4.6.5

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.3.3-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/epa-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.2.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/epa-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/epa-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.4.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/epa-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.2.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/epa-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/epa-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -19,11 +19,17 @@
 
 </div>
 
+<div align="center">
+
+**Public Hosted Server:** [https://epa.caseyjhand.com/mcp](https://epa.caseyjhand.com/mcp)
+
+</div>
+
 ---
 
 ## Overview
 
-EPA environmental data across five federal programs — facility compliance (ECHO), toxic chemical releases (TRI), Superfund cleanup sites, drinking water systems (SDWIS), and environmental-justice screening (EJScreen) — plus real-time air quality via AirNow. Search facilities by location or compliance status, pull inspection and enforcement history, track toxic releases across a region, and screen a point for environmental-justice risk from any MCP client. Runs as a stdio process or a local Streamable HTTP server.
+EPA environmental data across five federal programs — facility compliance (ECHO), toxic chemical releases (TRI), Superfund cleanup sites, drinking water systems (SDWIS), and environmental-justice screening (EJScreen) — plus real-time air quality via AirNow. Search facilities by location or compliance status, pull inspection and enforcement history, track toxic releases across a region, and screen a point for environmental-justice risk from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
 ### Tools
 
@@ -32,7 +38,7 @@ EPA environmental data across five federal programs — facility compliance (ECH
 | `epa_search_facilities` | Search EPA-regulated facilities by location, industry program, or compliance status across CAA, CWA, RCRA, TRI, and SDWA |
 | `epa_get_facility` | Full compliance profile for one facility by EPA Registry ID — inspections, enforcement actions, and penalties |
 | `epa_search_violations` | Search EPA civil and criminal enforcement cases by state, program, or date range |
-| `epa_get_air_quality` | Current AQI observations or next-day forecasts from AirNow |
+| `epa_get_air_quality` | Current AQI observations or the issued AQI forecast from AirNow |
 | `epa_get_tri_releases` | Per-chemical Toxic Release Inventory data for a single facility |
 | `epa_search_tri_releases` | Toxic Release Inventory records across facilities in a state or county |
 | `epa_search_superfund` | Search Superfund (CERCLA/SEMS) sites by location or NPL listing status |
@@ -76,8 +82,10 @@ All resource data is also reachable via tools — use `epa_get_facility` and `ep
 
 ### `epa_get_air_quality` <sub>tool</sub>
 
-- Provide `zip_code` or both `latitude` and `longitude`; `mode` is current (default) or forecast (requires ISO `forecast_date`); `distance_miles` defaults to 25, max 300
-- Returns per-pollutant AQI, `categoryNumber` (1 Good–6 Hazardous), and `categoryName`; preliminary data is unsuitable for regulatory, trend, or enforcement decisions
+- Provide `zip_code` or both `latitude` and `longitude`; `mode` is current (default) or forecast
+- Current mode returns each pollutant's latest hourly NowCast AQI from the closest monitor within 50 miles, with `siteName`, `siteID`, and `reportingAgency`
+- Forecast mode returns every day the reporting area's agency issued, with `dateValid`, `actionDay`, and the agency's `discussion`; optional `forecast_date` (YYYY-MM-DD) keeps one day and is rejected in current mode. Category-only forecasts carry no `aqi`
+- Readings carry `categoryName` and `categoryNumber` (1 Good–6 Hazardous); `attribution` credits the agencies and the U.S. EPA AirNow program and marks the data preliminary, unsuitable for regulatory, trend, or enforcement decisions
 - Registered only when `AIRNOW_API_KEY` is set; responses cache for about one hour
 
 ---
@@ -86,13 +94,17 @@ All resource data is also reachable via tools — use `epa_get_facility` and `ep
 
 - `facility_id` is the TRI `facilityId` from `epa_search_tri_releases`; optional `year` (1987–2030, all available by default) and partial `chemical_name`
 - Returns per-chemical air, water, land, and underground-injection releases, plus a separate one-time/non-routine total
+- Quantities are in pounds. TRI has facilities report dioxin and dioxin-like compounds in grams; those records are converted to pounds and carry `reportedUnit: "grams"`
 
 ---
 
 ### `epa_search_tri_releases` <sub>tool</sub>
 
-- Requires 2-letter `state`; optional partial `county`, `chemical_name`, and `year`; up to 200 records (default 50)
+- Requires 2-letter `state`; optional `county` (bare name, case-insensitive partial match, so `Lake` also matches LAKE OF THE WOODS — each record's `countyName` says which; a trailing County, Parish, or Borough is dropped), partial `chemical_name`, and `year`; up to 200 records (default 50)
+- One upstream request however sparse the filters or large the state — EPA joins facilities to their reporting forms server-side
+- Returns each record's one-time/non-routine total; `include_release_breakdown: true` adds air, water, land, and underground-injection releases at the cost of one more upstream request (up to ~20 seconds when EPA has not cached it)
 - Returns `facilityId` for `epa_get_tri_releases`; enrichment marks results truncated when the limit is reached
+- Dioxin and dioxin-like compounds, reported to TRI in grams, are converted to pounds and carry `reportedUnit: "grams"`
 
 ---
 
@@ -105,8 +117,9 @@ All resource data is also reachable via tools — use `epa_get_facility` and `ep
 
 ### `epa_search_water_systems` <sub>tool</sub>
 
-- Requires `state` or `zip_code`; up to 200 systems (default 50)
-- `has_violation` filters active violations; `pws_type` is community, non-transient, or transient, returned as CWS / NTNCWS / TNCWS in `type`
+- Requires `state` or `zip_code`; up to 200 systems (default 50). `zip_code` matches each system's address of record (often the owner's or operator's office), not its service area
+- `has_violation` keeps systems with an open SDWIS violation; violations returned to compliance or closed out when the system was deactivated don't count. `pws_type` is community, non-transient, or transient, returned as CWS / NTNCWS / TNCWS in `type`
+- With `state` alone, `has_violation` reads the state's first 1,000 open violation records; with `zip_code`, it reads up to 1,000 systems in the ZIP and checks them by PWSID. When either read fills, an enrichment `notice` says the list may miss violating systems
 
 ---
 
@@ -149,6 +162,23 @@ Agent-friendly output:
 
 ## Getting started
 
+### Public Hosted Instance
+
+A public instance is available at `https://epa.caseyjhand.com/mcp` — no installation required. It runs without an AirNow key, so `epa_get_air_quality` is not available there; the other 8 tools are. Point any MCP client at it via Streamable HTTP:
+
+```json
+{
+  "mcpServers": {
+    "epa-mcp-server": {
+      "type": "streamable-http",
+      "url": "https://epa.caseyjhand.com/mcp"
+    }
+  }
+}
+```
+
+### Self-Hosted / Local
+
 Add the following to your MCP client configuration file. An AirNow API key is optional — set `AIRNOW_API_KEY` to enable `epa_get_air_quality` (register free at [docs.airnowapi.org](https://docs.airnowapi.org/account/request/)); without it the server starts with the other 8 tools. ECHO, DMAP, and EJScreen tools work without authentication.
 
 ```json

package/changelog/0.4.x/0.4.0.md

@@ -0,0 +1,35 @@
+---
+summary: "epa_get_air_quality moves to AirNow's 2026 web services (breaking: distance_miles removed, observation coordinates removed, aqi optional); TRI search runs as one DMAP join with a working county filter and opt-in release breakdown; water-system has_violation counts open violations; hosted endpoint at epa.caseyjhand.com."
+breaking: true
+security: false
+agent-notes: |
+  Callers of epa_get_air_quality: drop `distance_miles`, stop reading `latitude`/`longitude`, treat `hourObserved` as a string and `aqi` as optional.
+---
+
+# 0.4.0 — 2026-10-08
+
+## Added
+
+- **`epa_get_air_quality`** reads `observation/current/ziplatlong/` and `forecast/current/`, returns per-site readings (`siteName`, `siteID`, `reportingAgency`), the agency `discussion`, and an `attribution` credits block ([#30](https://github.com/cyanheads/epa-mcp-server/issues/30)).
+- **`epa_search_tri_releases`** takes opt-in `include_release_breakdown` for air, water, land, and underground-injection releases at the cost of one more upstream request ([#17](https://github.com/cyanheads/epa-mcp-server/issues/17)).
+- **`epa_search_tri_releases`** records carry `countyName`; TRI quantities reported in grams (dioxin and dioxin-like compounds) are converted to pounds and carry `reportedUnit`.
+- **Hosted endpoint** `https://epa.caseyjhand.com/mcp` is listed in `server.json` remotes and the README.
+
+## Changed
+
+- **`epa_get_air_quality` (breaking)** removes the `distance_miles` input and the `latitude`/`longitude` output fields, retypes `hourObserved`, and makes `aqi` optional (category-only forecasts omit it). `forecast_date` is optional, filters the issued forecast, and is rejected in current mode.
+- **`epa_search_tri_releases`** is one DMAP join instead of an unbounded facility walk ([#32](https://github.com/cyanheads/epa-mcp-server/issues/32)); the `county` filter matches `county_name` after dropping a trailing County, Parish, or Borough ([#27](https://github.com/cyanheads/epa-mcp-server/issues/27)).
+- **`epa_search_water_systems`** `has_violation` keeps systems with an open violation, in chunked lookups with a scan notice, and works with `zip_code`; `zip_code` is documented as the address of record.
+- **`epa_get_facility`**, **`epa_search_facilities`**, **`epa_search_superfund`** render latitude and longitude independently ([#24](https://github.com/cyanheads/epa-mcp-server/issues/24)) and pound quantities at full precision.
+- **`facility_id`** guidance on `epa_get_tri_releases` points at `epa_search_tri_releases` ([#21](https://github.com/cyanheads/epa-mcp-server/issues/21)).
+- **Tests** assert exact tool sets, error messages, and per-field output across the suite.
+
+## Fixed
+
+- **DMAP row ranges** are 1-based and inclusive.
+- **`epa_search_tri_releases`** under-limit searches no longer fail during enrichment.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` ^0.13.13 → ^0.13.14 (framework skills synced).
+- `pino-pretty` ^13.1.3 → ^13.2.0.

package/dist/mcp-server/tools/definitions/get-air-quality.tool.d.ts

@@ -1,5 +1,6 @@
 /**
- * @fileoverview Tool for getting AQI observations or forecasts for a location from AirNow.
+ * @fileoverview Tool for getting current AQI observations or the issued AQI forecast for a
+ * location from AirNow.
  * @module mcp-server/tools/definitions/get-air-quality.tool
  */
 import { z } from '@cyanheads/mcp-ts-core';
@@ -13,34 +14,47 @@ export declare const getAirQualityTool: import("@cyanheads/mcp-ts-core").ToolDef
         forecast: "forecast";
     }>>;
     forecast_date: z.ZodOptional<z.ZodString>;
-    distance_miles: z.ZodDefault<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     observations: z.ZodArray<z.ZodObject<{
         reportingArea: z.ZodOptional<z.ZodString>;
+        reportingAreaCode: z.ZodOptional<z.ZodString>;
         stateCode: z.ZodOptional<z.ZodString>;
-        latitude: z.ZodOptional<z.ZodNumber>;
-        longitude: z.ZodOptional<z.ZodNumber>;
         dateObserved: z.ZodOptional<z.ZodString>;
-        hourObserved: z.ZodOptional<z.ZodNumber>;
+        hourObserved: z.ZodOptional<z.ZodString>;
         localTimeZone: z.ZodOptional<z.ZodString>;
+        discussion: z.ZodOptional<z.ZodString>;
         readings: z.ZodArray<z.ZodObject<{
             parameterName: z.ZodString;
-            aqi: z.ZodNumber;
+            aqi: z.ZodOptional<z.ZodNumber>;
             categoryNumber: z.ZodOptional<z.ZodNumber>;
             categoryName: z.ZodOptional<z.ZodString>;
+            siteName: z.ZodOptional<z.ZodString>;
+            siteID: z.ZodOptional<z.ZodString>;
+            reportingAgency: z.ZodOptional<z.ZodString>;
+            dateIssue: z.ZodOptional<z.ZodString>;
+            dateValid: z.ZodOptional<z.ZodString>;
+            forecastAgency: z.ZodOptional<z.ZodString>;
+            actionDay: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     mode: z.ZodString;
     message: z.ZodOptional<z.ZodString>;
+    attribution: z.ZodString;
 }, z.core.$strip>, readonly [{
     readonly reason: "no_location";
     readonly code: JsonRpcErrorCode.ValidationError;
     readonly when: "Neither zip_code nor latitude+longitude was provided.";
     readonly recovery: "Provide either zip_code or both latitude and longitude to identify the location.";
 }, {
-    readonly reason: "forecast_date_required";
+    readonly reason: "forecast_date_needs_forecast_mode";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "Mode is \"forecast\" but forecast_date was not provided.";
-    readonly recovery: "Provide forecast_date as YYYY-MM-DD when using mode=\"forecast\".";
+    readonly when: "forecast_date was set while mode is \"current\", where it has no effect.";
+    readonly recovery: "Set mode to \"forecast\" to filter by forecast_date, or omit forecast_date.";
+}, {
+    readonly reason: "invalid_zip_code";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly when: "AirNow rejected zip_code as invalid (HTTP 400).";
+    readonly recovery: "Check that zip_code is a valid 5-digit US ZIP code, or pass latitude and longitude instead.";
+    readonly thrownBy: "service";
 }], undefined>;
 //# sourceMappingURL=get-air-quality.tool.d.ts.map

package/dist/mcp-server/tools/definitions/get-air-quality.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"get-air-quality.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-air-quality.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmO5B,CAAC"}
+{"version":3,"file":"get-air-quality.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/get-air-quality.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AA+BjE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA0R5B,CAAC"}

package/dist/mcp-server/tools/definitions/get-air-quality.tool.js

@@ -1,16 +1,35 @@
 /**
- * @fileoverview Tool for getting AQI observations or forecasts for a location from AirNow.
+ * @fileoverview Tool for getting current AQI observations or the issued AQI forecast for a
+ * location from AirNow.
  * @module mcp-server/tools/definitions/get-air-quality.tool
  */
 import { tool, z } from '@cyanheads/mcp-ts-core';
 import { JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
 import { getAirNowService } from '../../../services/airnow/airnow-service.js';
+const AIRNOW_PROGRAM = 'the U.S. EPA AirNow program (www.airnow.gov)';
+const PRELIMINARY_NOTICE = 'AirNow data are preliminary and unverified; do not use them for regulatory, trend, or enforcement decisions.';
+/** Credit line naming the agencies behind the returned readings and the AirNow program. */
+function attributionFor(mode, areas) {
+    const agencies = [
+        ...new Set(areas.flatMap((area) => area.readings.flatMap((r) => {
+            const agency = r.reportingAgency ?? r.forecastAgency;
+            return agency ? [agency] : [];
+        }))),
+    ];
+    const list = (items) => new Intl.ListFormat('en', { type: 'conjunction' }).format(items);
+    const credit = mode === 'current'
+        ? `Data courtesy of ${list([...agencies, AIRNOW_PROGRAM])}.`
+        : agencies.length > 0
+            ? `Forecasts issued by ${list(agencies)} and distributed by ${AIRNOW_PROGRAM}.`
+            : `Forecasts distributed by ${AIRNOW_PROGRAM}.`;
+    return `${credit} ${PRELIMINARY_NOTICE}`;
+}
 export const getAirQualityTool = tool('epa_get_air_quality', {
     title: 'Get Air Quality Index',
-    description: 'Get current AQI observations or forecasts for a location from the AirNow API. Returns per-pollutant AQI values (PM2.5, ozone, CO, SO2, NO2), AQI category (Good through Hazardous), reporting area name, and observation timestamp. Provide either zip_code or both latitude and longitude. Set mode to "forecast" and provide forecast_date for next-day projections. Data is preliminary — suitable for awareness and informational use, not regulatory decisions. Responses are cached for ~1 hour.',
+    description: "Get current AQI observations or the issued AQI forecast for a US location from the AirNow API. Provide either zip_code or both latitude and longitude. Current mode returns the latest hourly NowCast AQI for each pollutant (PM2.5, ozone, PM10) from the closest monitor within 50 miles, with the monitor site name, site ID, and reporting agency; pollutants in one reporting area can come from different monitors. Forecast mode returns every day the reporting area's agency has issued (typically one to five), each with the AQI category, an action-day flag, and the issue date, plus the agency's forecast discussion when one exists; some agencies forecast a category without an AQI number. In forecast mode, set forecast_date to keep only the forecast valid on that date; current mode rejects it. Data are preliminary — suitable for awareness, not regulatory, trend, or enforcement decisions. Responses are cached for ~1 hour.",
     annotations: { readOnlyHint: true, openWorldHint: true, idempotentHint: true },
     input: z.object({
-        zip_code: z.string().optional().describe('5-digit ZIP code for the location'),
+        zip_code: z.string().optional().describe('5-digit US ZIP code for the location'),
         latitude: z
             .number()
             .optional()
@@ -22,18 +41,11 @@ export const getAirQualityTool = tool('epa_get_air_quality', {
         mode: z
             .enum(['current', 'forecast'])
             .default('current')
-            .describe('Data mode: "current" for latest AQI observations, "forecast" for next-day projections'),
+            .describe('Data mode: "current" for the latest hourly observations, "forecast" for every forecast day the reporting area has issued'),
         forecast_date: z
             .string()
             .optional()
-            .describe('Date for forecast in ISO 8601 format (YYYY-MM-DD). Required when mode is "forecast".'),
-        distance_miles: z
-            .number()
-            .int()
-            .min(0)
-            .max(300)
-            .default(25)
-            .describe('Search radius in miles for finding reporting stations. Default 25 miles.'),
+            .describe('Forecast mode only (rejected in current mode): keep just the forecast valid on this date (YYYY-MM-DD). Omit to get every issued forecast day. When no issued day matches, the result is empty and its message lists the issued dates.'),
     }),
     output: z.object({
         observations: z
@@ -42,48 +54,91 @@ export const getAirQualityTool = tool('epa_get_air_quality', {
             reportingArea: z
                 .string()
                 .optional()
-                .describe('Name of the AQI reporting area (e.g. "Seattle-Tacoma-Bellevue, WA")'),
-            stateCode: z.string().optional().describe('2-letter state code of the reporting area'),
-            latitude: z.number().optional().describe('Latitude of the reporting area centroid'),
-            longitude: z.number().optional().describe('Longitude of the reporting area centroid'),
+                .describe('Name of the AQI reporting area (e.g. "Seattle-Bellevue-Kent Valley")'),
+            reportingAreaCode: z
+                .string()
+                .optional()
+                .describe('AirNow reporting area code (e.g. "wa004"). Forecast mode only.'),
+            stateCode: z
+                .string()
+                .optional()
+                .describe('2-letter state code of the reporting area. Forecast mode only.'),
             dateObserved: z
                 .string()
                 .optional()
-                .describe('Observation or forecast date (YYYY-MM-DD)'),
+                .describe('Observation date (YYYY-MM-DD). Current mode only.'),
             hourObserved: z
-                .number()
+                .string()
                 .optional()
-                .describe('Hour of observation (0–23) in local time. Absent for daily forecasts.'),
+                .describe('Local hour of the observation as "HH:00". Current mode only.'),
             localTimeZone: z
                 .string()
                 .optional()
-                .describe('Local time zone abbreviation (e.g. "PST")'),
+                .describe('Local time zone abbreviation for hourObserved (e.g. "PDT"). Current mode only.'),
+            discussion: z
+                .string()
+                .optional()
+                .describe("The forecasting agency's discussion for this area, verbatim (may contain HTML). Forecast mode only; omitted when the agency issued none."),
             readings: z
                 .array(z
                 .object({
                 parameterName: z
                     .string()
-                    .describe('Pollutant name (e.g. "PM2.5", "Ozone", "CO")'),
-                aqi: z.number().describe('Air Quality Index value for this pollutant'),
+                    .describe('Pollutant name as AirNow reports it (e.g. "PM2.5", "OZONE", "PM10")'),
+                aqi: z
+                    .number()
+                    .optional()
+                    .describe('Air Quality Index value. Omitted when the agency issued only a category (category-only forecast).'),
                 categoryNumber: z
                     .number()
                     .optional()
-                    .describe('AQI category number: 1=Good, 2=Moderate, 3=Unhealthy for Sensitive Groups, 4=Unhealthy, 5=Very Unhealthy, 6=Hazardous'),
+                    .describe('AQI category number: 1=Good, 2=Moderate, 3=Unhealthy for Sensitive Groups, 4=Unhealthy, 5=Very Unhealthy, 6=Hazardous. Omitted when AirNow reports an unrecognized category.'),
                 categoryName: z
                     .string()
                     .optional()
                     .describe('AQI category name (e.g. "Good", "Moderate", "Unhealthy")'),
+                siteName: z
+                    .string()
+                    .optional()
+                    .describe('Monitor site that produced this observation. Current mode only.'),
+                siteID: z
+                    .string()
+                    .optional()
+                    .describe('AirNow ID of the monitor site. Current mode only.'),
+                reportingAgency: z
+                    .string()
+                    .optional()
+                    .describe('Agency that reported this observation. Current mode only.'),
+                dateIssue: z
+                    .string()
+                    .optional()
+                    .describe('Date the forecast was issued (YYYY-MM-DD). Forecast mode only.'),
+                dateValid: z
+                    .string()
+                    .optional()
+                    .describe('Date the forecast applies to (YYYY-MM-DD). Forecast mode only.'),
+                forecastAgency: z
+                    .string()
+                    .optional()
+                    .describe('Agency that issued the forecast. Forecast mode only.'),
+                actionDay: z
+                    .boolean()
+                    .optional()
+                    .describe('True when the agency declared an air quality action day for this date. Forecast mode only.'),
             })
-                .describe('AQI reading for a single pollutant parameter'))
-                .describe('Per-pollutant AQI readings for this reporting area and time'),
+                .describe('AQI reading for one pollutant (and, in forecast mode, one valid date)'))
+                .describe('Per-pollutant AQI readings for this reporting area'),
         })
-            .describe('AQI observation or forecast record for a single reporting area'))
+            .describe('AQI readings for one reporting area — per observed hour in current mode, per area across all forecast days in forecast mode'))
             .describe('AQI observation or forecast records grouped by reporting area'),
         mode: z.string().describe('Data mode used: "current" or "forecast"'),
         message: z
             .string()
             .optional()
-            .describe('Recovery hint when no observations are returned — suggests trying a different location or increasing distance_miles. Absent when data is returned.'),
+            .describe("Why the result is empty: AirNow's own explanation, the issued forecast dates when forecast_date matched none, or a coverage hint. Absent when data is returned."),
+        attribution: z
+            .string()
+            .describe('Credit to the reporting or forecasting agencies and the U.S. EPA AirNow program, with the preliminary-data notice. Reproduce it when passing this data on.'),
     }),
     errors: [
         {
@@ -93,98 +148,115 @@ export const getAirQualityTool = tool('epa_get_air_quality', {
             recovery: 'Provide either zip_code or both latitude and longitude to identify the location.',
         },
         {
-            reason: 'forecast_date_required',
+            reason: 'forecast_date_needs_forecast_mode',
+            code: JsonRpcErrorCode.ValidationError,
+            when: 'forecast_date was set while mode is "current", where it has no effect.',
+            recovery: 'Set mode to "forecast" to filter by forecast_date, or omit forecast_date.',
+        },
+        {
+            reason: 'invalid_zip_code',
             code: JsonRpcErrorCode.ValidationError,
-            when: 'Mode is "forecast" but forecast_date was not provided.',
-            recovery: 'Provide forecast_date as YYYY-MM-DD when using mode="forecast".',
+            when: 'AirNow rejected zip_code as invalid (HTTP 400).',
+            recovery: 'Check that zip_code is a valid 5-digit US ZIP code, or pass latitude and longitude instead.',
+            thrownBy: 'service',
         },
     ],
     async handler(input, ctx) {
-        // Resolve the location once into a discriminated shape so the service branches below
-        // narrow without non-null assertions. Zip takes precedence over lat/lng, and the raw
-        // (untrimmed) zip_code is forwarded to match prior behavior.
-        const zip = input.zip_code;
-        const loc = zip !== undefined && zip.trim() !== ''
+        // Zip takes precedence over lat/lng; a blank zip (form clients) falls through to lat/lng.
+        const zip = input.zip_code?.trim();
+        const location = zip
             ? { kind: 'zip', zipCode: zip }
             : input.latitude !== undefined && input.longitude !== undefined
                 ? { kind: 'latlng', latitude: input.latitude, longitude: input.longitude }
                 : undefined;
-        if (!loc) {
+        if (!location) {
             throw ctx.fail('no_location', 'Provide either zip_code or both latitude and longitude.');
         }
-        // forecast mode requires a date — validate up front so the error path is unchanged.
-        let forecastDate = '';
-        if (input.mode === 'forecast') {
-            if (input.forecast_date === undefined || input.forecast_date.trim() === '') {
-                throw ctx.fail('forecast_date_required', 'forecast_date (YYYY-MM-DD) is required when mode is "forecast".');
-            }
-            forecastDate = input.forecast_date;
+        const forecastDate = input.forecast_date?.trim() || undefined;
+        if (forecastDate && input.mode === 'current') {
+            throw ctx.fail('forecast_date_needs_forecast_mode', `forecast_date "${forecastDate}" only filters forecasts; current mode returns the latest observations.`);
         }
         ctx.log.info('epa_get_air_quality', {
             mode: input.mode,
-            zip: input.zip_code,
-            lat: input.latitude,
+            location: location.kind,
+            forecastDate,
         });
         const service = getAirNowService();
-        let observations;
-        if (input.mode === 'current') {
-            observations =
-                loc.kind === 'zip'
-                    ? await service.getCurrentByZip({ zipCode: loc.zipCode, distanceMiles: input.distance_miles }, ctx)
-                    : await service.getCurrentByLatLng({
-                        latitude: loc.latitude,
-                        longitude: loc.longitude,
-                        distanceMiles: input.distance_miles,
-                    }, ctx);
+        const lookup = input.mode === 'forecast'
+            ? await service.getForecast(location, ctx)
+            : await service.getCurrent(location, ctx);
+        const observations = input.mode === 'forecast' && forecastDate
+            ? lookup.areas.flatMap((area) => {
+                const readings = area.readings.filter((r) => r.dateValid === forecastDate);
+                return readings.length > 0 ? [{ ...area, readings }] : [];
+            })
+            : lookup.areas;
+        ctx.log.info('epa_get_air_quality completed', { areas: observations.length });
+        const attribution = attributionFor(input.mode, observations);
+        if (observations.length > 0)
+            return { observations, mode: input.mode, attribution };
+        const where = location.kind === 'zip'
+            ? `zip_code="${location.zipCode}"`
+            : `latitude=${location.latitude}, longitude=${location.longitude}`;
+        let message;
+        if (lookup.noDataMessage !== undefined) {
+            message = `AirNow returned no data for ${where}: "${lookup.noDataMessage}"`;
         }
-        else {
-            observations =
-                loc.kind === 'zip'
-                    ? await service.getForecastByZip({ zipCode: loc.zipCode, date: forecastDate, distanceMiles: input.distance_miles }, ctx)
-                    : await service.getForecastByLatLng({
-                        latitude: loc.latitude,
-                        longitude: loc.longitude,
-                        date: forecastDate,
-                        distanceMiles: input.distance_miles,
-                    }, ctx);
+        else if (lookup.areas.length > 0) {
+            const issued = [
+                ...new Set(lookup.areas.flatMap((a) => a.readings.flatMap((r) => r.dateValid ?? []))),
+            ].sort();
+            message = `No forecast valid on ${forecastDate} for ${where}. ${issued.length > 0 ? `Issued forecast dates: ${issued.join(', ')}.` : 'AirNow listed no valid dates.'} Omit forecast_date to get every issued day.`;
         }
-        ctx.log.info('epa_get_air_quality completed', { areas: observations.length });
-        if (observations.length === 0) {
-            const location = loc.kind === 'zip'
-                ? `zip_code="${input.zip_code}"`
-                : `lat=${input.latitude}, lng=${input.longitude}`;
-            return {
-                observations: [],
-                mode: input.mode,
-                message: `No AQI data found for ${location} within ${input.distance_miles} miles. Try increasing distance_miles or check that the location is within the US.`,
-            };
+        else {
+            message = `No AQI data found for ${where}. AirNow observations come from monitors within 50 miles and forecasts from the location's reporting area; check that the location is in the US, or try a nearby ZIP code.`;
         }
-        return { observations, mode: input.mode };
+        return { observations: [], mode: input.mode, message, attribution };
     },
     format: (result) => {
-        const lines = [];
-        lines.push(`## Air Quality Index — ${result.mode === 'forecast' ? 'Forecast' : 'Current Observations'} (mode: ${result.mode})`);
+        const lines = [
+            `## Air Quality Index — ${result.mode === 'forecast' ? 'Forecast' : 'Current Observations'} (mode: ${result.mode})`,
+        ];
         if (result.message)
             lines.push(`\n> ${result.message}`);
-        for (const obs of result.observations) {
-            lines.push(`\n### ${obs.reportingArea ?? 'Unknown Area'}`);
-            if (obs.stateCode)
-                lines.push(`**State:** ${obs.stateCode}`);
-            if (obs.dateObserved) {
-                const timeStr = obs.hourObserved !== undefined
-                    ? ` at ${obs.hourObserved}:00 ${obs.localTimeZone ?? ''}`
+        for (const area of result.observations) {
+            lines.push(`\n### ${area.reportingArea ?? 'Unknown Area'}`);
+            const meta = [
+                area.stateCode && `**State:** ${area.stateCode}`,
+                area.reportingAreaCode && `**Reporting area code:** ${area.reportingAreaCode}`,
+            ].filter(Boolean);
+            if (meta.length > 0)
+                lines.push(meta.join(' | '));
+            if (area.dateObserved || area.hourObserved) {
+                const time = area.hourObserved
+                    ? ` at ${area.hourObserved}${area.localTimeZone ? ` ${area.localTimeZone}` : ''}`
                     : '';
-                lines.push(`**Date:** ${obs.dateObserved}${timeStr}`);
+                lines.push(`**Observed:** ${area.dateObserved ?? 'date not reported'}${time}`);
             }
-            if (obs.latitude !== undefined && obs.longitude !== undefined) {
-                lines.push(`**Coordinates:** ${obs.latitude}, ${obs.longitude}`);
-            }
-            for (const reading of obs.readings) {
-                const category = reading.categoryName ? ` (${reading.categoryName})` : '';
-                const catNum = reading.categoryNumber !== undefined ? ` [category ${reading.categoryNumber}]` : '';
-                lines.push(`**${reading.parameterName}:** AQI ${reading.aqi}${category}${catNum}`);
+            for (const r of area.readings) {
+                const label = r.dateValid ? `${r.dateValid} ${r.parameterName}` : r.parameterName;
+                const value = r.aqi !== undefined
+                    ? `AQI ${r.aqi}${r.categoryName ? ` (${r.categoryName})` : ''}`
+                    : (r.categoryName ?? 'Category not reported');
+                const category = r.categoryNumber !== undefined ? ` [category ${r.categoryNumber}]` : '';
+                const categoryOnly = r.aqi === undefined ? ' (category only, no AQI number)' : '';
+                const site = r.siteName || r.siteID
+                    ? ` — ${[r.siteName, r.siteID && `site ${r.siteID}`].filter(Boolean).join(', ')}`
+                    : '';
+                const details = [
+                    r.reportingAgency,
+                    (r.dateIssue || r.forecastAgency) &&
+                        ['issued', r.dateIssue, r.forecastAgency && `by ${r.forecastAgency}`]
+                            .filter(Boolean)
+                            .join(' '),
+                    r.actionDay !== undefined && `action day: ${r.actionDay ? 'yes' : 'no'}`,
+                ].filter(Boolean);
+                lines.push(`- **${label}:** ${value}${category}${categoryOnly}${site}${details.length > 0 ? ` · ${details.join(' · ')}` : ''}`);
             }
+            if (area.discussion)
+                lines.push(`\n**Discussion:**\n${area.discussion}`);
         }
+        lines.push(`\n**Source:** ${result.attribution}`);
         return [{ type: 'text', text: lines.join('\n') }];
     },
 });