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. Throws canvas_unavailable when DuckDB is off.
| 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 already mark readOnlyHint=true, but the description adds behavioral context: it throws canvas_unavailable when DuckDB is off, which is not in annotations. This provides actionable information beyond the annotation.
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?
Three sentences, each essential: purpose/benefit, output description, and error condition. Front-loaded and 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?
With a single parameter and existing output schema, the description covers all needed context: what it does, what it returns, and a key error. Synthesizing schema and annotations into a useful whole.
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 already describes canvas_id as the DataCanvas id. The description does not add new parameter details, but the schema alone is sufficient, meeting 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 lists tables and columns on a DataCanvas, explicitly linking its purpose to enabling valid SQL for openaq_dataframe_query. It distinguishes from sibling tools like openaq_dataframe_query by focusing on schema discovery.
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 indicates when to use (before querying to get column names) and mentions the error condition. It lacks explicit when-not or alternatives, but the context is clear given the sibling tools.
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 — a four-layer gate rejects writes, DDL, and file/network table functions.
| 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?
The description adds significant behavioral context beyond the readOnlyHint annotation, detailing the 'four-layer gate rejects writes, DDL, and file/network table functions' and that it queries staged measurement tables.
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 succinct sentences: the first clearly states the tool's function, and the second provides usage context. No extraneous information.
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?
The description adequately covers purpose, usage, behavioral constraints, and parameter guidance. The presence of an output schema mitigates the need to explain return format.
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?
With 100% schema coverage, the description still adds value by explaining table naming convention (measurements_<sensorId>) and recommending openaq_dataframe_describe for previewing table and column names.
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 states a specific verb ('Run a read-only SQL SELECT') and resource ('measurement tables openaq_get_measurements staged on a DataCanvas'), clearly distinguishing it from sibling tools by emphasizing aggregation and cross-sensor comparison.
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 specifies when to use the tool ('For aggregation...and cross-sensor comparison over series too large to inline') and mentions the 'only SELECT is allowed' restriction, providing helpful context for tool selection.
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. |
| 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds critical behavioral context: stations are physical sensors (not modeled), coverage is uneven, and no station means no monitoring. There is 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 well-structured with the main purpose first, then data nature, then usage guidance. It is slightly long but every sentence adds value; could trim minor redundancy but overall efficient.
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 (0 required), 100% schema coverage, an output schema, and thorough annotations, the description is complete. It explains all search modes, output fields, and provides inter-tool dependencies and limitations.
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 description coverage is 100%, but the description adds extra meaning: e.g., resolving coordinates via other tools, API hard-cap on radius, and that the same pollutant can have multiple parameter IDs. This significantly aids correct parameter usage.
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 specifies the verb 'find', the resource 'air-quality monitoring stations (measured by physical sensors, not modeled)', and the search methods (near a point, within a bounding box, or by country). It clearly distinguishes from sibling tools by stating it is the required first step for obtaining location IDs used by openaq_get_readings 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?
The description explicitly states when to use this tool (first step for readings/measurements) and when not to (for modeled coverage, use open-meteo-mcp-server's air-quality tool). It also explains the limitation that absence of stations indicates no monitoring, not clean air.
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; the tool resolves the station's sensor for that parameter internally (v3 series are sensor-scoped, but you think in stations). 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?
Annotations declare readOnly, openWorld, and idempotent hints. The description adds critical behavioral details: DataCanvas spill for large results, internal sensor resolution, and no unit conversion. No contradictions; description complements annotations well.
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 front-loaded with the core purpose and efficiently packs useful information without excessive fluff. Each sentence contributes value, though it is slightly verbose. Well-structured for AI consumption.
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 complexity (7 parameters, 2 required, 1 enum, output schema exists), the description covers all critical aspects: purpose, parameters, aggregation choices, DataCanvas behavior, and unit handling. The output schema reduces the need for return format details.
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?
100% schema coverage means all parameters have descriptions. The tool description adds context beyond schema: explains the rationale for locationId/parametersId, the effect of aggregation options, and how datetimeFrom/datetimeTo patterns work. This extra information improves the AI's understanding of parameter usage.
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 the tool returns historical measurement series for one pollutant at one station over a date range, with a specific use case for trend analysis. Distinguishes itself by explaining the internal sensor resolution and mentioning sibling tools like openaq_find_locations and openaq_list_parameters for parameter IDs.
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?
Provides explicit guidance on when to use different aggregations (e.g., 'daily' for multi-month trends, 'raw' for fine-grained analysis) and explains the internal sensor resolution. Lacks explicit comparison to openaq_get_readings, but the context is sufficient for an AI agent to decide.
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 | Local case-insensitive filter on country code and name (e.g. "united", "IN", "germany"). The list is bounded (~153 countries); omit to list all. Filters the fetched list on our side, not an upstream search. |
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?
Beyond annotations (readOnlyHint, idempotentHint), description explains the tool surfaces coverage disparity and bounded list of ~153 countries. 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?
The description is efficient, but could be slightly more compact. All sentences contribute value; no superfluous text.
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 single optional parameter, full annotations, and presence of output schema, the description covers all necessary context: purpose, behavior, and appropriate use.
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 description coverage is 100%, and the description adds context: the query is a local case-insensitive filter applied after fetch, not an upstream search.
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 is a catalog of country-level coverage with specific fields (id, ISO code, name, date span, parameters). It distinguishes from sibling tools by positioning it as a prerequisite to regional sweeps.
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?
Explicit guidance: answers questions like 'which countries have NO2 monitoring?' and advises calling it before openaq_find_locations to check recent data.
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 | Local case-insensitive filter on code, display name, and description (e.g. "pm" for particulates, "ozone", "co"). The full catalog is small (~44 entries); omit to list everything. This filters the fetched list on our side — it is not an upstream search. | |
| 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 declare readOnlyHint and idempotentHint. Description adds valuable context: live fetch, local filtering, catalog size (~44 entries), and disambiguation purpose. 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?
Two sentences: first states what the tool returns, second explains its purpose and usage. No redundant words, well-organized.
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?
For a simple catalog listing tool, the description is complete: return fields, usage example, and scope. Output schema exists but description does not need to explain it.
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%, baseline 3. Description adds meaning for query (local case-insensitive filter, not upstream search) and pollutantsOnly (excludes meteorological parameters). Adds value beyond 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?
Description clearly states it lists pollutants with canonical units and unique IDs, serving as a unit-disambiguation reference. It distinguishes itself from sibling tools like openaq_list_countries by explicitly naming the tools it supports.
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 when to use: to get parametersId for other tools and interpret units. Mentions it's a small bounded catalog fetched live. Does not explicitly state when not to use, but context is clear.
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!