Recipe: Weather for any location

The task

You have a location — US or anywhere else — and need a forecast or current conditions. Picking the wrong pack for the location (or the wrong argument names within the right pack) is the most common failure here.

Tools used: the NWS forecast tool (namespaced nws_get_forecast on the gateway), get_alerts (US only), the Open-Meteo forecast tool (namespaced weather_get_forecast), and get_weather (global, via Open-Meteo) — see the argument-name and namespacing notes below for why the exact callable names matter here.

Copy-paste prompt

Get weather for "<location>" using Pipeworx. If it's a US location, use the nws tools for
the richer NWS forecast and check for active alerts; otherwise use the weather (Open-Meteo)
pack. Don't guess — if the location doesn't resolve, say so rather than picking a nearby
city.

What a good answer looks like

nws_get_forecast({ latitude: 37.7749, longitude: -122.4194 })

returns (live call, 2026-08-06 — trimmed):

{
  "location": { "latitude": 37.7749, "longitude": -122.4194, "city": "San Francisco", "state": "CA",
                 "timezone": "America/Los_Angeles", "grid": "MTR 85,105", "radar_station": "KMUX" },
  "period_count": 14,
  "periods": [
    { "name": "Today", "temperature": 72, "temperature_unit": "F", "wind": "6 to 13 mph W",
      "precip_chance_pct": 0, "short": "Sunny",
      "detailed": "Sunny. High near 72, with temperatures falling to around 68 in the afternoon..." }
  ]
}

A trustworthy answer has:

• location.city/state/grid/radar_station echoed back — confirms which NWS grid point your coordinates resolved to, not just that some forecast came back.
• named periods (“Today”, “Tonight”, “Friday”, …) with short + detailed prose, not a bare temperature — NWS forecasts are period-based, and the detail carries wind/precip context a single number doesn’t.

The argument name is the trap, not the coverage decision. nws_get_forecast requires the full words latitude/longitude — passing the shorter lat/lon (an easy habit from other weather APIs) fails cleanly rather than defaulting to something:

nws_get_forecast({ lat: 37.7749, lon: -122.4194 })
// → { error: "invalid_arguments", message: "nws_get_forecast received an invalid argument:
//     latitude, longitude are required but were not provided.", missing: ["latitude","longitude"] }

That’s an honest, loud failure — the actual plausible-sounding trap is routing the right argument names to the wrong pack:

nws_get_forecast({ latitude: 35.6762, longitude: 139.6503 })  // Tokyo
// → { error: "tool_error", message: "NWS: not found (HTTP 404). NWS only covers US locations.",
//     feedback_hint: "If Pipeworx should have this data, file pipeworx_feedback(...)" }

Also a clean error, not silent wrong data — but if you’re chaining calls without checking error, this reads exactly like a call that succeeded, just with an empty payload. Check for the error key before treating any weather response as usable.

Step-by-step tool calls

Decision tree

US location with severe weather

nws_get_forecast({ latitude: 37.7749, longitude: -122.4194 })
// → 14-period forecast with NWS detailed prose (shown above)

get_alerts({ state: "CA" })
// → { count: 50, alerts: [{ event: "Severe Thunderstorm Warning", severity: "Severe",
//     urgency: "Immediate", area: "Montgomery, MD; Loudoun, VA", ... }, ...] }

get_alerts is bare (no nws_ prefix) — it doesn’t collide with any other pack’s tool name, unlike get_forecast (see below).

Non-US location (Tokyo, London, anywhere)

weather_get_forecast({ location: "Tokyo" })
// → { location: "Tokyo", country: "Japan", latitude: 35.6895, longitude: 139.69171,
//     days: [{ date: "2026-08-06", high_f: 87.9, low_f: 75.9, precipitation_mm: 0,
//              conditions: "Overcast" }, ...] }

Bare get_forecast does not resolve to a single tool. Three packs export a tool named get_forecast (weather, airquality, nws), so the gateway exposes each with its pack prefix — the callable name is weather_get_forecast, not get_forecast.

Just current conditions

get_weather({ location: "Denver" })
// → { location: "Denver", country: "United States", temperature_f: ..., humidity_pct: ...,
//     conditions: "...", wind_mph: ... }

get_weather (unlike get_forecast) has no collision — the bare name works everywhere.

Auto-routing pattern

const isUS = lon > -125 && lon < -66 && lat > 24 && lat < 50  // CONUS bbox
// Add Alaska / Hawaii / territories ranges if you want full US coverage

const forecast = isUS
  ? await nws_get_forecast({ latitude: lat, longitude: lon })
  : await weather_get_forecast({ latitude: lat, longitude: lon })

Or skip the bbox check entirely and always use weather_get_forecast unless you specifically need NOAA’s US-specific alerts/products — Open-Meteo aggregates NOAA data for US points, so you don’t lose US accuracy by defaulting to it.

Citation pattern

Forecast for Tokyo (today) shows a high near 88°F with overcast conditions, per Open-Meteo aggregated from JMA. For US severe weather, follow NWS active alerts.

Caveats

• nws_get_forecast needs latitude/longitude spelled out — lat/lon fails with a clean invalid_arguments error rather than silently defaulting.
• get_forecast alone is ambiguous across weather, airquality, and nws — always call the namespaced form (weather_get_forecast for global) unless you’re on a connection scoped to just one of those packs.
• NOAA hits the gateway’s 5-min default cache. Forecasts update every few hours, so this is fine. For severe-weather alerts, prefer a fresh call rather than relying on a cached one.
• Open-Meteo timezone defaults to UTC in some fields. The response includes the location’s resolved timezone context where available — convert client-side when displaying to users.
• Forecast accuracy degrades after day 3. Day 7+ is directional signal, not a confident prediction. Don’t quote multi-day-out forecasts as facts.
• No global severe-weather alerts source in Pipeworx today. If you need typhoon/cyclone warnings outside the US, file via pipeworx_feedback — the same feedback_hint the tool itself returns on a non-US NWS call.