openaq-mcp-server

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

With readOnlyHint=true already signaling a safe read, the description adds valuable context: it reports the output contents (row count, column names) and the requirement that DataCanvas must be enabled. It doesn't discuss failure modes or rate limits, but the output schema covers return structure. This goes beyond the annotation without contradicting it.

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 action, and each sentence earns its place. The first sentence states purpose and value; the second details the output and prerequisite. No redundant or filler content.

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 listing tool with one parameter and an output schema, the description provides enough context: purpose, usage timing, required precondition, and output summary. It doesn't cover error scenarios, but the output schema and annotations cover the essential details, making it sufficiently complete for an agent to invoke correctly.

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 input schema fully describes the single parameter canvas_id with a contextual explanation ('DataCanvas id returned by openaq_get_measurements when a series spilled'). Since schema coverage is 100%, the baseline is 3, and the description doesn't add additional parameter-level meaning beyond that. This meets the baseline without exceeding it.

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 function: 'List the tables and columns staged on a DataCanvas'. It explicitly ties this to a sibling tool ('so you can write valid SQL for openaq_dataframe_query'), which distinguishes it and clarifies its role. The specific verb 'List' and the resource 'DataCanvas' make the purpose unambiguous.

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 clear context on when to use the tool: before running openaq_dataframe_query to avoid guessing column names. It also mentions a prerequisite ('Requires DataCanvas to be enabled'), which is helpful for the agent. However, it doesn't explicitly state when not to use it or compare with other sibling tools like openaq_get_readings, so it falls just short of a 5.

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

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

While annotations already declare readOnlyHint=true, the description adds meaningful behavioral detail: 'Only SELECT is allowed — writes, DDL, and file/network table functions are rejected.' This tells the agent exactly what operations will fail, which is beyond the annotation. It also explains the table naming convention from openaq_get_measurements, adding context not 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.

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

The description is three sentences, each with a distinct purpose: purpose, use case, and restrictions. It is front-loaded with the core action, and every sentence adds necessary context without redundancy.

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 tool has an output schema, so return values are covered externally. The description explains the tool's role in the workflow, its constraints, and its relationship to sibling tools, making it complete for a query tool of this complexity.

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%, so both parameters are already well-documented. The description adds extra value by explaining how to reference tables ('measurements_<sensorId>') and recommending the use of openaq_dataframe_describe to discover table/column names, which helps the agent construct correct SQL.

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 opens with a specific verb+resource: 'Run a read-only SQL SELECT against the measurement tables openaq_get_measurements staged on a DataCanvas.' It also distinguishes the tool from siblings by stating it is for 'aggregation (monthly means, exceedance counts) and cross-sensor comparison over series too large to inline,' and points to openaq_dataframe_describe as a prerequisite.

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 this tool vs. others: 'For aggregation... and cross-sensor comparison over series too large to inline.' It also gives a clear prerequisite: 'Use openaq_dataframe_describe first to see table and column names.' The read-only and SELECT-only restriction is also clearly stated.

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

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

Annotations declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context beyond these: '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.' It also discloses behavioral nuances such as the 100-station cap per page, distance ordering only within a page, and the API's hard 25000m radius limit, none of which contradict 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?

Every sentence earns its place. The description is front-loaded with the core purpose, followed by return fields, integration context, a coverage caveat, and an alternative tool. It is longer than typical descriptions, but given seven parameters and the need to convey paging and coverage nuance, the length is justified with zero redundancy.

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?

Despite having an output schema (so return values need not be explained), the description still lists key return fields, clarifies search modes, and provides crucial real-world caveats about uneven sensor coverage. It also explains how this tool fits into the broader workflow with openaq_get_readings/openaq_get_measurements and alternative tools, making it fully self-contained for an agent to decide when and how to invoke 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?

The input schema already provides 100% coverage, including detailed descriptions for every parameter and mutual exclusivity notes. The main description adds extra semantics by summarizing the three search modes (coordinates+radius, bbox, iso) and mentioning the returned 'distance from the query point (when searching by coordinates)', which is not in the schema. This adds modest value beyond the schema, but the schema already carries most of the heavy lifting.

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: 'Find air-quality monitoring stations... near a point, within a bounding box, or by country.' It lists returned fields (id, name, coordinates, distance, country, provider, parameters, datetimeLast) and explicitly distinguishes from sibling tools by positioning it as the required first step for openaq_get_readings/openaq_get_measurements and by naming open-meteo as the alternative 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?

