openaq-mcp-server

openaq-mcp-server: get readings

openaq_get_readings

Read-onlyIdempotent

Latest measured value for every sensor at a monitoring station — the current-conditions tool. Returns one record per parameter, each with the value, its unit, the UTC and local timestamp, and the sensor id, joined so every value carries its pollutant and unit (the raw latest feed is keyed only by sensor id). The station block names its provider (for attribution) and timezone. Pass a locationId from openaq_find_locations, or pass coordinates to auto-resolve to the nearest station that measures the requested parametersId. Data recency varies by station reporting cadence — read each value's timestamp to know whether "latest" is minutes or hours old. These are measured observations with coverage gaps, not a modeled grid.

Input Schema

TableJSON Schema

Name	Required	Description
`locationId`	No	Station id from openaq_find_locations. Provide this OR coordinates. When set, returns the latest value for every sensor at this station.
`coordinates`	No	Fallback "latitude,longitude" when you do not have a locationId — resolves to the nearest station (within 25km) that measures parametersId, then reads its latest values. Requires parametersId.
`parametersId`	No	Required with coordinates: which parameter id the nearest station must measure (get ids from openaq_list_parameters). With locationId, optionally filters the returned values to this parameter id; omit to get all sensors.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Set when coordinate resolution compared a full 1,000-station page: more stations may match, so the station returned is the nearest of the first 1,000 OpenAQ lists, not necessarily the nearest overall.
`location`	No	The station these readings came from
`readings`	No	Latest value per sensor. An old datetime means the station reports infrequently or is stale — not that the value is current.

Schema Changelog

Changes observed during successful MCP inspections.

Changed10 schema fields changedSep 24, 2026

removedOutput schema / properties / location / properties / coordinates / additionalProperties
```
Removed value: -false
```

addedOutput schema / properties / location / properties / coordinates / anyOf

