Hermes — Air Quality Intelligence

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

No annotations are provided, so the description carries the full burden. It does add useful behavioral context: the tool combines multiple data sources, returns a structured 'summary' dict, and tells agents to present the summary description to users first. However, it does not disclose limitations like data freshness, geographic coverage, or potential fallback behavior if no monitors are nearby.

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-organized with a clear summary sentence, usage guidance, return value note, and a concise argument list. Each sentence adds value and no information is wasted. It is appropriately sized for a tool with two parameters and moderate complexity.

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 covers the tool's purpose, when to use it, what it returns, and key parameter semantics. It also positions itself against siblings. However, because there is no output schema, a few specifics about the response structure (e.g., sections returned for each purpose) could strengthen completeness, though the mention of a structured 'summary' dict is adequate.

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 0%, so the description must compensate. It does so thoroughly: 'location' is explained as Postcode, place name, or "lat,lon", and 'purpose' receives a full list of valid values with explanations. This provides meaning well beyond the bare schema properties and defaults.

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 performs a 'Comprehensive air quality assessment for a location in one call' and specifies what is combined (monitor discovery, current readings, DAQI). It also implicitly distinguishes itself from siblings by positioning as the first tool to call for any location-based air quality question.

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 guidance: 'Use this as the first tool call for any air quality question about a location.' It also provides an when-not-to-use example by pointing to the dedicated `trend_analysis` tool for long-term trends. This is strong usage differentiation.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the return format ('Returns a PNG chart image with a brief text summary') and explains parameter defaults and effects (e.g., pollutants default, show_who_guidelines flag). While it does not describe error handling or side effects, it covers the core behavior relevant to an agent.

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 compact and well-organized: opening statement of function, return type, then usage guidance, followed by a bullet-like Args list. Every sentence serves a purpose; no redundancy or filler.

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 (8 parameters, no annotations, no output schema), the description is remarkably complete. It covers all parameters, the output type, defaults, and usage context, leaving no critical gaps for an agent to safely invoke the 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 description coverage is 0%, but the description includes an Args block that explains every parameter: date format, location alternatives, pollutants default, frequency options, and boolean flag behavior. This fully compensates for schema silence and adds meaning beyond type/default.

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 first sentence uses a specific verb and resource: 'Generate a time series chart of air quality data.' The usage guidance ('Use this when users ask about trends, patterns, or want to visualise air quality over time') further clarifies intent and distinguishes it from sibling tools like trend_analysis or get_historical_aq.

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 the tool ('Use this when users ask about trends, patterns, or want to visualise air quality over time'), providing clear context. However, it does not mention alternative tools for cases like raw data retrieval, so it lacks explicit when-not-to-use guidance.

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?

With no annotations provided, the description carries the full burden. It meaningfully discloses behavior: returns a ranked comparison by pollutant, includes DAQI bands and distance to nearest monitor, and imposes a 2–6 location constraint. It does not mention side effects or error handling, but as a read-only comparison tool, this is acceptable and the description goes beyond a mere tautology.

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 and well-structured: it front-loads the main purpose, then the output, then use cases, and finally parameter details. Every sentence earns its place with no redundancy. The use of a short 'Args' section cleanly separates parameter semantics without bloating the main description.

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 moderate complexity (2 parameters, no output schema, no annotations), the description covers all essential aspects: purpose, output shape, use cases, and parameter format/constraints. It provides enough detail for an agent to select and invoke the tool correctly, even without an output schema.

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 0%, so the description compensates exceptionally well. It explains the locations parameter format ('postcodes, place names, or "lat,lon"') and the 2–6 item constraint, and clarifies the pollutants parameter as optional with an example and default behavior. This adds substantial meaning beyond the bare 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 a specific action ('Compare current air quality') and resource ('across multiple locations side-by-side'), distinguishing it from siblings like get_current_aq which likely handles a single location. It also mentions the key output (ranked comparison by pollutant with DAQI bands), leaving no ambiguity about the tool's purpose.

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 case contexts ('comparing development sites, school locations, or residential options'), giving clear guidance on when to use this tool. It does not name alternative tools or state when not to use it, but the use case framing is sufficiently clear and implies comparison scenarios as opposed to single-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?

