← Setup tutorial · Examples · Tools reference

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.

When the model should call it

The user has a location, address, or list/file of sites/assets/stores/warehouses.
The user wants to know which are at risk, when bad weather hits, or how severe.

Inputs

locations[]: Array of { label, latitude, longitude } or { label, zip }. 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. Defaults to all five.
hours: Optional. Forecast window, 1–168 hours. Defaults to 168 (7 days).

Output

For each location:

overall — worst band across all returned indices.
peaks[] — per-index { index, peak, at, band, blurb }. band is one of low / moderate / high / extreme, computed from the rounded 0–10 value (0–3 low, 4–6 moderate, 7–8 high, 9–10 extreme). blurb is the canonical WeatherOptics description for that integer value, served from /impact/blurbs.
error — present when this location specifically failed.

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

Reliability

One /impact/forecast/hourly call per location (fan-out), with retry+backoff on 429/5xx and concurrency capped at 4.
Lat/lon range-validated up front (catches swapped or malformed coordinates).
If any location fails, the tool result is marked isError: true so the failure can't masquerade as low-risk data.

Rules the model must follow

Use returned label, band, overall, and blurb values verbatim. Never re-derive severity from raw numbers; never reword blurbs.
If any location has an error, surface it as UNKNOWN — never treat missing data as low risk.

Indices returned

flood — flooding risk
road — driving / road-conditions risk
life_property — danger to life and property
disruption — business disruption (requires plan entitlement on the token)
power — power-outage risk

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 } or { label, zip }. 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–336). Defaults to 168 (7 days).

Output

For each location:

hourly[] — one row per hour, filtered to the requested variables. Each row carries time_iso, local_time_iso, and the numeric/boolean values.
daily[] — full daily summaries (temperature_high/low, total_precipitation, average_wind_speed, hours_with_rain/snow/sleet, max_relative_humidity, max_heat_index, etc.). Always returned; small enough to embed.
error — present when this specific location failed.

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 } or { label, zip }. label required, echoed verbatim.
index: One of flood, road, life_property, disruption, power. All 0–10 scale.
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 } or { label, zip }. 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.

`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 } — lat/lng only, no server-side geocoding. Chain find_coordinates_for_place for place names.
departure_time: ISO 8601 with timezone, or "now" (default). Must be within the last 24h or in the future.
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. 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, and official government weather alerts (US NWS + Canada + Mexico pass-through).

Inputs

location: { label, latitude, longitude } or { label, zip }.
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 or storm_reports 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_tile_map` Beta

Render a map image of a WeatherOptics tile layer (road, flood, wind, radar, wildfire, …) 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 } 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.

The returned image_url embeds the caller's token — treat it as sensitive.

`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

You only have a free-text place description and don't already have reliable coordinates.
Call this before get_impact_forecast, pick the best match, and pass {label, latitude, longitude} into the forecast tool.
If multiple matches look plausible, ask the user to confirm rather than guessing.

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 UserCity / "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

User asks about their places — "my Chicago locations", "my locations in Texas", or just "my locations".

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

User asks about their trucks/fleet — "my fleet", "my Dallas trucks", "vehicle V-103".

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.

Tools reference

get_impact_forecast Beta

When the model should call it

Inputs

Output

Reliability

Rules the model must follow

Indices returned

get_weather_forecast Beta

Inputs

Output

Backing service

get_impact_series Beta

Inputs

Output

get_weather_series Beta

Inputs

Output

get_rightroute_forecast Beta

Inputs

Output

get_severe_events_near Beta

Inputs

Output

get_tile_map Beta

Inputs

find_coordinates_for_place Beta

When the model should call it

Inputs

Output

Backing service

search_locations Beta

When the model should call it

Inputs

Output

Backing service

search_vehicles Beta

When the model should call it

Inputs

Output

Backing service

`get_impact_forecast` Beta

`get_weather_forecast` Beta

`get_impact_series` Beta

`get_weather_series` Beta

`get_rightroute_forecast` Beta

`get_severe_events_near` Beta

`get_tile_map` Beta

`find_coordinates_for_place` Beta

`search_locations` Beta

`search_vehicles` Beta