Added value: +[
+  {
+    "additionalProperties": false,
+    "properties": {
+      "latitude": {
+        "description": "Station latitude (decimal degrees)",
+        "type": "number"
+      },
+      "longitude": {
+        "description": "Station longitude (decimal degrees)",
+        "type": "number"
+      }
+    },
+    "required": [
+      "latitude",
+      "longitude"
+    ],
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / properties / location / properties / coordinates / description

Previous value: -"Station coordinates"New value: +"Station coordinates. Null when OpenAQ lists no latitude or no longitude."

removedOutput schema / properties / location / properties / coordinates / properties

Removed value: -{
-  "latitude": {
-    "description": "Station latitude (decimal degrees)",
-    "type": "number"
-  },
-  "longitude": {
-    "description": "Station longitude (decimal degrees)",
-    "type": "number"
-  }
-}

removedOutput schema / properties / location / properties / coordinates / required
```
Removed value: -[
-  "latitude",
-  "longitude"
-]
```
removedOutput schema / properties / location / properties / coordinates / type
```
Removed value: -"object"
```

addedOutput schema / properties / location / properties / provider

Added value: +{
+  "description": "Network that operates the station (e.g. \"AirNow\") — cite it alongside OpenAQ. Null when OpenAQ lists none.",
+  "type": [
+    "string",
+    "null"
+  ]
+}

addedOutput schema / properties / location / properties / providerId

Added value: +{
+  "description": "Provider id, usable as providersId in openaq_find_locations. Null when OpenAQ lists none.",
+  "type": [
+    "number",
+    "null"
+  ]
+}

changedOutput schema / properties / location / required

Previous value: -[
-  "id",
-  "name",
-  "coordinates",
-  "timezone",
-  "distanceMeters",
-  "datetimeLast"
-]New value: +[
+  "id",
+  "name",
+  "coordinates",
+  "provider",
+  "providerId",
+  "timezone",
+  "distanceMeters",
+  "datetimeLast"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when the station resolved but returned no recent values."New value: +"Set when coordinate resolution compared a full 1,000-station page: more stations may match, so the station returned is the nearest of the first 1,000 OpenAQ lists, not necessarily the nearest overall."

Changed4 schema fields changedSep 24, 2026
- addedInput schema / properties / locationId / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / locationId / minimum
```
Removed value: --9007199254740991
```
- addedInput schema / properties / parametersId / exclusiveMinimum
```
Added value: +0
```
- removedInput schema / properties / parametersId / minimum
```
Removed value: --9007199254740991
```
Changed6 schema fields changedSep 20, 2026
- removedOutput schema / properties / location / properties / distanceMeters / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / location / properties / distanceMeters / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / location / properties / timezone / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / location / properties / timezone / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / readings / items / properties / parameter / properties / displayName / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / readings / items / properties / parameter / properties / displayName / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "location",
+      "readings"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `location_not_found`: The locationId does not exist (API returns {\"detail\":\"Location not found\"}). `parameter_not_at_location`: No sensor at the resolved station measures parametersId (often the wrong unit variant was chosen). `no_station_near_coordinates`: The 25km auto-resolution sweep found no station measuring the requested parametersId. `no_recent_values`: The station has the requested sensors but its latest feed carried no values for them. `invalid_location_scope`: Both locationId and coordinates were provided, or neither was. `missing_coordinates_parameter`: coordinates was provided without parametersId. `upstream_error`: OpenAQ returned 5xx or an unreadable body on every retry. `rate_limited`: OpenAQ returned 429 — the request budget for this key is exhausted. `upstream_timeout`: OpenAQ did not respond within the request timeout on every retry. `invalid_api_key`: OpenAQ returned 401 — the configured OPENAQ_API_KEY is missing, invalid, or revoked. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "location_not_found",
+            "parameter_not_at_location",
+            "no_station_near_coordinates",
+            "no_recent_values",
+            "invalid_location_scope",
+            "missing_coordinates_parameter",
+            "upstream_error",
+            "rate_limited",
+            "upstream_timeout",
+            "invalid_api_key"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "location",
-  "readings"
-]

First observedJun 16, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, lowering the bar. The description goes well beyond this by revealing that the raw feed is keyed only by sensor iderview, that timestamps must be read to assess data recency, and that the data are 'measured observations with coverage gaps, not a modeled grid.' These are non-obvious behavioral and data-quality traits that help an agent interpret results correctly.

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

Conciseness5/5

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

Five sentences, each earning its place: what it returns, the join behavior, the station block contents, the two invocation modes, and the recency/data-quality caveats. It is front-loaded with the main purpose and avoids any redundant restatement of the schema.

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

Completeness4/5

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

The description covers return shape, key fields, call patterns, and important data caveats, and an output schema exists. One gap: the schema marks zero parameters as required, and the description does not explicitly state 'provide exactly one of locationId or coordinates,' which could allow an agent to omit both and receive an error. This is a minor completeness issue given the strong surrounding context.

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

Parameters3/5

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

Schema description coverage is 100%, with detailed explanations for locationId, coordinates, and parametersId. The description tells the agent where to find a locationId (from find_locations) and that coordinates resolve to the nearest station, but it adds little beyond the schema. Baseline 3 fits when the schema already carries parameter semantics.

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

Purpose5/5

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

The description opens with a precise statement: 'Latest measured value for every sensor at a monitoring station' and labels itself 'the current-conditions tool.' This clearly differentiates it from siblings like openaq_get_measurements and openaq_find_locations, and it names the resource (readings) with an explicit verb (get).

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

Usage Guidelines4/5

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

It explains the two invocation patterns (locationId vs coordinates), references openaq_find_locations for obtaining a station id, and notes that coordinates need parametersId. The 'current-conditions' label implies a contrast with historical time-series tools, but it does not explicitly state 'do not use this for historical data, use openaq_get_measurements instead,' so the exclusion is not fully spelled out.

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

All openaq-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.