With no annotations, the description carries the full burden of behavioral disclosure. It explicitly reveals the return structure ('a summary with plain-English health assessment... raw aqi and who_compliance data') and even directs presentation order. It does not discuss error handling or authentication, but for a read-only data tool, the key behaviors are transparently covered.

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, then logically breaks down returns and arguments. Every sentence provides necessary information: the health-summary focus, the presentation instruction, and the parameter formats. It is concise despite having multiple sections—no fluff or 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?

For a tool with no output schema and no annotations, the description does a good job explaining return values and parameters, making it largely complete. However, it omits edge-case behavior (e.g., invalid location, missing data) and any rate limits or prerequisites, so it leaves a small but non-critical gap.

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 0%, so the description must compensate—and it does thoroughly. For each parameter it explains the acceptable format and choices: location as 'Postcode, place name, or "lat,lon"', index with three AQI systems and a default, period with four time frames. This goes well beyond the schema's bare type/default information.

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: 'Get an AQI assessment with health advice and WHO compliance check.' This specific verb+resource combination distinguishes it from sibling tools like get_current_aq and assess_location_aq, which focus on raw readings or location assessment rather than a combined health summary.

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 implies when to use the tool—whenever an AQI summary with health advice and WHO compliance context is needed—and instructs the agent to 'Present the summary to users first.' However, it does not explicitly mention when not to use it or name alternative sibling tools, so it stops short of a full exclusionary guideline.

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 are absent, so the description carries the full disclosure burden. It partly meets that burden by describing the return shape: a 'summary' with health assessment and advice, 'readings' from nearby monitors, and 'metadata' on freshness and sources. It still omits permissions, rate limits, behaviour on an unresolvable location, and units of measurement.

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 purpose, followed by a returns section and an Args block, so the reader can scan in order. Nearly every sentence carries information, though the 'Also returns...' sentence partly restates the first paragraph's health-context framing.

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 four parameters, 0% schema coverage, no annotations, and no output schema, the description does the heavy lifting well: it documents every argument with examples and describes the three return fields an agent must present. Residual gaps are units, freshness thresholds, and failure modes, which are minor for a current-conditions read 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 description coverage is 0%, so the description must supply parameter meaning, and it does so for all four arguments. Examples: location accepts a postcode, place name, or 'lat,lon'; radius_km gives the default; and pollutants and sources get concrete example values. It does not state the default or behaviour when filters match no monitors.

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: 'Get the most recent air quality readings near a location, with health context.' That clearly separates it from get_historical_aq (past data) and from the kb_* explainer tools. It does not name a sibling outright, so an agent must infer from the names that this is the current-conditions tool rather than the comparison or trend 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 only real usage direction is the output instruction 'Present the summary to users first,' which tells the agent how to order what it shows the user. The description gives no explicit when-to-use or when-not-to-use guidance versus assess_location_aq, get_aqi_summary, or compare_locations, so choosing between those siblings is left to inference from their names.

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?

With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses the return structure, per-monitor summary behavior, annual guideline comparison thresholds, partial-day exclusion rules, UTC time handling, and that the narrative should be presented first.

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 return behavior, then structured into clear caveats and an Args section. It is appropriately sized for a six-parameter analytical tool, with no obvious filler.

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 lack of annotations and output schema, the description is complete enough for correct invocation and interpretation. It explains both input semantics and important output caveats such as per-monitor statistics, partial-day exclusion, and annual guideline data-capture requirements.

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 0%, but the description compensates by documenting every parameter in the Args section. It explains ISO date formats, end-date inclusiveness, location formats, the location/site_code alternative, pollutant examples, and allowed frequency values with the default.

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 a specific verb and resource: get historical air quality data for a site or location, with health context. The historical scope distinguishes it from get_current_aq, though it does not explicitly name alternate sibling tools such as trend_analysis or regulatory_stats.

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 implies the tool is for historical air quality retrieval and explains how to identify a site via location or site_code, plus optional pollutants and frequency. However, it does not explicitly state when to use this tool versus siblings like trend_analysis, regulatory_stats, or assess_location_aq, so guidance is adequate but incomplete.

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?

