aviation-weather-mcp-server

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

Annotations already indicate readOnlyHint and idempotentHint. The description adds critical behavioral details: returns identifier variants, coordinates, elevation, data types; confirms ICAO-only acceptance and that IATA codes fail; specifies max 20 IDs. No contradiction.

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 information-dense sentences with no filler. The tool's purpose and key constraints are front-loaded, making it efficient for an AI agent 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 output schema exists, the description succinctly covers all usage modes (resolve by ID, discover by bbox or state) and highlights critical input rules. No gaps remain.

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% with descriptions for each parameter. The description adds crucial context beyond the schema, such as the requirement for at least one parameter, the ICAO-only constraint, and that bbox is for spatial queries. This significantly enhances usability.

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 uses specific verbs 'Resolve' and 'discover' to clearly state the tool's purpose: finding aviation weather stations by ICAO ID, bounding box, or US state. It distinguishes from sibling tools (e.g., aviation_get_metar) which retrieve weather data, not station metadata.

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 that at least one of station_ids, bbox, or state is required, and that station IDs must be 4-letter ICAO format. It provides guidance on input constraints but does not explicitly compare to alternatives, though siblings are for different purposes.

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?

Describes return content (hazard type, severity, altitude range, valid period, polygon coordinates, raw text) and covers US-centric limitation. Annotations already indicate readOnly, openWorld, idempotent; description adds valuable behavioral details.

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: purpose, result fields, and usage notes. No fluff, front-loaded with key 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?

With output schema present, description summarizes return fields, explains coverage scope, and normalizes empty results. Fully equips 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 has 100% coverage, but description adds meaning: hazard enum mapped to specific advisory types (e.g., TURBULENCE = AIRMET Tango) and explains each. This goes beyond schema descriptions.

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 'Get active SIGMETs and AIRMETs' and lists returned fields. Distinguishes from sibling tools (e.g., aviation_get_metar, aviation_get_taf) by focusing on advisories.

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 context: 'Coverage is US-centric (NWS Aviation Weather Center)' and normalizes empty results. Does not explicitly state when not to use, but sufficient for expected use.

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?

The description details the decoded fields returned (wind, visibility, ceiling, temperature, etc.) and the computed flight category and raw METAR string, exceeding what readOnlyHint and idempotentHint annotations provide. No contradictions 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 concise and front-loaded: states purpose, lists return fields, then gives usage guidance. Every sentence adds value 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?

Given the tool's complexity (multiple stations, history, computed categories), the description covers purpose, parameters, return data, and sibling tool usage. It lacks explicit error handling notes but is otherwise complete for an MCP tool with a rich 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 100%, so the description does not need to add much. It reiterates the station ID count and hours range, which is helpful but not additive 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 gets current METAR weather observations for one or more airports. It differentiates from siblings by explicitly directing users to aviation_find_stations for resolving ICAO IDs, and the sibling names (aviation_get_taf, etc.) imply other weather data types.

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 mentions accepting 1-10 ICAO IDs and suggests using aviation_find_stations to verify IDs. It does not explicitly exclude usage for forecasts or other weather data, but the sibling names provide context. A clear when-not-to-use statement would elevate this to 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 declare readOnlyHint=true, openWorldHint=true, and idempotentHint=true. The description adds behavioral context: constraints on parameter exclusivity, coverage, and data sparsity. It does not 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?

The description is three sentences with clear structure: purpose, output details, usage constraints, and a caveat. Every sentence adds value; no unnecessary 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?

Given that output schema exists, the description does not need to detail return values. It covers what the tool does, parameter usage, coverage limitations, and data characteristics. This is complete for a read-only query 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 coverage is 100%, so parameters are well-documented. The description adds semantic value by explaining the mutual exclusivity of station_id and bbox, and the function of distance_nm relative to station_id.

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 retrieves 'recent Pilot Reports (PIREPs)' and specifies the data returned (decoded turbulence, icing, cloud reports with altitude, etc.). It distinguishes from sibling tools like aviation_get_metar and aviation_get_taf by focusing on PIREPs.

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 says 'Requires either station_id ... or bbox ... — not both', providing clear usage guidance. It also notes coverage is 'US-centric' and that absence of reports does not imply smooth conditions. However, it does not explicitly state when to use this tool instead of siblings.

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. The description adds behavioral details beyond these: it returns raw TAF string, decoded weather conditions, and cloud layers; it explains the forecast time horizon and issuance restrictions. No contradictions 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 two sentences: a concise statement of the main function and a supplementary sentence with context. No redundant information, every word contributes. Front-loaded with the core purpose.

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 (weather forecast with multiple fields, availability constraints) and the presence of an output schema, the description covers all necessary aspects: purpose, scope, return structure, constraints, and cross-reference to another tool. No gaps for an agent to misinterpret.

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% (the only parameter station_ids is fully described in schema). The description adds minimal new semantic information: it reiterates the 1-4 station limit and gives examples (KSEA, KJFK). Since the schema already provides necessary parameter meaning, the baseline of 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 specifies exactly what the tool does: 'Get the Terminal Aerodrome Forecast (TAF) for one or more airports.' It lists returned fields (valid times, wind, visibility, etc.) and distinguishes from siblings by noting TAF availability depends on airport type and referencing aviation_find_stations. The verb 'Get' and resource 'TAF' are precise, with constraints (1-4 stations) and examples.

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 usage context: TAFs cover 24-30 hours, are issued only for airports with scheduled commercial service, and suggests checking TAF availability via aviation_find_stations. It does not explicitly state when not to use this tool or mention alternatives like METAR for current conditions, but the context is sufficient for an agent to decide.

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