aviation-weather-mcp-server

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

Annotations already declare readOnlyHint and idempotentHint, which covers the safety profile. The description adds useful behavioral context beyond annotations: the ICAO format constraint (with example), the fact that it returns multiple identifier variants and data types, and the requirement of at least one parameter. No contradiction with annotations; the description enriches understanding.

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—three sentences—with no filler. It front-loads the purpose, then return info, then constraints. Every sentence earns its place, and the structure guides the agent from understanding to invocation.

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 has 3 parameters (one nested object), an output schema, and supportive annotations, the description is complete for agent use. It covers what the tool does, what it returns, input constraints, and invocation requirements. Nothing essential is missing, and the output schema handles return-value details.

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 parameters are well-documented in the schema. The description adds the crucial 'at least one required' constraint, which is not present in the schema (no required fields). It also reinforces the ICAO format and hints at using bbox/state to discover IDs. This adds value beyond the schema, though some redundant overlap exists.

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', 'discover') and a clear resource (aviation weather stations). It clearly distinguishes from siblings like aviation_get_metar/aviation_get_taf, which retrieve specific data types, whereas this tool resolves/discover station metadata. The return contents (identifier variants, coordinates, elevation, data types) are stated explicitly.

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 states the required condition ('At least one of station_ids, bbox, or state is required') and mentions the two discovery modes (bbox or state). It implicitly differentiates from sibling tools by focusing on station lookup rather than data retrieval, but it does not explicitly name alternatives or specify when NOT to use it. The guidance is clear but not exhaustive.

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 readOnly, openWorld, and idempotent hints, so the safety profile is covered. The description adds valuable context beyond annotations: US-centric coverage (NWS Aviation Weather Center), that it reads only the domestic SIGMET feed, the rejection behavior for AIRMET requests, and that empty results are normal. These details help an agent interpret behavior without contradicting the 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?

Four sentences, ~60 words, front-loaded with the core action and scope. It efficiently packs the return fields, coverage limitation, rejection behavior, and result normalization into a compact, readable description with 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?

The tool has three optional params, a nested bbox object, and an explicit output schema (present). The description covers the return fields, geographic scope, feed limitations, and edge cases (empty results). Given the output schema exists to detail return structure, nothing an agent needs to call this correctly is missing.

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%, with each parameter documented in the schema, including detailed enum semantics (e.g., why MTN OBSCN and LLWS are rejected, what advisory_type 'airmet' does). The description only lists the filter options without adding new meaning. Baseline 3 is appropriate because the schema carries the semantic load.

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 active domestic SIGMETs for a region.' It clearly states the scope (domestic SIGMETs) and enumerates returned fields (hazard type, severity, altitude range, valid period, polygon coordinates, raw text). This distinguishes it from the sibling tools (e.g., METAR, TAF, PIREPs, stations) by focusing exclusively 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?

The description provides explicit when-not guidance: it cannot return an AIRMET and rejects such requests. It also clarifies that empty results are normal during fair weather, which sets expectations. It mentions 'Filter by advisory_type, hazard, or bbox' but does not name alternative tools for AIRMETs; however, the sibling list contains no AIRMET tool, so the exclusion is contextual enough. Lacks a direct 'use this when you need SIGMETs' statement but that is strongly implied.

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 the tool as read-only and idempotent, and the description adds context about the output fields (wind, visibility, ceiling, flight category). However, since an output schema is present, the listing of return fields largely duplicates structured data. The description does not disclose additional behavioral traits such as error handling or station lookup behavior beyond the schema, so the value added beyond annotations is modest.

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 composed of four sentences, each with a distinct role: purpose, output, input constraints, and usage guidance. It is front-loaded with the core purpose and then provides necessary detail without excessive verbosity, though some repetition of schema-bound information could be trimmed.

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 (two parameters, an output schema, and read-only annotations), the description covers purpose, output shape, input constraints, and an alternative for station resolution. It does not discuss error cases or rate limits, but these are less critical for a safety-neutral read operation, making the description adequately 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 input schema provides 100% coverage for both parameters, including descriptions, types, defaults, and constraints. The description only repeats examples and limits already in the schema (e.g., '1–10 ICAO station IDs'), adding no new semantic meaning beyond what the schema already offers.

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 current weather observations (METARs)') and the resource ('for one or more airports'), with a specific list of returned fields. This makes it easily distinguishable from sibling tools like TAF forecasts or PIREPs, though it does not explicitly contrast them, the METAR focus 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?