With no annotations, the description carries the transparency burden. It discloses that the tool returns a markdown document, the default framework ('all'), and the optional pollutant filter. However, it does not state that this is a read-only operation, nor does it describe potential errors or behavior with invalid inputs. The mention of 'current' hints at data freshness but lacks detail.

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 compact and well-structured: a one-line purpose, an Args section for parameters, and a Returns line. Every sentence adds value, and the front-loaded purpose ensures quick understanding. No filler or redundant 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?

For a simple KB getter with two optional parameters and an output schema (though not shown), the description is mostly complete. It covers framework options, defaults, filtering, and return type. The main gap is a lack of predefined pollutant values or a note on how to discover them, but given the output schema exists and the tool is well-scoped, this is a minor omission.

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 0%, so the description must compensate. It adds meaning to 'framework' by enumerating allowed values ('WHO', 'UK', 'EU', 'all') and clarifies that 'pollutant' is an optional filter. However, it does not provide examples of pollutant names or explain format constraints, leaving some ambiguity for a parameter that is not enumerated in 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 states a specific action ('Get') and resource ('air quality guideline and target values'), clearly distinguishing it from sibling KB tools like kb_get_health_effects or kb_get_local_context. It also specifies the return format ('full guidelines document'), leaving no ambiguity about the tool's function.

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 implies usage by listing framework and pollutant filters, with defaults clearly noted. However, it does not provide explicit when-to-use guidance or contrast with alternative tools (e.g., 'use kb_get_health_effects for health impact info'). The context is clear enough for basic selection, but explicit exclusions are absent.

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?

No annotations are provided, so the description bears the burden of disclosure. It does state the output format ('Returns health effects document (markdown)') and the verb 'Get' implies read-only behavior. However, it lacks explicit mention of side effects, error behavior, or data sources, which would increase transparency further.

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 compact and well-structured: a one-sentence purpose, then a formatted Args block with valid values and default. Every line contributes useful information, with no redundancy or 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 tool with two simple parameters and a single markdown output, the description covers allowed inputs, default, and output type. It lacks details about error conditions or edge cases, but given the low complexity, it is nearly 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?

The description goes far beyond the input schema by enumerating allowed values for both pollutant ('NO2', 'PM2.5', 'PM10', 'O3') and population_group ('general', 'children', etc.) and specifying the default. This provides essential semantic meaning that the schema (with only titles) lacks.

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 action ('Get health evidence summaries') and the resource ('pollutant and population group'), which distinguishes it from sibling kb_get_* tools that target other content types. The purpose is specific and 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 implies use when health evidence is needed, but it does not explicitly contrast with sibling tools like kb_get_guidelines or kb_get_practical_advice. There is no when-not guidance, leaving some ambiguity for an agent deciding between related knowledge-base tools.

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?

No annotations are provided, so the description carries the burden. It discloses the return format (markdown) and allowed area values ('southwark', 'london'), but doesn't mention error behavior, read-only status, or handling of unrecognized areas. This adds some context but leaves gaps.

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 extremely concise: one purpose sentence, an Args line, and a Returns line. It front-loads the main intent, avoids redundancy, 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?

The tool is simple with one parameter and has an output schema, so the description is minimally sufficient. However, it lacks differentiation from sibling KB tools and does not clarify what 'contextual information' encompasses, which is a gap for a knowledge base 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 description coverage is 0%, so the description provides the only semantic meaning for the 'area' parameter. It gives concrete examples ('southwark', 'london') and mentions that any specific neighbourhood is allowed, significantly extending the schema's bare default.

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 gets area-specific contextual information, with a specific verb ('Get') and resource. It distinguishes from sibling KB tools by focusing on 'local context' and returning a markdown document, though the nature of 'contextual information' could be more explicit.

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 guidance on when to choose this tool over siblings like kb_get_guidelines or kb_get_health_effects. The description only implies usage for area-specific context without explicit exclusions, alternatives, or prerequisites.

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?

