singapore_get_pm25

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

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so the safety profile is covered. The description adds real behavior beyond that: the default-to-latest rule, the fact that local limits apply per timestamp group, and that the pagination token is a preserved upstream token whose offsets must be consumed first. That extra context is genuinely useful but phrased cryptically and never explains the return shape.

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 short sentences, front-loaded with the metric and unit, which is good. But the final sentence about 'consuming local offsets before continuing the preserved upstream pagination token' is dense and ambiguous, costing more comprehension than it saves.

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?

An output schema exists so return values needn't be explained, and annotations cover safety. Still missing for a 7-parameter filter tool: how area/region/station_id relate, what valid values look like, and how the offset interacts with the pagination token when resuming.

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 only 14% schema description coverage, the description must carry the load, and it partially does: it clarifies that dates are Singapore-local, that omitting date yields the latest reading, and it touches limit/offset/pagination_token semantics. However, area, region, and station_id — three of seven parameters — get no explanation at all, and their interplay is unstated.

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?

Names the specific resource and unit ('NEA PM2.5 (micrograms per cubic metre)'), which clearly distinguishes it from siblings like singapore_get_psi or singapore_query_air_quality_annual. It lacks an explicit verb ('retrieve/fetch'), but the resource is 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?

'Latest if omitted' hints at the default-date case, but there is no guidance on when to pick this tool over singapore_get_psi or the annual air-quality query, and no statement of which filters (area vs region vs station_id) to prefer. The pagination sentence describes mechanics rather than when-to-use.

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