It explicitly directs users to 'Use aviation_find_stations to resolve or verify an ICAO ID, or to discover nearby stations,' which is a clear alternative for a specific scenario. However, it does not mention when to choose this over aviation_get_taf or aviation_get_pireps, so the guidance is partial rather than comprehensive.

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, lowering the bar. The description adds valuable context beyond these: 'Coverage is US-centric; PIREPs are sparse and absence of reports does not imply smooth conditions' and the altitude-boundary behavior that reports with null altitude are dropped. These insights about data quality and edge-case handling are not present in the annotations and materially improve agent decision-making.

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 a single, information-dense paragraph that front-loads the purpose, then lists return contents, then the constraints, and ends with a data-coverage caveat. Every sentence earns its place; there is no filler or repetition. Structure is logical and an agent can parse it quickly.

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 has an output schema (not shown here, but indicated by 'has output schema: true'), the description does not need to detail return format. It covers the input constraints, altitude behavior, and data quality caveats. The complexity of six parameters with a nested bbox object is adequately addressed through the description's constraints and examples. Nothing essential for correct invocation is missing.

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 baseline is 3. The description goes well beyond schema descriptions by explaining cross-parameter constraints: the mutual exclusivity of station_id and bbox, the separation of distance_nm to station_id searches, the altitude ordering requirement, and the null-altitude drop behavior. It also clarifies the intended meaning of altitude filters in feet MSL. This is a significant addition the schema alone does not provide.

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 verb ('Get'), a resource ('Pilot Reports (PIREPs)') and the scope ('near an airport or within a bounding box'). It clearly distinguishes itself from siblings by naming the PIREP-specific content (turbulence, icing, cloud reports) and the raw string, so an agent can reliably separate it from METAR, TAF, advisories, and station lookup 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 internal usage constraints: 'Requires either station_id or bbox — not both', 'distance_nm belongs to the station_id search only', and 'altitude_min_ft must not exceed altitude_max_ft'. It does not explicitly name sibling tools or explain when to prefer this over them, but the resource is so specific that an agent would naturally select it for PIREPs. A small gap is the lack of explicit 'when-not-to-use' guidance relative to weather reports.

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 agent knows this is a safe read; the description adds valuable context beyond that: the 24-30 hour forecast window, the scheduled-service issuance constraint, and the explicit return-element list. It doesn't address error behavior or invalid-station handling, but given the read-only annotation profile, this is not a major gap.

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 that are front-loaded with purpose and efficiently convey returns, scope, and a usage prerequisite. The only minor redundancy is restating the 1-4 station count that maxItems/minItems already encode, but it serves as useful reinforcement. No filler or hedging.

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 read-only tool that already has an output schema and a single well-documented parameter, this is nearly complete: it covers what data is returned, the coverage window, the availability constraint, and the parameter format. It doesn't discuss forecast period count, units, or error handling, but those are minor given the annotations and 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 coverage is 100% — station_ids is fully documented with type, pattern (^[A-Z]{4}$), minItems, maxItems, and an example. The description's 'Accepts 1-4 ICAO station IDs (e.g., KSEA, KJFK)' largely restates the schema's constraints rather than adding new meaning. Baseline 3 is appropriate when the schema carries the semantic load.

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?

States a specific verb (Get), resource (Terminal Aerodrome Forecast), and target (one or more airports), and enumerates the exact return fields (valid times, wind, wind shear, visibility, weather, clouds, vertical visibility, raw TAF string). This makes the tool's scope unambiguous and distinguishes it from siblings like aviation_get_metar (current conditions) and aviation_get_advisories (warnings).

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 clear context: TAFs cover 24-30 hours and are only issued for airports with scheduled commercial service, plus points the agent to aviation_find_stations to confirm availability via data_types. It doesn't explicitly state when to prefer this over aviation_get_metar for current conditions, but the forecast-vs-observation framing implies it.

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