With no annotations, the description carries the transparency burden. It discloses the return format (markdown document) and lists the allowable topic values, which is helpful. However, it does not explicitly state that the operation is read-only, what happens on invalid input, or any other behavioral traits. The tool appears safe, but the description omits this 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 concise and well-structured, with a brief purpose statement followed by a list of accepted topic values and a clear return type. Every sentence adds value and there is no redundant information. The front-loaded purpose statement ensures quick understanding.

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 retrieval tool with one parameter, the description covers the essential inputs and outputs. The presence of an output schema likely explains the return document's contents, so the description need not elaborate further. Minor gaps remain around error handling, but these are not critical for such a straightforward 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?

The schema provides only the parameter name 'topic' with no description or enum, resulting in 0% coverage. The description compensates by enumerating all acceptable values, which gives the agent concrete options. While it doesn't explain the meaning of each topic, the labels are largely self-explanatory and the compensation is effective.

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: providing plain-language explanations of monitoring methods and limitations. This distinguishes it from sibling KB tools like kb_get_health_effects or kb_get_guidelines, which focus on different topics. The specific verb 'get' and resource 'explanations of monitoring methods' make the intent explicit.

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 implies usage for questions about monitoring methods and their limitations, but it does not explicitly mention when to use this tool over siblings. No alternatives or exclusions are provided. The allowed topics give some contextual guidance, but the usage guidelines remain implicit rather than 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that the guidance is generic and NOT keyed to individual context, and it specifies the return format (markdown). However, it does not address potential limitations such as KB recency or scope constraints, though such details are less critical for a read-only KB tool.

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 a clear opening sentence, a concise usage directive, and a simple Args/Returns layout. Every sentence contributes to the tool's understanding without unnecessary padding.

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 tool with one parameter and a markdown output, the description covers purpose, usage, parameter values, and return format. It also mentions the alternative tool, providing an agent with all necessary context to decide between this and the Clara 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?

The input schema only defines `situation` as a required string with no description or enum values (schema description coverage 0%). The description compensates fully by listing all permitted values, which is essential for correct invocation and fills the schema gap.

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 provides 'Generic protective-action guidance for a category of situation' and explicitly contrasts it with the personalized 'contextual_advice' tool. It also lists the specific situation categories, effectively distinguishing it from sibling KB retrieval 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 gives explicit directives: prefer the Clara MCP server's `contextual_advice` tool for personalized advice, and use this KB tool 'only as a fallback or when Clara is not available.' This provides clear when-to-use and when-not-to-use guidance with a named alternative.

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?

With no annotations, the description carries the full burden of disclosure. It clearly details the structure of the output: a 'summary' with count, status, and type explanations, and a 'monitors' list with metadata. It also adds a behavioral directive to present the summary first, which is valuable context beyond a generic 'list' operation.

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: a one-sentence summary first, then output details, then an Args section. Every sentence adds meaningful information without repetition or fluff. It is concise and front-loaded, making it easy for an agent to quickly grasp the tool's function.

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 three parameters and no output schema, so the description must cover both inputs and outputs. It explains the summary and monitors list sufficiently for an agent to handle the result correctly. However, it leaves 'full metadata' vague and doesn't mention ordering or edge-case behavior, making it strong but not exhaustive.

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 schema has zero descriptions (0% coverage), and the description fully compensates by explaining each parameter: location accepts postcode, place name, or 'lat,lon'; radius_km is the search radius with default 5.0; sources is an optional filter with concrete examples. This provides essential value that the schema lacks.

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 precise, specific action: 'List air quality monitoring sites near a location, with context.' It clearly identifies the resource (monitoring sites), the scope (near a location), and what is returned (summary and monitors list). This distinguishes it from sibling tools that deal with measurements or historical data.

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 implies a clear use case—finding monitoring sites near a location—but does not explicitly contrast with sibling tools like get_current_aq or get_aqi_summary. It does give a practical instruction ('Present the summary to users first') but lacks explicit alternatives or exclusionary guidance.

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?

