Air quality index and pollutants.
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"city": "<city>"
},
"name": "air_quality"
}
}| Name | Required | Description | Default |
|---|---|---|---|
| city | Yes | City name, optionally 'City, CC' |
Changes observed during successful MCP inspections.
Input schema / properties / cityAdded value: +{
+ "description": "City name, optionally 'City, CC'",
+ "type": "string"
+}Input schema / requiredAdded value: +[
+ "city"
+]Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and discloses almost nothing: it does not say whether the data is current or forecast, what AQI scale or units are used, where the data comes from, or whether the call is free/rate-limited. Only the implicit 'read-only lookup' nature can be guessed from the phrasing.
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?
It is a single short fragment with zero waste, which is good, but it is under-specified rather than concise — there is no front-loaded statement of action, scope, or output. One extra clause would have made it useful without bloating it.
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 one-parameter lookup this could be adequate, but with no annotations, no output schema, and a near-identical sibling tool, the definition leaves key questions unanswered: what is returned (AQI value, pollutant breakdown), in what units, and how it differs from 'get_air_quality'. That is not enough for confident selection.
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% for the single 'city' parameter, including the 'City, CC' format hint, so the schema already does the work. The description adds no further meaning such as whether the city name is matched fuzzily, whether a country is required for ambiguous names, or what happens on lookup failure, so baseline 3 applies.
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 names the resource (air quality index and pollutants) but uses a bare noun phrase with no verb, so it reads as a label rather than a statement of what the tool does. It also fails to distinguish itself from the sibling 'get_air_quality', which appears to cover the same resource, leaving an agent unable to choose between them from the text alone.
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?
There is no when-to-use guidance, no exclusions, and no mention of the obvious alternatives ('get_air_quality', 'get_weather', 'forecast'). An agent must infer entirely from the name that this retrieves current air quality for a city rather than a forecast or a weather bundle.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.