Skip to main content
Glama

openaq-mcp-server

by io.github.cyanheads

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). 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
NameRequiredDescriptionDefault
locationIdNoStation id from openaq_find_locations. Provide this OR coordinates. When set, returns the latest value for every sensor at this station.
coordinatesNoFallback "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.
parametersIdNoRequired 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
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
noticeNoGuidance when the station resolved but returned no recent values.
locationNoThe station these readings came from
readingsNoLatest value per sensor. An old datetime means the station reports infrequently or is stale — not that the value is current.

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds substantial behavioral context: the output structure (one record per parameter with value, unit, UTC/local timestamps, sensor id), the join that the raw feed lacks, the recency caveat tied to station cadence, and the warning that these are measured observations with gaps—not a modeled grid. This goes well beyond what annotations provide and sets accurate expectations.

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

Conciseness4/5

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

The description is dense but each sentence earns its place: it states the core purpose, details the returned record structure, gives both invocation routes, and flags the recency and data-coverage caveats. It is a bit longer than minimal but everything included is relevant. The structure front-loads the purpose and then expands logically. A slightly tighter wording could trim a few words, but no sentence is redundant.

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

Completeness5/5

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

For a tool with three optional parameters, two distinct call patterns, and an output schema already present, the description covers all the essential aspects an agent needs: how the result is shaped, how to select the target station, the dependency between parameters, and the reliability caveat about timestamps. The output schema covers the exact return fields, so the description does not need to repeat them. Nothing critical is missing.

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

Parameters4/5

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

The input schema already gives detailed descriptions for all three parameters (100% coverage). The description adds value by explaining the relationship and constraints: locationId OR coordinates, coordinates as a 'fallback' that auto-resolves within 25km, and parametersId being 'Required with coordinates' while optionally filtering when locationId is used. This conditional logic is not obvious from the schema alone and meaningfully helps an agent invoke the tool correctly.

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 starts with a precise verb and resource: 'Latest measured value for every sensor at a monitoring station'. It also brands itself as 'the current-conditions tool', which cleanly separates it from siblings like openaq_get_measurements (historical data). The scope (per-sensor, latest value) and the join detail (carries pollutant and unit) leave no ambiguity about what the tool returns.

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?

The description clearly explains the two entry modes (locationId or coordinates) and the condition that coordinates requires parametersId. It even names the source for locationId (openaq_find_locations). It stops short of explicitly stating 'use this for current conditions, use openaq_get_measurements for historical trends', but the 'current-conditions tool' label and the mention of recency implicitly frame the appropriate use case.

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 toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.4/5.0
Disambiguation5/5

Each tool serves a distinct purpose: catalog discovery (list_countries, list_parameters), station lookup (find_locations), current data (get_readings), historical data (get_measurements), and DataCanvas query support (dataframe_describe, dataframe_query). No two tools overlap in function.

Naming Consistency4/5

The prefix 'openaq_' is consistent, and most tools follow a verb_noun pattern (find_locations, get_measurements, list_countries). However, 'dataframe_describe' and 'dataframe_query' invert this to noun_verb, a minor deviation that could confuse agents.

Tool Count5/5

Seven tools covers the full workflow (discover, locate, read current/historical, and handle large data) without redundancy. This is a well-scoped surface for an air quality data server.

Completeness5/5

The set provides end-to-end capability: metadata discovery, location search, current conditions, historical time series, and a mechanism for large SQL queries. No critical gaps like missing update/delete operations exist because the server is read-only by design.

Resources