Tools reference

Tools exposed by the WeatherOptics MCP server, their inputs, what they return, and how the model is expected to use them.


get_impact_forecast Beta

Assess weather risk for one or many places over the next 7 days. The primary tool. Returns the peak WeatherOptics index per location and when each peak occurs, with canonical band + verbatim blurb per index. Also answers "is there wildfire spread risk at/near X?" — a 0–10 wildfire_spread score at the point (opt-in index, with the active fire's name).

When the model should call it

Inputs

locations[]
Array of { label, latitude, longitude }, { label, zip }, or { label, place } — place is a free-text name/address resolved server-side via WeatherOptics geocoding (the match is echoed in resolved_place). label is required — use the asset name/ID from the user's data, echoed back verbatim; never fabricated.
indices
Optional. Comma-separated subset of flood, road, life_property, disruption, power, wildfire_spread. Defaults to the five standard indices; wildfire_spread is opt-in (e.g. "is there wildfire spread risk at X?" → wildfire_spread).
hours
Optional. Forecast window, 1–168 hours. Defaults to 168 (7 days).

Output

For each location:

Top-level: requested / succeeded / failed counts plus a top-level warning string when any location errored.

Reliability

Rules the model must follow

Indices returned

Note: indices on different scales (e.g. temp_seasonality_score anomaly score, speed_reduction fraction) are deliberately excluded — mixing scales produced misleading severity bands during prototyping.

get_weather_forecast Beta

Raw WeatherOptics weather variables (temperature, precipitation, wind, humidity, heat index, etc.) at one or many locations over the next 7 days. For plain non-risk questions like "will it rain in Chicago Thursday?" or "how hot next week?". For weather-risk questions (road, flood, power outage), use get_impact_forecast instead.

Inputs

locations[]
Array of { label, latitude, longitude }, { label, zip }, or { label, place } (free-text name resolved server-side, echoed in resolved_place). label is required and echoed back verbatim.
variables
Optional subset of hourly variables. Default: temperature, heat_index, wind_speed, wind_gust, total_precipitation, rainfall_rate, snowfall_rate, relative_humidity.
hours
Max hourly rows per location (1–168). Defaults to 168 (7 days).

Output

For each location:

Top-level: requested / succeeded / failed plus a warning string when anything failed. isError: true on any failure.

Backing service

Calls GET /weather/forecast on the WeatherOptics api-server. Requires the Standard Weather API permission on the token.

get_impact_series Beta

Return a rendered time-series chart (as a QuickChart image URL) showing a WeatherOptics impact index at a single location over the forecast window. The chat client embeds the returned chart_url as an image inline; the raw points come along so the model can narrate specific peaks without re-fetching.

Inputs

location
Single { label, latitude, longitude }, { label, zip }, or { label, place } (resolved server-side, echoed in resolved_place). label required, echoed verbatim.
index
One of flood, road, life_property, disruption, power, wildfire_spread. All 0–10 scale. wildfire_spread comes from /impact/wildfire (144-hour horizon; wildfire permission) — a series of zeros means no active fire's spread reaches the point.
hours
Forecast window (6–168). Defaults to 168 (7 days).
granularity
hourly (default) returns one point per hour. daily collapses to one point per local calendar day keeping the peak — cleaner for a 5–7 day view.

Output

{ label, series, granularity, chart_url, peak: { value, at }, points: [{ time_iso, local_time_iso, value }, ...] }

Response also carries a second text content block with a markdown image link (![](chart_url)) — Claude renders it inline; ChatGPT ignores it and charts points natively.

Y-axis is pinned to 0–10 so severity context is consistent across charts. Legend hidden (title carries the label).

get_weather_series Beta

Return a rendered time-series chart (as a QuickChart image URL) showing a raw WeatherOptics weather variable at a single location over the forecast window. Same idea as the impact chart, but for plain values (temperature, precipitation, wind, humidity, etc.).

Inputs

location
Single { label, latitude, longitude }, { label, zip }, or { label, place } (resolved server-side, echoed in resolved_place). label required, echoed verbatim.
variable
One of temperature, heat_index, wind_speed, wind_gust, total_precipitation, rainfall_rate, snowfall_rate, rain_accumulation, snow_accumulation, relative_humidity, visibility.
hours
Forecast window (6–168). Defaults to 168 (7 days).
granularity
hourly (default) returns one point per hour. daily collapses to one point per local calendar day keeping the peak — cleaner for a 5–7 day view.

Output

{ label, series, granularity, chart_url, peak: { value, at }, points: [{ time_iso, local_time_iso, value }, ...] }

Response also carries a second text content block with a markdown image link (![](chart_url)) — Claude renders it inline; ChatGPT ignores it and charts points natively.

Y-axis auto-fits to the data range; axis label includes units.

aggregate_weather_data Beta

One statistic — max, min, avg, sum, or count — computed server-side over the hourly forecast at one or many locations, for either a weather variable or a 0–10 impact index, with an optional conditional filter. Answers "how much rain at the Chicago yard over the next 48h?", "peak road risk across my terminals this week?", or "how many hours below freezing with precipitation at Denver?" without the model reading 168-row series and doing arithmetic by eye.

Inputs

locations[]
Same shape as get_weather_forecast: { label, latitude, longitude }, { label, zip }, or { label, place } (resolved server-side, echoed in resolved_place). label is required, echoed verbatim.
field
Any hourly weather variable (temperature, wind_gust, total_precipitation, snow_flag, …) or impact index (road, flood, life_property, disruption, power, wildfire_spread). Rates are per-hour inches; *_accumulation fields are documented as "WeatherOptics adjusted … accumulation (in)"; flags are 1/0.
operator
max / min return the value plus the local hour it occurs. sum is meaningful for per-hour rates and flags; on other fields it still returns the arithmetic sum but with a warning. count = hours where field is non-zero / flag true and the filter holds (filter on field itself → simply the hours matching the filter).
hours
Forecast window from now, 1–168. Defaults to 168 (7 days).
filter_field / filter_operator / filter_value
Optional, all three together. Restricts the statistic to hours where the filter field (same as field or any other, weather or impact) is lt / lte / gt / gte / eq the value, in that field's units. Mixing families (weather field, impact filter) is fine — each family is fetched once and joined on the hour.

Output

Per location:

Top-level summary — the cross-location roll-up: max/min name the location_label (and at) holding the value; sum and count total across locations; avg pools every qualifying hour. Plus requested / succeeded / failed and a warning string; isError: true whenever any location failed.

Backing service

Reuses the chart tools' series path: GET /weather/forecast for weather variables and GET /impact/forecast/hourly for indices and GET /impact/wildfire for wildfire_spread (one call per location per family, concurrency capped at 4, retry on 429/5xx). Requires the weather, ratings, or wildfire permission — whichever the chosen field needs. Forecast window only; past periods are covered by get_daily_historical.

get_rightroute_forecast Beta

Weather-adjusted route forecast via the RightRoute API: travel time, arrival window, expected slowdown percentage, plus per-route weather / impact / temperature narratives and wildfire impact (when the token has the wildfire permission; degrades gracefully with a warning otherwise).

Inputs

origin / destination
{ label, latitude, longitude } or { label, place } — a free-text place name is resolved server-side via WeatherOptics geocoding and echoed in the point's resolved_place. Unresolvable names fail loudly (no silent fallback).
departure_time
ISO 8601 with timezone, or "now" (default). Past times are supported: departures more than 24h ago automatically use the historical reconstruction (mode: "historical"): contiguous US, departures from 2007-01-01, less granular weather data than forecast routes, new data every 24 hours. Wildfire risk, government weather alerts and power outage risk are not included there; the result's note says so.
waypoints / vehicle_type
Optional stops in order; car (default) or truck.
include_route_polyline
Opt-in (default false). Adds route_polyline to the result: the true route geometry downsampled to ≤200 points with per-point worst-hazard values — made to be passed straight into get_tile_map to render the route, hazard-colored, over a weather layer. Request it only when the user wants a map/visual of the route.

Output

hazard_callouts[] lifts elevated risk indices along the route (wildfire spread/conditions, flood, road, …) to the top level with canonical blurbs — a 0% slowdown does not mean no weather risk; an active wildfire near the route appears only here. overall_hazard_level is the canonical severity of the whole trip (computed server-side from the worst callout); official_guidance (moderate+ only) names official sources to also consult; and presentation_guidance carries per-result reporting notes for these fields. The full RightRoute response is under raw.

get_severe_events_near Beta

Severe weather near a location: SevereCast (next-hour hail / tornado / damaging-wind cells, CONUS-only), storms + cyclones (hurricanes, winter storms, days out), live lightning, active US wildfire incidents, and official government weather alerts (US NWS + Canada + Mexico pass-through). Incidents and alerts only — it has no 0–10 spread score; "is there wildfire spread risk at X?" is get_impact_forecast with indices wildfire_spread. It covers one location per call; for every active hurricane or tropical disturbance worldwide, use get_active_cyclones.

Inputs

location
{ label, latitude, longitude } or { label, place } (resolved server-side; zip is not accepted by the events feed).
radius_miles
Optional. With a radius, events intersecting the surrounding box are returned; without, only events covering the exact point.
event_types
Defaults to severe_cast, storms, cyclones, nws_alerts. Add lightning, storm_reports, or us_wildfires (active US wildfire incidents) explicitly.

Output

Events normalized to { source, event_type, severity, headline, starts_at, ends_at, distance_miles, properties }, sorted closest-first, capped at the 50 closest (with a loud warning listing the total). Requires the events and weather_alerts permissions for full coverage.

get_live_road_status Beta

Live road status: what is being reported on the roads right now, around a location or along a route: closures, road surface status (dry, wet/slush, black ice, snowy, low visibility, severe driving conditions, closed, crosswind danger), traffic incidents, truck warnings and weather events, e.g. "is I-80 closed in Wyoming?" or "any closures on my route?". Source: the WeatherOptics Live Road Status API (state and provincial 511 / DOT reports, collected about once an hour); each report carries the source's own update time. For forecast slowdowns on a drive, use get_rightroute_forecast.

Inputs

location or route_polyline
One of: { label, latitude, longitude } / { label, place }, or the route_polyline from get_rightroute_forecast (with include_route_polyline: true).
radius_miles
Search radius around a location (default 25), or corridor half-width along a route (default 5).
types
Defaults to road_closure, road_status, traffic_incident, trucker_warning, weather_event. Add road_work, traffic_congestion or special_event explicitly.

Output

items[] with type, roadway, surface condition or category, description, state, timing, last_updated, distance_miles and (on a route) miles_along_route; nearest first, or in route order. Dry/normal surface reports are counted (surface_conditions, normal_surface_roadways) rather than listed; at most 50 items, with a warning when more matched. coverage_gaps names states in the area whose sources don't provide a requested type. Traffic cameras and road weather stations are not returned. US coverage; Canadian reports need a separate permission. Requires the road_conditions permission.

get_hourly_historical Beta

Hourly historical weather and/or 0–10 impact indices at one location for up to 7 local days, e.g. "when did it rain hardest on Tuesday?". Coverage per the API docs: North America and Europe from 2022-05-04, elsewhere from 2022-12-02; new data typically arrives within 6 hours, so the latest hours may be missing (data_ends_at). Power is the Power Outage Index V2.

Inputs

location
{ label, latitude, longitude } or { label, place }.
start_date / end_date
YYYY-MM-DD local calendar days at the location, inclusive, at most 7 days.
variables / indices
Hourly weather variables (default: temperature, wind_speed, wind_gust, total_precipitation, rainfall_rate, snowfall_rate) and impact indices (road, flood, disruption, life_property, power; default none).

Output

rows[]: one per hour with time_iso, local_time_iso and the requested values. Exactly one WeatherOptics request per data type (upstream_calls). Requires weather_historical and/or ratings_historical.

get_daily_historical Beta

Day-by-day historical summaries at one location for up to 366 local days, e.g. "how much rain did Seattle get last month?". Weather days use the same fields and the same computation as the daily summaries in get_weather_forecast; impact indices give each day's peak. Same coverage as get_hourly_historical.

Inputs

location, start_date / end_date
As for get_hourly_historical, at most 366 days.
fields / indices
Daily weather fields (default: temperature_high, temperature_low, total_precipitation, total_rain_precipitation, total_snow_precipitation, max_wind_gust) and impact indices (default none).

Output

days[] (one per local day; hours_available on partial days), summary (window extremes with dates, sums of daily totals, index peaks), missing_dates for dates with no data, and upstream_calls: long windows are fetched as several one-week requests (a full year is about 53 per data type). Requires weather_historical and/or ratings_historical.

get_active_cyclones Beta

Every active tropical cyclone (hurricanes, typhoons, tropical storms) and tropical disturbance worldwide, for broad questions with no specific place: "any hurricane activity?", "anything brewing in the Gulf?". Sources: NHC (Atlantic, Eastern and Central Pacific) and JTWC (Western Pacific and other basins), via the WeatherOptics cyclone feed.

Inputs

None.

Output

storms[]: one row per storm with name, basin, source, current position, wind, gust and category, peak_forecast, the full official track[], and track_ends_at (the forecast horizon). disturbances[]: one row per area that may develop, with the 48-hour and 7-day formation chance (percent and level), position, and the forecaster's outlook text. Model guidance tracks are not included. Requires the events permission.

get_tile_map Beta

Render a map image of a WeatherOptics tile layer (road, flood, wind, radar, …) or the polygon-only wildfire layer over a location, region, or route. Composited server-side (Google basemap + WO overlay) by the tile server; in MCP Apps-capable clients (ChatGPT developer mode) the map renders inline in the chat.

Inputs

location + radius_miles
{ label, latitude, longitude } or { label, place } (resolved server-side) with a 1–500 mi radius (default 40).
bbox
Named { west, south, east, north } for state/CONUS-scale views.
route_polyline
The array from get_rightroute_forecast(include_route_polyline: true), passed unchanged: auto-frames the map and draws the route hazard-colored (canonical band colors) with origin/destination markers. Colors reflect conditions at the time the driver reaches each point. Route maps show basemap + route only — no weather tile layer (layer / animate are ignored), since a fixed-hour layer under a multi-hour drive misrepresents timing.
animate
Forecast layers animate the next 96h. radar is observed data and loops the past 30 minutes; there is no future radar layer.
layer: wildfire
Polygons, not tiles — there is no wildfire raster (both the wildfire_spread and wildfire_conditions tilesets are deprecated and are never requested). Basemap + active fire boundaries (NIFC perimeters: name, acres, percent contained, updated time) + the current wildfire-spread polygons (the v2 product, one ring per 0–10 spread level around each fire), from one GET /events/current?event_types=us_wildfires,us_wildfire_spreads call for the map's bbox. The polygons are widget-only: they travel in the tool result's _meta (_meta.overlays, one GeoJSON FeatureCollection at full NIFC fidelity, coordinates rounded to 5 dp; each feature's kind is boundary or spread, and each keeps the feed's canonical fill / fill-opacity / stroke, which the widget draws from — the same props the portal renders; _meta.overlay_palette.wildfire_spread is the canonical 0–10 palette from /impact/blurbs for the legend). MCP Apps hosts forward _meta to the map iframe but keep it out of the model's context, so a 360 KB perimeter never enters the conversation. What the model sees is fires — one row per fire with name, acres, percent_contained, updated_iso and max_spread_index (the highest 0–10 ring present) — plus the names in note. At most 30 polygons per kind (highest spread index / largest fires kept) with a warning when truncated; the layer is always interactive (the widget auto-frames the view to the fire polygons; the requested radius/bbox is the framing only when there are none), and there is no static image (no static fallback). Requires the wildfire_tiles permission (the feed's gate). For the per-point 0–10 score use get_impact_forecast with wildfire_spread.
interactive
Pan/zoom map with a layer picker and time bar. The per-layer tile specs (URLs embedding the caller's token) are widget-only, in _meta.interactive_layers; the model sees only available_layers (layer names). A layer whose tile host is not allowed by the widget's CSP is dropped from the picker with a warning rather than drawing blank.
Every map URL (the static preview image_url and the interactive tile URLs) embeds the caller's token, so none of them are model-visible: they travel only in the tool result's _meta to the map widget.

find_coordinates_for_place Beta

Look up candidate coordinates for a place name, address, city, or landmark (e.g. "Richmond, VA" or "1600 Pennsylvania Ave"). Wraps the existing WeatherOptics geocoding service.

Temporary token requirement: geocoding is portal-scoped upstream, so for now the plugin needs a portal token for this tool (until per-capability API permissions land).

When the model should call it

Inputs

query
The place name, address, city, or landmark to look up.

Output

{
  "query": "Richmond, VA",
  "matches": [
    { "name": "Richmond, VA, USA", "latitude": 37.5407, "longitude": -77.4360 }
  ]
}

Backing service

Calls POST /geocoding/location_suggestions on the WeatherOptics api-server (the same endpoint the business portal uses for address autocomplete). Same per-request token auth as the rest of the MCP. No third-party provider configuration needed.

Token caveat. This endpoint currently requires a portal-scoped token, not the long-lived API token. A portal token works, but it expires when you sign out of the business portal — the tool will start returning auth errors at that point and you'll need to paste a fresh portal token. Pending an api-server change to accept the API token via alternate_permission.

search_locations Beta

Search the user's saved locations in WeatherOptics (their "locations" list — the same set that powers the portal). Each record carries lat/lon ready to feed into get_impact_forecast.

Temporary token requirement: same portal-token requirement as the geocoder until the api-server change lands.

When the model should call it

Inputs

query
Optional case-insensitive substring filter on the record name. Omit to list the most recently created.
limit
Max records to return (1–50). Defaults to 25.

Output

{
  "query": "Chicago",
  "count": 1,
  "records": [
    { "id": 42, "name": "Chicago Depot", "latitude": 41.88, "longitude": -87.63,
      "group_ids": [3, 7] }
  ]
}

Backing service

Calls GET /cities.json on the WeatherOptics api-server. Pagination via limit; results filtered server-side when query is set.

search_vehicles Beta

Search the user's vehicles / fleet assets in WeatherOptics. Each record carries the vehicle's current lat/lon ready to feed into get_impact_forecast.

The vehicles endpoint accepts the RightRoute API token as well as a portal token; geocoding / locations still require portal until the api-server alternate_permission change lands.

When the model should call it

Inputs

query
Optional. Server-side filter on the vehicle's external_id. Omit to list the most recently created vehicles.
limit
Max records to return (1–50). Defaults to 25.

Output

{
  "query": "V-103",
  "count": 1,
  "records": [
    { "id": 18, "name": "Truck 103", "external_id": "V-103",
      "latitude": 32.78, "longitude": -96.79, "group_ids": [9] }
  ]
}

Backing service

Calls GET /vehicles.json on the WeatherOptics api-server.

search_routes Beta

Search the user's saved routes and recurring lanes in WeatherOptics (the routes list that powers RightRoute in the portal). Each record carries origin/destination labels + coordinates and the scheduled departure_time — everything a follow-up get_rightroute_forecast call needs.

Requires the "Saved routes" (routes:read) permission on the connection; without it the tool returns the standard in-band permission-denied message rather than an empty list.

When the model should call it

Inputs

query
Optional case-insensitive filter matched against route name, origin/destination labels, and external_id. Omit to list the most recently created routes.
limit
Max routes to return (1–50). Defaults to 25.

Output

{
  "query": "memphis",
  "count": 1,
  "routes": [
    { "id": 9021, "name": "Dallas → Memphis",
      "origin": { "label": "Dallas Yard", "latitude": 32.78, "longitude": -96.79 },
      "destination": { "label": "Memphis DC", "latitude": 35.15, "longitude": -90.05 },
      "departure_time": "2026-09-02T13:00:00.000Z",
      "status": "unstarted", "vehicle_id": 18, "vehicle_type": "truck",
      "recurring_cron": "0 8 * * 1", "group_ids": [4] }
  ]
}

A warning field is set when the result may be incomplete — more routes matched than limit allows, or the search did not cover every saved route (see below).

Backing service

Calls GET /routes.json on the WeatherOptics api-server with exclude=latest_rightroute_response, so the heavy RightRoute response blobs never leave the server — this tool returns route identity and schedule only. The search text is passed as the routes index's query param (api-server #398), which matches name, origin/destination labels and external ID across all of the caller's routes; a warning flags when more routes matched than the limit returned.