With no annotations provided, the description carries the full burden. It discloses default behaviors for year and pollutants, and lists the returned metrics. This goes beyond a simple 'Get statistics' statement, though it does not discuss edge cases like invalid locations or data completeness.

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 compact, front-loaded with the main purpose, then lists return values and parameters in a clean inherited Argparse style. Every sentence adds value, and the parameter details are organized effectively 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 tool with no output schema and three parameters, the description covers the key inputs and outputs: it spells out parameter formats/defaults and enumerates the metrics returned. It does not specify the exact structure of the compliance assessment (e.g., boolean, string), but the information is sufficient for an agent to understand the tool's scope.

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 schema provides only titles and types (0% description coverage), so the description must compensate. It defines location as 'Postcode, place name, or "lat,lon"', explains the year default as 'most recent complete year', and clarifies pollutants as an optional filter with an example. This is highly informative and goes well 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 starts with a specific verb 'Get' and a clear resource: 'LAQM Annual Status Report-style statistics for a location.' It enumerates the exact outputs (annual means, percentiles, exceedance counts, data capture percentages, compliance assessment) and distinguishes itself from siblings like get_aqi_summary or chart_aq_trend, which focus on different aspects of air quality data.

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 implies usage context by detailing the statistical outputs and compliance assessment, making it clear this tool is for regulatory-style reporting. However, it does not explicitly mention when_not to use it or name alternative tools, so it falls 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?

With no annotations provided, the description is the sole source of behavioral information. It discloses that the tool returns 'temporal profiles showing typical patterns' and accepts location/pollutant/period, but it does not elaborate on output structure, data aggregation, or any limitations (e.g., how 'typical' is defined). This is adequate but not rich, warranting a 3.

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 compact and well-structured: a one-sentence summary, a sentence on output, a sentence on use cases, and a neatly formatted Args block. No fluff or 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?

While parameters are fully documented, the description is thin on output semantics (no detail on what a 'temporal profile' contains) and does not mention any exclusions or data caveats. Given no output schema, this gap makes it slightly incomplete, so a 3 is warranted.

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 schema provides only type and defaults; the description fills in all semantic details: location format ('Postcode, place name, or "lat,lon"'), valid pollutant values, and valid period values. This fully compensates for the 0% schema coverage, so a 5 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 opens with 'Analyse when pollution is highest — hour of day, day of week, and month', which clearly identifies the tool's function (temporal analysis) and distinguishes it from siblings like trend_analysis or chart_aq_trend by specifying the exact time granularities. It also states the output ('temporal profiles'), making 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 phrase 'Useful for advising on best times for outdoor exercise, school runs, or commuting' provides concrete application contexts, but it does not explicitly contrast with alternative tools or state when not to use it. This is clear context without exclusions, aligning with a score of 4.

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?

With no annotations provided, the description carries the full burden—and it delivers. It discloses the statistical methods (Theil-Sen and Mann-Kendall), robustness properties, return format ('summary' with plain-English and statistical details), and clamping behavior for out-of-range years including metadata.years_clamped. It even gives interaction instructions ('Present the summary to users first').

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: a clear purpose sentence, methodology, return value, then an Args section. Each sentence provides necessary information without fluff. The front-loading of the core action and the explicit arg format makes it 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?

For a tool with no output schema, the description adequately explains the return value ('summary' with plain-English description and statistical details) and key behaviors like clamping. Given the moderate complexity and 3 parameters, no critical information is missing. It is complete for an AI agent to select and 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 description coverage is 0%, but the description fully compensates. It explains all three parameters: location accepts postcode, place name, or 'lat,lon'; pollutant lists valid options and default; years specifies default, range, and clamping behavior. This exceeds typical schema documentation.

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: 'Analyse the long-term trend in a pollutant near a location.' It clearly distinguishes from sibling tools like get_current_aq (current conditions) and get_historical_aq (raw historical data) by focusing on long-term trend analysis with explicit statistical methodology.

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 for when to use this tool: for long-term trend analysis to determine improvement, worsening, or stability. It also notes robustness to outliers and missing data, implying suitability for noisy datasets. However, it does not explicitly state when not to use it or reference alternative tools, so it lacks the explicit exclusions seen in top-tier examples.

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