openaq-mcp-server
Server Details
Find air-quality stations and read pollutant observations from government monitors via OpenAQ v3.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Tool Definition Quality
Average 4.6/5 across 7 of 7 tools scored.
Each tool has a clearly distinct purpose: listing countries, listing parameters, finding locations, getting current readings, getting historical measurements, and managing DataCanvas tables for SQL queries. No two tools overlap in functionality.
All tools follow a consistent verb_noun pattern with the 'openaq_' prefix (e.g., list_countries, get_readings, dataframe_query). No mixing of conventions.
7 tools is well-scoped for an air quality data server, covering discovery, current conditions, historical data, and advanced SQL querying via DataCanvas. Not too few or too many.
The tool set covers the full data lifecycle for a read-only API: discovery (countries, parameters, locations), current readings, historical measurements, and custom SQL queries. Minor gaps like missing multi-parameter bulk retrieval are addressed by the DataCanvas tools.
Available Tools
7 toolsopenaq_dataframe_describeopenaq-mcp-server: dataframe describeARead-onlyInspect
List the tables and columns staged on a DataCanvas so you can write valid SQL for openaq_dataframe_query without guessing column names. Returns each measurement table (measurements_) with its row count and column names. Requires DataCanvas to be enabled.
| Name | Required | Description | Default |
|---|---|---|---|
| canvas_id | Yes | DataCanvas id returned by openaq_get_measurements when a series spilled. |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the canvas holds no tables yet. |
| tables | Yes | Tables currently staged on the canvas. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true. The description adds that the tool returns table-level details (row count, column names) and requires DataCanvas to be enabled, providing useful behavioral context beyond 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?
Two sentences, no filler. Purpose is front-loaded, and every sentence adds value.
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?
Given the tool is simple (1 param, no nested objects) and has an output schema, the description adequately explains return values (tables, columns, row count) and its role in the query workflow. Slightly incomplete regarding the structure of the return, but sufficient.
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?
The single parameter canvas_id is described in the schema as 'DataCanvas id returned by openaq_get_measurements when a series spilled.' The description adds no further parameter-level detail, but schema coverage is 100%, so baseline 3.
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 uses specific language: 'List the tables and columns' and explicitly connects to writing valid SQL for the sibling tool openaq_dataframe_query. It clearly distinguishes its purpose from other tools.
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 description states when to use (before querying) and a prerequisite ('Requires DataCanvas to be enabled'). It does not explicitly state when not to use, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_dataframe_queryopenaq-mcp-server: dataframe queryARead-onlyInspect
Run a read-only SQL SELECT against the measurement tables openaq_get_measurements staged on a DataCanvas. Reference tables by the name the measurements call returned (measurements_). For aggregation (monthly means, exceedance counts) and cross-sensor comparison over series too large to inline. Only SELECT is allowed — writes, DDL, and file/network table functions are rejected.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Read-only SELECT. Reference tables by the names openaq_get_measurements returned (e.g. measurements_1701). Use openaq_dataframe_describe first to see table and column names. | |
| canvas_id | Yes | DataCanvas id returned by openaq_get_measurements when a series spilled. |
Output Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Result rows (capped at the canvas row limit). |
| rowCount | Yes | Full result count before the row cap. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, and description adds constraints: only SELECT is allowed, writes/DDL/network functions rejected. No contradictions.
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 sentences, front-loaded with main action, then usage context and constraints. Every sentence adds value without repetition.
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?
Covers purpose, constraints, usage hints, and mentions prerequisite tool. Could mention potential performance considerations but overall complete given output schema existence.
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 the schema property descriptions already include the guidance about table references and using openaq_dataframe_describe. The description adds no new parameter-level meaning.
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 clearly states the tool runs read-only SQL SELECT against measurement tables, distinguishing it from siblings like openaq_dataframe_describe and openaq_get_measurements.
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?
Explicitly says when to use (aggregation, cross-sensor comparison over large series) and when not (writes, DDL, file/network functions). Also advises using openaq_dataframe_describe first for table/column names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_find_locationsopenaq-mcp-server: find locationsARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| iso | No | Restrict 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. | |
| bbox | No | Bounding 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). | |
| limit | No | Max stations to return (1–100). Default 20. Results are ordered by distance when searching by coordinates. | |
| radius | No | Search radius in metres around coordinates (1–25000; the API hard-caps at 25000). Default 12000 (~12km). Only used with coordinates. | |
| coordinates | No | Center 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. | |
| parametersId | No | Only 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
| Name | Required | Description |
|---|---|---|
| cap | No | The limit that was applied. |
| shown | No | Number of stations returned. |
| notice | No | Guidance when OpenAQ reports a lower-bound total without the result set hitting the limit. |
| locations | Yes | Matching 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. |
| truncated | No | True when the station list was capped at the limit. |
| totalCount | Yes | Total matching stations before the limit. A floor (not an exact count) when totalCountIsLowerBound is true. |
| totalCountIsLowerBound | No | True when OpenAQ reported a lower bound (">N"): totalCount is a floor and more stations match than the count shown. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that coverage is uneven and real, that stations only report measured parameters, and that results are ordered by distance when using coordinates. Adds valuable context beyond annotations (readOnlyHint, openWorldHint, idempotentHint), e.g., no distance field with bbox.
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?
Succinct yet comprehensive; front-loaded with purpose, every sentence adds new and useful information. No wasted words. Structure flows logically from purpose to usage to limitations.
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?
Given 6 parameters with complex constraints and 0 required, the description fully explains all parameter meanings, usage patterns, and behavioral quirks. Output schema exists, but description also lists returned fields. No gaps remain.
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?
All 6 parameters are covered in description with additional meaning: explains mutual exclusivity of coordinates+radius vs bbox, gives examples for coordinates, details radius constraints, and clarifies that parametersId narrows stations but still returns all sensors. Schema coverage is 100%, but description significantly enhances usability.
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?
Clearly states it finds air-quality monitoring stations by point, bbox, or country, specifying they are physical sensor-based (not modeled). Distinguishes from siblings (openaq_get_readings, openaq_get_measurements) and even suggests an alternative tool for modeled coverage.
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?
Explicitly states it's the required first step for get_readings and get_measurements, advises against using it for modeled coverage in favor of open-meteo-mcp-server's tool. Also explains coverage limitations and when not to infer clean air from absence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_get_measurementsopenaq-mcp-server: get measurementsARead-onlyIdempotentInspect
Historical measurement series for one pollutant at one station over a date range — for trend analysis and "was last week worse than the monthly average?". Pass a locationId and a parametersId and work in stations — you get the series for that pollutant at that station. Choose aggregation: raw (every reported value), hourly, or daily — daily and hourly add a per-bucket statistical summary (min, median, max, mean, sd). Large ranges produce thousands of rows and spill to a DataCanvas: the response returns a preview plus a canvasId and table name you query with openaq_dataframe_query. Values carry their unit; the server never converts between µg/m³, ppm, and ppb.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows per page from the API (1–1000). Default 1000. The tool pages internally up to the spill threshold. | |
| canvas_id | No | DataCanvas id from a prior call to reuse the same canvas (e.g. to compare two stations' series side by side). Omit to start fresh; the response returns a new canvas_id when the series spills. | |
| datetimeTo | No | End of the range, inclusive. Must be on or after datetimeFrom. Omit for "up to now". | |
| locationId | Yes | Station id from openaq_find_locations. | |
| aggregation | No | Time bucketing. "raw" = every reported value (often hourly at source). "hourly"/"daily" = server-side rollups with a statistical summary per bucket. Use "daily" for multi-month trends to keep the series small; "raw" for fine-grained recent analysis. | raw |
| datetimeFrom | No | Start of the range, inclusive. Date "YYYY-MM-DD" or full UTC "YYYY-MM-DDTHH:MM:SSZ". Omit to get the most recent values. | |
| parametersId | Yes | Parameter id to pull the series for (e.g. 2 = PM2.5 µg/m³). Get ids from openaq_list_parameters. Must be a parameter the station measures — find_locations lists each station's parameters. |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Degraded-mode hint when the series was truncated but DataCanvas is unavailable. |
| series | Yes | The (possibly previewed) series, newest or oldest first per the API. When truncated, this is a preview — query canvasId for the full set. |
| canvasId | No | DataCanvas id holding the full series. Query with openaq_dataframe_query. |
| location | Yes | Station the series came from |
| rowCount | Yes | Rows in this response (preview length when spilled) |
| sensorId | Yes | Resolved sensor id the series was pulled from |
| parameter | Yes | What was measured, resolved from the station's sensor |
| tableName | No | Canvas table name for the full series (e.g. "measurements_1701"). Reference it in SQL. |
| truncated | No | True when the series exceeded the inline limit and the full set was staged on canvasId. Absent/false when everything fit inline. |
| totalCount | Yes | Total rows in the full series. |
| aggregation | Yes | Bucketing applied |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, openWorldHint), the description discloses spillover behavior with DataCanvas, unit preservation (no conversion between µg/m³, ppm, ppb), and statistical summaries for aggregated data. No contradictions with 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?
The description is a single well-structured paragraph that front-loads the purpose, gives instructions, and covers behavioral notes without unnecessary words. Every sentence adds value.
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?
Given the complexity (7 parameters, output schema exists), the description covers spillover, aggregation summaries, unit handling, and usage examples. With output schema present, it does not need to detail return values, making this complete.
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 baseline is 3. The description adds meaningful usage guidance for aggregation (trend vs. fine-grained), clarifies omission behavior for datetimeFrom/To, and explains canvas_id reuse. This exceeds the baseline.
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 clearly states the tool returns historical measurement series for one pollutant at one station over a date range, with specific use cases like trend analysis. It distinguishes from siblings by mentioning DataCanvas spillover and subsequent query with openaq_dataframe_query.
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 description provides guidance on when to use different aggregations (daily for trends, raw for fine-grained) and prerequisites (use openaq_find_locations and openaq_list_parameters). However, it does not explicitly contrast with sibling tools like openaq_get_readings for when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_get_readingsopenaq-mcp-server: get readingsARead-onlyIdempotentInspect
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.
| Name | Required | Description | Default |
|---|---|---|---|
| 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
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the station resolved but returned no recent values. |
| location | Yes | The station these readings came from |
| readings | Yes | Latest value per sensor. An old datetime means the station reports infrequently or is stale — not that the value is current. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations (readOnlyHint, openWorldHint, idempotentHint). It explains that values are joined with pollutant and unit, notes data recency varies by station reporting cadence, and clarifies that observations are measured with coverage gaps rather than a modeled grid.
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 description is a single paragraph of five sentences, front-loaded with the core purpose. Every sentence adds value, and the structure is logical and easy to parse.
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?
Given the presence of an output schema (not shown but noted), the description appropriately focuses on input logic and data caveats. It covers the two access methods, the nature of the data, and recency warnings, making it fully actionable for an AI agent.
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?
Although the input schema already provides 100% coverage with descriptions, the tool description adds important connectivity: it explains how locationId relates to openaq_find_locations, how coordinates require parametersId, and how parametersId optionally filters. This enhances understanding beyond the schema alone.
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 clearly states the tool's purpose: 'Latest measured value for every sensor at a monitoring station — the current-conditions tool.' It specifies that it returns one record per parameter with value, unit, timestamps, and sensor id, and distinguishes itself from the raw latest feed and sibling tools like openaq_get_measurements.
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 description gives explicit guidance on when to use locationId vs coordinates, noting coordinates require parametersId and locationId can optionally filter. It explains the relationship with sibling tools (openaq_find_locations, openaq_list_parameters) but does not provide explicit exclusions or when-not-to-use scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_list_countriesopenaq-mcp-server: list countriesARead-onlyIdempotentInspect
Catalog of country-level coverage: id, ISO code, name, the date span of available station data (datetimeFirst/datetimeLast), and which parameters are measured anywhere in that country. The availability check before a regional sweep — answers "which countries have NO2 monitoring?" and tells you whether a country has recent data before you call openaq_find_locations. Coverage is uneven worldwide; this surfaces where measured data exists.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive filter over the bounded country catalog (~153) by code and name. A two-letter query is treated as an exact ISO 3166-1 alpha-2 code (e.g. "US" → United States); longer queries match as substrings (e.g. "united", "germany"). Omit to list all. |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the query matched nothing. |
| countries | Yes | Matching countries with coverage metadata. |
| totalCount | Yes | Total countries matched after filtering. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context about uneven coverage and that it surfaces where measured data exists. It clarifies that the tool provides date span and parameter information, which is beyond the annotations but consistent and helpful.
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 description is two sentences, front-loaded with the core purpose ('Catalog of country-level coverage'), and each sentence adds value: listing contents, usage guidance, and note about coverage. No wasted words.
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?
Given the tool's simplicity (1 optional parameter, output schema present, annotations present), the description is complete. It explains what the catalog contains, when to use it (before openaq_find_locations), and notes uneven coverage. No missing information for an agent to correctly select and invoke this tool.
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 a detailed description of the 'query' parameter. The description does not add new parameter semantics beyond what the schema provides, so a baseline of 3 is appropriate. The description adds usage context but not additional parameter details.
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 clearly states the tool is a 'Catalog of country-level coverage' listing id, ISO code, name, date span, and measured parameters. It differentiates from siblings by explicitly mentioning it should be used before openaq_find_locations for regional sweeps and to check parameter availability like NO2 monitoring.
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 description provides explicit guidance: 'The availability check before a regional sweep' and tells when to use it (before openaq_find_locations). It addresses common use cases like 'which countries have NO2 monitoring?' and implies not to use when you already have country-level info.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openaq_list_parametersopenaq-mcp-server: list parametersARead-onlyIdempotentInspect
Catalog of every measurable pollutant and its canonical unit: id, code, display name, unit, and a one-line description (pm25, pm10, o3, no2, so2, co, bc, and ~38 more). This is the unit-disambiguation reference — the same pollutant exists under several ids with different units (CO is id 4 in µg/m³, id 8 in ppm, id 102 in ppb), so use this to pick the exact parametersId for openaq_find_locations / openaq_get_readings / openaq_get_measurements and to interpret a reading's unit. A small bounded catalog fetched live from OpenAQ.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Case-insensitive filter over the bounded parameter catalog (~44) by code, display name, and description (e.g. "pm" for particulates, "ozone", "co"). Omit to list everything. | |
| pollutantsOnly | No | When true, exclude meteorological/auxiliary parameters (temperature, humidity, wind, pressure, particle-count channels) and return only air pollutants. Default false (full catalog). |
Output Schema
| Name | Required | Description |
|---|---|---|
| notice | No | Guidance when the query matched nothing. |
| parameters | Yes | Matching parameters. Multiple rows can share a name with different ids/units — pick the id whose unit you want. |
| totalCount | Yes | Total parameters matched after filtering. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and idempotentHint. The description adds that it is a small bounded catalog (~44 items) fetched live from OpenAQ, and explains the unit disambiguation issue. No contradiction with 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?
The description is a single dense paragraph that efficiently conveys purpose, output, and usage context. It is front-loaded with the core purpose. While it could be slightly more structured, it remains concise and informative.
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?
Given the tool's simplicity (2 optional parameters, 100% schema coverage, and an output schema), the description fully covers the catalog's content, purpose, and link to other tools. It mentions the size (~44) and the live fetch, making it complete.
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 descriptions. The tool description adds practical context: examples for query (e.g., 'pm', 'ozone'), clarifies it's case-insensitive, and explains that pollutantsOnly excludes meteorological parameters. This adds value 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?
The description clearly states it returns a catalog of pollutants with canonical units, listing specific fields (id, code, display name, unit, description). It distinguishes itself from sibling tools by noting it is a reference for disambiguation and selecting parametersId for other tools.
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 description explicitly instructs to use this tool to pick the exact parametersId for other tools (openaq_find_locations, openaq_get_readings, openaq_get_measurements) and to interpret units. While it doesn't state when not to use it, the purpose is clear and context-specific.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!