The description gives explicit when-to-use and when-not-to-use guidance: 'For dense modeled coverage anywhere on Earth, use open-meteo-mcp-server's air-quality tool instead.' It also explains paging is intended for iso/bbox sweeps, not near-me searches, and references companion tools like openaq_list_countries and openaq_list_parameters for parameter discovery.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description is free to add behavioral detail: aggregation adds per-bucket statistics, large ranges spill to a DataCanvas with a preview and canvasId, and the server never converts units. This goes beyond annotations and provides valuable operational context.

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 around 150 words and well-structured: it front-loads the purpose, then explains aggregation, spill behavior, and unit handling. Every sentence carries specific information, though a slight trim could make it punchier without losing content.

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 params, output schema exists, annotations present), the description covers the key contextual aspects: use case, aggregation options, large-result handling, and unit policy. It is complete for an agent to select and invoke the tool correctly.

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%, including detailed explanations for each parameter (e.g., date formats, aggregation enum, limit behavior). The tool description reinforces the need for locationId and parametersId but does not add substantial meaning beyond the schema. Baseline 3 is appropriate.

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 function: 'Historical measurement series for one pollutant at one station over a date range.' It is specific about the resource (measurements), scope (one pollutant/station/date range), and distinct use cases like trend analysis. The spill-to-DataCanvas behavior also differentiates it from sibling 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 provides explicit use cases ('for trend analysis and "was last week worse than the monthly average?"') and explains when to use aggregation modes. It references a sibling tool (openaq_dataframe_query) for handling large spill results, but does not explicitly mention when not to use this tool or alternative retrieval tools like openaq_get_readings.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial context: output shape ('one record per parameter'), the join from the raw feed keyed by sensor id, the resolution behavior for coordinates (nearest station within 25km), and the warning about data recency and coverage gaps. This goes far beyond the structured 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 front-loaded with the main purpose and uses a well-structured, moderately sized paragraph. Every sentence contributes meaningful context—format, usage, and caveats—without repetition. There is no wasted wording.

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 an output schema exists, the description doesn't need to enumerate return fields. It covers the essential non-obvious context: data recency varies, readings are measured with coverage gaps, not modeled, and location resolution logic. This is complete for a tool of this complexity.

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 essentially paraphrases what the schema already states. It reinforces the dependency that parametersId is required with coordinates and optional with locationId, and points to sibling tools for source ids, but adds no genuinely new parameter-level meaning 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 opens with a specific verb and resource: 'Latest measured value for every sensor at a monitoring station — the current-conditions tool.' It clearly distinguishes itself from sibling tools like openaq_get_measurements by positioning itself as the 'current-conditions' tool, not a time-series tool.

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 clear usage context: use it for current conditions, pass a locationId from openaq_find_locations, or pass coordinates with parametersId to auto-resolve to a nearby station. It also mentions data recency caveats. However, it does not explicitly name when to use openaq_get_measurements as an alternative, so it is not a 5.

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

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

Annotations already mark the tool as read-only and idempotent, so the description doesn't need to restate safety. It adds valuable context about uneven global coverage and that it surfaces where measured data exists, which goes beyond the schema and annotations. 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, zero waste. The first sentence lists the returned fields, the second explains the tool's role in a broader workflow. Information is front-loaded and every clause contributes.

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 tool is simple, has an output schema, and strong annotations. The description covers purpose, usage timing, and data coverage nuances. No additional behavioral details are necessary for effective invocation.

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%, so baseline is 3. The description reinforces the purpose of parameter filtering (e.g., NO2 monitoring) but adds no new syntax or semantics beyond the schema, which already explains query and parametersId fully.

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 identifies the tool as a catalog of country-level coverage with specific fields (id, ISO code, name, datetimeFirst/datetimeLast, parameters). It uses a specific verb 'catalog' and distinguishes its role from downstream tools like openaq_find_locations by positioning it as a pre-check.

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 it: 'availability check before a regional sweep' and 'before you call openaq_find_locations.' It provides a concrete use case ('which countries have NO2 monitoring?') but does not name alternative tools for when not to use it, though the context implies find_locations for specific location queries.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds valuable context beyond annotations: it is a live-fetched bounded catalog (~44 items), notes that the same pollutant exists under multiple ids with different units, and highlights the disambiguation purpose—useful behavioral details not present in the schema or 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 concise yet information-dense, with only two sentences that each earn their place. It front-loads the core purpose and includes concrete examples (CO in different units) that illustrate the unit-disambiguation function without unnecessary fluff.

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 read-only catalog tool with full schema coverage, idempotent read-only annotations, and an output schema, the description is complete. It explains the catalog's bounded nature, use case, and relation to sibling tools, making it self-sufficient for an agent to invoke correctly.

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 the baseline is 3. The description adds value by explaining the catalog's size (~44) and how the query filters over code/display name/description, complementing the schema's parameter descriptions. It also clarifies the pollutantsOnly parameter's effect (excluding meteorological/auxiliary parameters) which is slightly more contextual than the schema's wording.

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: listing a catalog of pollutants with canonical units, including specific examples and the schema's id/code/name/unit fields. It distinguishes itself from sibling tools by explicitly being a reference catalog for unit disambiguation, which is unique among the listed 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 states when to use this tool: to pick the exact parametersId for openaq_find_locations / openaq_get_readings / openaq_get_measurements and to interpret a reading's unit. It also provides a clear alternative context by naming these siblings, giving the agent direct guidance on how this tool fits into the workflow.

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