Skip to main content
Glama
Sign In

nws-weather-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Nws Find Stations

nws_find_stations
Read-only

Find weather observation stations near a location. Returns stations sorted by proximity with distance and bearing. Use to discover station IDs for nws_get_observations.

Input Schema

NameRequiredDescriptionDefault
limitNoMax stations per page. A page holds at most 50; a larger limit (up to 10000) is served as 50 and reported through requestedLimit and effectiveLimit. totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest.
cursorNoOpaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the station list, so pages are contiguous within one response; the registry changes rarely, but a later call can window an updated list.
latitudeYesCenter latitude for proximity search.
longitudeYesCenter longitude for proximity search.

Output Schema

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
shownNoNumber of stations returned in this page
noticeNoGuidance when the requested limit exceeded the page cap, when no stations were found near the requested coordinates, when stations remain beyond this page, or when the supplied cursor points past the end of the list.
stationsNoNearby stations sorted by distance
nextCursorNoOpaque token for the next page of stations — pass it back as `cursor`. Omitted when this is the last page.
totalCountNoTotal observation stations available near this location before the page limit was applied — NOT the number returned in this page, which is shown. Same value on every page of one query; compare it against shown to tell whether stations were withheld.
effectiveLimitNoThe page size applied instead of requestedLimit; continued pages keep it. Absent when the limit was within the cap.
requestedLimitNoThe limit asked for, when it exceeded the 50-station page cap; absent otherwise.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Max stations per page (1-50). totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest."New value: +"Max stations per page. A page holds at most 50; a larger limit (up to 10000) is served as 50 and reported through requestedLimit and effectiveLimit. totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest."
    • changedInput schema / properties / limit / maximum
      Previous value: -50New value: +10000
    • addedOutput schema / properties / effectiveLimit
      Added value: +{
+  "description": "The page size applied instead of requestedLimit; continued pages keep it. Absent when the limit was within the cap.",
+  "type": "number"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no stations were found near the requested coordinates, when stations remain beyond this page, or when the supplied cursor points past the end of the list."New value: +"Guidance when the requested limit exceeded the page cap, when no stations were found near the requested coordinates, when stations remain beyond this page, or when the supplied cursor points past the end of the list."
    • addedOutput schema / properties / requestedLimit
      Added value: +{
+  "description": "The limit asked for, when it exceeded the 50-station page cap; absent otherwise.",
+  "type": "number"
+}
  2. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `out_of_scope`: Coordinates fall outside US National Weather Service coverage Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `out_of_scope`: Coordinates fall outside US National Weather Service coverage. Other values are possible when a failure originates below the handler."
  3. Changed2 schema fields changed
    • removedOutput schema / properties / stations / items / properties / elevationM / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / stations / items / properties / elevationM / type
      Added value: +[
+  "number",
+  "null"
+]
  4. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "stations",
+      "totalCount",
+      "shown"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `out_of_scope`: Coordinates fall outside US National Weather Service coverage Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "out_of_scope"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}
    • removedOutput schema / required
      Removed value: -[
-  "stations",
-  "totalCount",
-  "shown"
-]
  5. Changed5 schema fields changed
    • changedInput schema / properties / limit / description
      Previous value: -"Max stations per page (1-50). totalFound still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest."New value: +"Max stations per page (1-50). totalCount still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest."
    • addedOutput schema / properties / shown
      Added value: +{
+  "description": "Number of stations returned in this page",
+  "type": "number"
+}
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of stations returned in this page"New value: +"Total observation stations available near this location before the page limit was applied — NOT the number returned in this page, which is shown. Same value on every page of one query; compare it against shown to tell whether stations were withheld."
    • removedOutput schema / properties / totalFound
      Removed value: -{
-  "description": "Total observation stations available near this location before the page limit was applied. Same value on every page of one query.",
-  "type": "number"
-}
    • changedOutput schema / required
      Previous value: -[
-  "stations",
-  "totalFound",
-  "totalCount"
-]New value: +[
+  "stations",
+  "totalCount",
+  "shown"
+]
  6. Changed6 schema fields changed
    • addedInput schema / properties / cursor
      Added value: +{
+  "description": "Opaque continuation token from a previous response's nextCursor. Omit for the first page. The token carries its own page size, so limit applies to the first page only. Every call re-fetches the station list, so pages are contiguous within one response; the registry changes rarely, but a later call can window an updated list.",
+  "type": "string"
+}
    • changedInput schema / properties / limit / description
      Previous value: -"Max stations to return (1-50)."New value: +"Max stations per page (1-50). totalFound still reports every station near the point, so pass the returned nextCursor as cursor to reach the rest."
    • addedOutput schema / properties / nextCursor
      Added value: +{
+  "description": "Opaque token for the next page of stations — pass it back as `cursor`. Omitted when this is the last page.",
+  "type": "string"
+}
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when no stations were found near the requested coordinates."New value: +"Guidance when no stations were found near the requested coordinates, when stations remain beyond this page, or when the supplied cursor points past the end of the list."
    • changedOutput schema / properties / totalCount / description
      Previous value: -"Number of stations returned (respects the limit parameter)"New value: +"Number of stations returned in this page"
    • changedOutput schema / properties / totalFound / description
      Previous value: -"Total observation stations available near this location before the limit was applied"New value: +"Total observation stations available near this location before the page limit was applied. Same value on every page of one query."
  7. Changed4 schema fields changed
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Guidance when no stations were found near the requested coordinates.",
+  "type": "string"
+}
    • addedOutput schema / properties / totalCount
      Added value: +{
+  "description": "Number of stations returned (respects the limit parameter)",
+  "type": "number"
+}
    • addedOutput schema / properties / totalFound
      Added value: +{
+  "description": "Total observation stations available near this location before the limit was applied",
+  "type": "number"
+}
    • changedOutput schema / required
      Previous value: -[
-  "stations"
-]New value: +[
+  "stations",
+  "totalFound",
+  "totalCount"
+]
  8. Changed5 schema fields changed
    • removedOutput schema / properties / stations / items / properties / distance
      Removed value: -{
-  "description": "Distance from query point in km",
-  "type": "number"
-}
    • addedOutput schema / properties / stations / items / properties / distanceKm
      Added value: +{
+  "description": "Distance from query point in kilometers",
+  "type": "number"
+}
    • removedOutput schema / properties / stations / items / properties / elevation
      Removed value: -{
-  "anyOf": [
-    {
-      "type": "number"
-    },
-    {
-      "type": "null"
-    }
-  ],
-  "description": "Elevation in meters"
-}
    • addedOutput schema / properties / stations / items / properties / elevationM
      Added value: +{
+  "anyOf": [
+    {
+      "type": "number"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "description": "Elevation in meters"
+}
    • changedOutput schema / properties / stations / items / required
      Previous value: -[
-  "stationId",
-  "name",
-  "distance",
-  "bearing",
-  "elevation",
-  "timeZone",
-  "county",
-  "forecastZone"
-]New value: +[
+  "stationId",
+  "name",
+  "distanceKm",
+  "bearing",
+  "elevationM",
+  "timeZone",
+  "county",
+  "forecastZone"
+]
  9. Changed1 schema field changed
    • addedOutput schema / properties / stations / items / description
      Added value: +"Observation station record with identity, location, and zone codes"
  10. First observed

TDQS

A4/5.0
Behavior3/5

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

readOnlyHint=true already tells the agent this is a safe read, so the burden is lower. The description contributes the ordering guarantee and the downstream purpose, and the schema carries the detailed pagination/stability disclosure. Nothing extra is added about rate limits or data freshness beyond what's in the schema, so a solid-but-not-rich 3.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short sentences, front-loaded with what it does, then the return shape, then the downstream use. There is no filler and no repetition of schema content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description needn't explain return fields, and it still names the proximity ordering and the follow-up tool. It is close to complete for a discovery tool; only the pagination caveat lives solely in the schema, which is acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the schema already explains limit, cursor windowing, requestedLimit/effectiveLimit, and coordinate bounds in more depth than the description does. The description only echoes the output-side effect of proximity sorting, not any parameter syntax. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Find weather observation stations near a location") and adds the result shape (sorted by proximity with distance and bearing). It explicitly ties itself to a sibling, nws_get_observations, so an agent can place it in the workflow without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear positive usage context: "Use to discover station IDs for nws_get_observations." That prerequisite relationship is genuinely helpful routing. It stops short of the top mark because no when-not condition or alternative discovery tool is named.

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

All nws-weather-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources