NWS Weather — tool reference

Server URL: https://toolcargo.com/mcp/nws-weather · Scope: connector:nws-weather. Activate Site Audit free and use ToolCargo OAuth or a scoped API key. NWS needs no account or provider key. Each successful point lookup or forecast page uses one shared-plan call.

nws_point

{ "latitude": 38.8977, "longitude": -77.0365 }

Use explicit coordinates supplied for your task. Latitude is bounded to −90–90 and longitude to −180–180; both are rounded to four decimal places before public NWS lookup. This is US/NWS coverage, including supported territories, rather than worldwide weather. Uncovered locations can return an unavailable-source error.

Returns the exact requested point identity, grid office, gridX/gridY, issuing forecast office, timezone, nearby relative-location context and validated forecast pointers. Pointers are never followed. Some marine locations lack text forecasts, so unavailable pointers remain null. The nearby city and its distance are context rather than an exact location or observation. The grid office (office, source gridId) can differ from the issuing forecast office (forecastOfficeId, source cwa), including in Alaska. Use the grid office for forecast requests. Office and grid assignments can change; recheck this mapping periodically.

nws_grid_forecast

{ "office": "LWX", "gridX": 97, "gridY": 71, "units": "si", "limit": 5, "offset": 0 }

Pass the exact three-character office and grid integers returned by the point lookup. Grid coordinates are bounded to 0–1000. Request us or si units. Period forecasts usually describe day/night windows; use their explicit start/end times rather than assuming a fixed duration.

Returns source temperature and unit, wind speed text or structured quantity, direction, precipitation probability, summaries and bounded detail. Source numeric probabilities can differ from rounded narrative percentages: both remain source data. Null probability is unknown, not zero. Structured quantity units remain explicit and are not locally converted.

nws_hourly_forecast

{ "office": "LWX", "gridX": 97, "gridY": 71, "units": "us", "limit": 10, "offset": 0 }

Uses the same exact-grid inputs and exposes hourly periods, including dewpoint and humidity when supplied. This predicts weather over an approximately 2.5 km forecast grid cell. It is not measured weather at the coordinate. Missing fields and quantities remain null.

Paging and freshness

Both forecast tools expose at most ten periods per explicit local page, with offsets 0–200. Use nextOffset with unchanged office, grid, units and limit. Each call refetches one bounded forecast and slices locally; pages can change between calls and do not form a pinned snapshot. No automatic paging.

fetchedAt is ToolCargo retrieval time. generatedAt is source forecast generation; updateTime is the source data update. validTimes and each period’s start/end preserve source intervals and timezone offsets. Missing times remain null. updateAgeSeconds is a derived difference, not a freshness guarantee; a negative value indicates a future source timestamp or clock disagreement. Read exact period times before planning.

Forecast responses do not independently echo office/grid IDs. Their identity is the exact reconstructed API request; the point lookup independently checks requested point identity and canonical forecast pointers. Each narrative is limited to 2,000 characters, summaries to 300 and other text to 100–150, with explicit truncation.

Source boundaries

The official NWS public API states that its data is free for any purpose, subject to rate limits. Requests use fixed https://api.weather.gov JSON paths, an identifying ToolCargo application contact, shared provider pacing, a 15-second timeout and 2 MB response cap. No retries or followed redirects. NWS receives rounded coordinates, office/grid and unit parameters; ToolCargo account credentials are not forwarded.

This connector provides forecast research rather than observations, alerts or emergency monitoring. It does not guarantee conditions, completeness or freshness. No location detection, geocoding, files or arbitrary URL fetching. Source references: API guide and known issues · OpenAPI specification.