nws-weather-mcp-server

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

Annotations already mark the tool as read-only (readOnlyHint=true). The description adds value by disclosing the output ordering (sorted by proximity) and that each result includes distance and bearing, which is not in the annotations or schema. No contradiction 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 exactly two sentences, front-loaded with the purpose and output, and the second sentence gives a clear use case. There is no fluff or repetition of schema/annotation contents.

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 rich output schema and fully-documented parameters, the description covers everything essential: what the tool finds, how results are ordered, and why an agent would call it (to get station IDs for observations). No critical missing context.

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%; every parameter (latitude, longitude, limit, cursor) has its own detailed description. The tool description does not add further parameter-specific semantics, so 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 uses a specific verb ('Find') and resource ('weather observation stations'), specifies the output (sorted by proximity with distance and bearing), and explicitly connects to a sibling tool (nws_get_observations). This clearly differentiates it from the other NWS 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 an explicit usage directive: 'Use to discover station IDs for nws_get_observations.' This tells the agent when to employ this tool, but it does not explicitly state when not to use it or mention alternative tools, so it stops one step short of full 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?

The description adds behavioral detail about output modes (named 12-hour periods vs hourly), and the readOnlyHint annotation covers safety. However, it does not disclose pagination via cursor, the fact that each call re-fetches the forecast, or any other constraints beyond the basic output format. Given minimal annotations, this is only a partial disclosure.

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, front-loaded with the primary purpose, and contains no filler. It efficiently communicates the core functionality.

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 core purpose and output modes but omits the pagination behavior (cursor) and does not clarify how this tool differs from zone forecasts. The output schema and full parameter descriptions compensate for some gaps, but the description alone is not fully self-sufficient for distinguishing and using 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?

All four parameters are fully documented in the input schema with descriptions, so the schema carries the parameter semantics. The tool description repeats only the hourly distinction and adds no new parameter meaning, so a baseline score 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 clearly states the tool retrieves weather forecasts for US locations and specifies the two output formats (named 12-hour periods vs hourly). It does not explicitly differentiate from the sibling nws_get_zone_forecast, which also provides forecasts, so it only partially distinguishes among siblings.

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?

No guidance is provided on when to use this tool versus alternatives such as nws_get_zone_forecast or nws_get_observations. The description implies it is for point forecasts but does not state that or mention scenarios like needing current conditions or zone-based forecasts.

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 readOnlyHint=true, the description adds valuable behavioral context beyond annotations by disclosing automatic nearest-station resolution from coordinates. This is a non-obvious behavior that affects results. It does not discuss edge cases like missing station, but the annotation covers safety and the description adds meaningful extra insight.

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 sentences, front-loaded with the core purpose, no redundant wording. Every clause adds information about how to specify the target or what the tool returns.

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 output schema exists, so return values are covered. The description explains the two input modes and the automatic resolution behavior. It is slightly incomplete in that it does not mention what happens if neither coordinates nor station_id are provided, but the schema's optional parameters still make the tool callable. Overall, the description plus schema and annotations provide sufficient context for a simple read-only 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 100%, and each parameter has a detailed description including examples. The tool description only restates what the schema already says (coordinates vs station ID), adding no new meaning. Baseline 3 applies given the high schema coverage.

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 a specific verb ('Get') and resource ('current weather observations') with clarifying detail ('actual measured conditions') that distinguishes it from sibling forecast tools. It also explains the two ways to specify the target (coordinates or station ID).

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 clearly explains how to invoke the tool (coordinates or station ID) and implicitly separates it from forecasts by emphasizing 'actual measured conditions'. However, it does not explicitly name alternative tools for forecasts or exclusions, missing the top bar for explicit when/when-not 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?

The readOnlyHint annotation already signals a safe read operation, so the description does not need to restate that. It adds meaningful context by explaining what each product type contains (e.g., AFD gives 'synoptic setup, model guidance, forecaster confidence'), which helps the agent set expectations for the returned content. 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 moderately sized (about 4 sentences) and front-loaded with the core purpose. Each sentence serves a distinct role: first defines the tool, second explains the default, third enumerates the other product types, and the last clarifies the office code origin. It is slightly longer than necessary but avoids fluff and is well organized.

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 an output schema present and readOnlyHint true, the description does not need to detail return values or safety. It covers the tool's function, the product_type options, and the office parameter's source. It does not mention failure modes (e.g., what happens if a WFO has no discussion) or rate limits, but for a simple read-only retrieval tool, the level of detail is sufficient for an agent to invoke it 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?

