Skip to main content
Glama

openaq-mcp-server

by io.github.cyanheads

openaq-mcp-server: find locations

openaq_find_locations
Read-onlyIdempotent

Find air-quality monitoring stations (measured by physical sensors, not modeled) near a point, within a bounding box, or by country. Returns each station's id, name, coordinates, distance from the query point (when searching by coordinates), country, provider, the parameters its sensors measure, and the timestamp of its most recent data (datetimeLast). Required first step: openaq_get_readings and openaq_get_measurements key on the location id this returns. Coverage is uneven and real — a station only reports the parameters it measures, and the absence of a nearby station means no monitoring there, not clean air. For dense modeled coverage anywhere on Earth, use open-meteo-mcp-server's air-quality tool instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
isoNoRestrict to a country by ISO 3166-1 alpha-2 code (e.g. "US", "IN", "DE"). Combine with bbox/coordinates to scope, or use alone for a country-wide list. Discover coverage with openaq_list_countries.
bboxNoBounding box as "minLon,minLat,maxLon,maxLat" (west,south,east,north). Alternative to coordinates+radius for area sweeps. Results have no distance field (no center point).
pageNoWhich page of results to return (1-based). Default 1. The only way past the 100-station cap: with limit 100, page 2 returns stations 101–200. Distance ordering applies within a page, not across pages, so paging is for iso/bbox sweeps — a near-me coordinates search should stay on page 1.
limitNoMax stations to return (1–100). Default 20. Results are ordered by distance when searching by coordinates.
radiusNoSearch radius in metres around coordinates (1–25000; the API hard-caps at 25000). Default 12000 (~12km). Only used with coordinates.
coordinatesNoCenter point as "latitude,longitude" (e.g. "47.6062,-122.3321"). Pair with radius for a near-me search. Resolve a place name to coordinates with openstreetmap-mcp-server or open-meteo geocode first. Provide either coordinates+radius OR bbox, not both.
parametersIdNoOnly return stations that measure this parameter id (e.g. 2 = PM2.5 µg/m³). Get ids from openaq_list_parameters — the same pollutant has several ids for different units. Narrows the station set; each returned station still lists all its sensors.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe limit that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of stations returned.
noticeNoGuidance when OpenAQ reports a lower-bound total without the result set hitting the limit.
locationsNoMatching stations. Empty array means no monitoring coverage for the query — NOT clean air. Widen the radius, try openaq_list_countries, or use the modeled open-meteo air-quality tool.
truncatedNoTrue when the station list was capped at the limit.
totalCountNoTotal matching stations before the limit. A floor (not an exact count) when totalCountIsLowerBound is true.
totalCountIsLowerBoundNoTrue when OpenAQ reported a lower bound (">N"): totalCount is a floor and more stations match than the count shown.

TDQS

A4.5/5.0
Behavior4/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 valuable context beyond that: coverage is uneven and real, absence of stations means no monitoring, not clean air, and distance is only returned for coordinate searches. This enriches the agent's mental model of result interpretation, though it does not disclose pagination quirks (which live in the schema).

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?

The description is concise but information-dense, with three clear sentences: purpose and selection criteria, return fields, then usage and caveats. It is front-loaded with the central action, and every sentence earns its place by adding distinct value (purpose, returns, sequence, limitation, alternative). No filler or redundancy.

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?

Given the tool has 7 optional parameters, a rich output schema, and clear annotations, the description covers all the essential contextual pieces: what the tool returns (key fields), how it relates to sibling tools (first step), its data-source limitations, and the recommended alternative for modeled data. Nothing an agent needs to choose and invoke it correctly is missing.

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?

The input schema has 100% description coverage, with each parameter explained in detail (e.g., coordinates pattern, bbox format, radius bounds, page/limit behavior). The description adds only marginal parameter-level detail, such as implying bbox vs coordinates via 'within a bounding box' and noting distance only when searching by coordinates. Since the schema already carries the full burden, a baseline of 3 is appropriate.

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 states a specific verb ('Find') and a precise resource ('air-quality monitoring stations') with explicit selection criteria: near a point, within a bounding box, or by country. It also distinguishes itself from the modeled-data alternative by explicitly noting it uses physical sensors, and from sibling openaq tools by positioning itself as the required first step for readings/measurements. This leaves no ambiguity about what the tool does.

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

Usage Guidelines5/5

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

The description gives explicit when-to-use guidance: it is the first step for openaq_get_readings and openaq_get_measurements, and it names the open-meteo alternative for dense modeled coverage. It also implicitly excludes modeled data by stating it is physical sensors only. This clearly routes the agent to the correct tool for each scenario.

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