The input schema already provides descriptions for both parameters (office and product_type) with 100% coverage, so the baseline is 3. The description adds value by explaining the office code is a WFO identifier sourced from nws_get_forecast and by expanding on the meaning of product_type entries (e.g., HWO is a '1-7 day outlook for severe weather, flooding, winter weather'). This goes beyond a simple repetition of 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 opens with a specific verb and resource: 'Get the latest narrative forecast product from a Weather Forecast Office (WFO).' It clearly identifies the default product (AFD) and lists alternate product types (HWO, ZFP, SPS), which distinguishes it from sibling tools like nws_get_forecast or nws_get_zone_forecast. The phrase 'narrative forecast product' delimits its scope precisely.

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 explains that the default product is AFD and gives a one-sentence definition of each product type, helping the agent choose the right product_type. It also points out that the office code is the 'office' field from nws_get_forecast, providing a concrete cross-reference. However, it does not explicitly state when to avoid this tool or prefer a sibling like nws_get_zone_forecast for ZFP, so it stops short of full exclusion 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?

The annotations declare readOnlyHint=true, and the description adds behavioral context: it returns human-readable zone forecasts and warns that county/fire entries will not resolve. This goes beyond the basic read-only flag and explains expected failure cases.

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 efficiently structured with the core purpose first, then return details, then integration context and caveats. Every sentence adds necessary information without 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?

The description covers the purpose, expected output, source of zone codes, and important type-based limitations. Given the output schema and annotations, this is a complete enough description for an 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?

The input schema describes the zone_id parameter thoroughly, including format, examples, and source tools. The description's mention of the XXZ### pattern is redundant but consistent; it only slightly reinforces the schema, so no major additional meaning is added.

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 the specific action 'Get the text forecast for a public NWS forecast zone' and details the return type (named periods with narrative text). It distinguishes from siblings by mentioning the alert-to-forecast chain and the specific zone codes, clearly stating what the tool is for.

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 explains when to use this tool—after obtaining zone codes from nws_search_alerts or nws_find_stations—and includes an explicit exclusion: only affectedZones entries with type 'forecast' work, while 'county' or 'fire' will not resolve. This gives practical usage context and alternative paths.

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 aligns with the readOnlyHint annotation and adds context that the tool returns all valid event names. It doesn't conflict with annotations; the read-only nature is clear, and no side effects are implied. The description could mention the return format, but output schema likely covers that.

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 concise sentences: first states the core function, second provides usage context. Every word earns its place; no filler 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?

Given the tool's simplicity (no parameters, output schema present, readOnly annotation), the description fully covers its purpose and usage. It even names a related sibling tool for integration context.

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 zero parameters, the schema is fully self-explanatory. The description reiterates 'No parameters required,' which is helpful but redundant. Baseline 4 applies; no further semantic clarification is needed.

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 a specific verb 'List' with a clear resource 'valid NWS alert event type names'. It immediately distinguishes this tool from siblings by explaining its role in discovering values for nws_search_alerts and browsing alert categories.

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: to discover valid event filter values for nws_search_alerts or to browse alert categories. It also notes 'No parameters required,' signaling simplicity, which provides clear context for selection.

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 readOnlyHint=true, the safety profile is already known. The description adds the 'active' scope (only current alerts) but does not disclose pagination continuity, data freshness, or any side effects. This is on par with the high-calibration example where annotations covered safety and the description added a scoping constraint.

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 concise sentences achieve high density: first states the action and scope, second lists the filter dimensions, third captures the key constraint and national-search behavior. No filler 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?

Given the tool's complexity (12 optional parameters, mutual exclusivity) and rich schema, the description provides a coherent overview and highlights the most critical constraint for correct usage. Output schema covers return values, and parameter details live in the schema, so the description is sufficiently complete for an agent to choose and 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?

Input schema description coverage is 100%, so the baseline is 3. The description's filter list and mutual-exclusivity note merely restate what the schema already documents per parameter, adding no new semantic meaning beyond a convenient summary.

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 action and resource: 'Search active weather alerts (watches, warnings, advisories) across the US.' This clearly distinguishes it from sibling tools like nws_list_alert_types or forecast retrieval, and the enumeration of filter dimensions (state, coordinates, zone, etc.) makes its function unmistakable.

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 operational context: it targets active alerts and explains that omitting all filters performs a national search. It also highlights the mutual exclusivity constraint. However, it does not explicitly contrast with alternative tools or state when not to use it, so it stops 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.