CommuteScout
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
CommuteScout: live, official US road data with routing, traffic, weather and history, nationwide.
For trips between any two US places use the trip tools:
plan_trip: the route, drive time for a departure (with traffic, typical, free-flow), and everything live on the line by mile (incidents, closures, chain controls, cameras, signs, tolls, speed and red-light cameras, road weather, wildfires) plus NWS alerts and the forecast on arrival.
best_time_to_go: when to leave or visit; up to 16 departures compared on drive time, weather and the route's incident history.
find_place: resolve an address when it is ambiguous. Around one place: get_nearby_events, get_weather, get_traffic, get_area_history. Coverage: get_coverage.
The user's places: pass "home", "work" or a saved place's name as any origin, destination or place; omit origin to start from Home (get_my_places lists them, when the server is connected with the user's CommuteScout API key). This server cannot see the user's device: for "from here" or "near me", pass coordinates or a city you already know from the conversation, or ask.
California has extra depth in check_route, check_region, get_incidents (CHP logs), get_lane_closures, get_chain_controls, get_wildfires, get_cameras, get_road_signs and rank_routes.
Lead with each tool's summary when it has one. Relay notes, stale
data_as_of times and source errors. Speak in the user's local time
(tools return local times). Never guess between far-apart places with
the same name: ask. Remind users to verify before driving (511 or the
state DOT site). Not affiliated with any government agency.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| check_routeA | Check current conditions along a major California highway corridor. The flagship trip-check tool: give it a start and end place and it returns everything active along that stretch right now - CHP incidents, lane closures physically in place, chain controls, and wildfires within ~10 miles - ordered by miles from the start, plus a summary. ALWAYS pass from_coords and to_coords ("lat,lon") when you know where the places are - for landmarks, small towns, or anything not a major city they are required for a good answer. Coordinates do two things: they let unlisted places resolve to the nearest corridor (e.g. "Alice's Restaurant" snaps to I-280 on the Peninsula), and they CLIP the route to the span actually being driven, so a trip to a mid-corridor destination doesn't report events beyond it. Corridors covered: I-80 Sacramento-Reno, US-50 to South Lake Tahoe, I-5, US-101, SR-17, SR-99, SR-1, I-15 to Vegas, Bay Area freeways, Tahoe-area routes. This is NOT a general router: if nothing matches (even with coordinates), the response lists the covered corridors; fall back to the filtered tools with center= for anything else. Freshness: CHP incidents refresh about once a minute; closures, chain controls, and fires are on a 5-minute cache. Current conditions only - this cannot forecast tomorrow's weather or closures. |
| check_regionA | Full current-conditions report for a California region. Use this for area-scale questions ("how is the Bay Area?", "what's happening in SoCal?") instead of stitching together point queries. It sweeps every source over the whole region at once: CHP incidents (severity-sorted, worst first), lane closures in place (full closures called out), chain controls, and wildfires inside the region. Regions: Bay Area, Sacramento metro, Tahoe/Sierra, Central Valley, Southern California, San Diego, Central Coast, North State. An unrecognized region name returns the list. Large regions are capped to the most severe items; the counts are always exact and the response says when a list was truncated. Freshness: CHP ~1/min fetched live, everything else 5-minute cache. |
| get_incidentsA | Live CHP traffic incidents statewide, optionally filtered. Data: the California Highway Patrol statewide computer-aided dispatch feed - collisions, traffic hazards, disabled vehicles, closures as CHP logs them. Refreshes about once a minute; incidents disappear when CHP closes the log. Fetched live on every call. Filters (combinable):
Limits: locations are free-text from dispatchers; a few incidents lack usable coordinates and are omitted. No history - current logs only. |
| get_lane_closuresA | Caltrans lane and road closures physically in place RIGHT NOW. Data: the Caltrans Lane Closure System (LCS). Only closures that crews have actually established (CHP code 1097) and not yet picked up are returned - scheduled-but-not-started closures are excluded, so this is "what is blocking lanes now", not a construction calendar. Refresh: 5-minute cache over per-district Caltrans feeds. Filters: route (e.g. "I-80", "US 101", "1"); district (Caltrans district 1-12, e.g. 3 = Sacramento/Tahoe, 4 = Bay Area, 7 = Los Angeles); center "lat,lon" with radius_km - closures whose begin or end point is inside the circle. For a town or place, center is the filter that catches work on EVERY road around it, including small state routes. Read closure_class on each record, it is what the closure means for through traffic:
|
| get_chain_controlsA | Current chain-control requirements on California mountain highways. Data: Caltrans chain-control status for fixed checkpoints on mountain routes (I-80 Donner, US-50 Echo Summit, SR-88, SR-89, and others). Levels: R-1 = chains OR snow tires required; R-2 = chains required except 4WD/AWD with snow tires on all four; R-3 = chains on ALL vehicles (rare, usually precedes closure). Refresh: 5-minute cache. Filters: route (e.g. "80", "US-50", "SR-88"); center "lat,lon" with radius_km for all checkpoints around a place (e.g. around Truckee), whatever highway they are on. Off-season (roughly May-October) there are usually no controls anywhere; the response says so explicitly rather than returning an empty list. Chain requirements can change hour to hour in storms - tell the user the data_as_of time and to carry chains anyway when snow is possible. |
| get_wildfiresA | Active California wildfires, flagged when close to a major highway. Data: the interagency WFIGS current-wildfire feed (NIFC) - name, size in acres, percent contained, discovery date. Points are each fire's ORIGIN, not its perimeter: a large fire can affect roads far from this point. Refresh: 5-minute cache; size/containment typically update once or twice a day. Small, fast-moving local fires may appear in CHP incident logs (get_incidents, type "FIRE-Report of Fire") before this feed has them. Filters:
This tool does NOT know about road closures caused by fires - cross-check get_incidents and get_lane_closures for the affected area. |
| rank_routesA | Which major corridors have the most going on right now. Answers broad questions like "what are the busiest routes", "where is traffic worst", or "which highways should I avoid today" across all 17 tracked corridors. by="activity" ranks on live events (full closures weigh most, then incidents, lane closures, chain controls); by="congestion" ranks on measured speed vs free-flow at each corridor's midpoint and needs the traffic feed to be configured - if it is not, the ranking silently falls back to activity. Each entry carries the counts and a one-line reason, so the answer can say WHY a corridor ranks where it does, not just list names. |
| get_camerasA | Live Caltrans roadside camera snapshots near a point or on a route. Data: ~3,000 in-service Caltrans cameras statewide. Every returned image_url was verified live moments ago (offline cameras that serve a placeholder frame are filtered out), so images can be shown directly. Snapshots refresh roughly every minute; stream_url (when present) is an HLS video stream. Filters: center "lat,lon" (required unless route is given) with radius_km; route (e.g. "I-80", "50") narrows to that highway. Results sort nearest-first when a center is given. Use a camera to let the user SEE conditions: fog on the pass, snow on the pavement, traffic density at an interchange. |
| get_road_signsA | What Caltrans changeable message signs are displaying right now. Data: statewide CMS sign text, blank and out-of-service signs already filtered - every record is a message a driver is physically seeing. Signs carry the road's operational truth ("CHAINS REQUIRED 10 MI AHEAD", "FULL CLOSURE HWY 96 DUE TO FIRE", "PREPARE TO STOP"), often before the event shows up in any other feed. Refresh: ~2-minute cache. Filters: route (e.g. "I-80") and/or center "lat,lon" with radius_km. Quote sign text verbatim to the user - it is the most current and most local signal this server has. |
| get_nearby_eventsA | Live road events near a point anywhere CommuteScout covers, not just California: 37 states today (get_coverage lists them). Data: the same multi-state feeds the live map shows, normalized - state DOT incidents, roadwork and closures, chain and traction advisories, and nationwide wildfires. Every event names its publishing agency in the source field. Coverage varies by state (some publish roadwork only; docs/state-coverage.md has the matrix); states added later appear here automatically. For CALIFORNIA questions prefer the dedicated tools above (richer detail: dispatch logs, lane counts, chain levels). Use THIS tool for any location outside California, near a state border, or as a supplement when a California tool comes back empty. center is "lat,lon"; or pass place (an address or place name) instead. kinds is a comma list from: incident, closure, chain, fire, sign, rwis, camera, toll (toll adds live and fixed toll prices where agencies publish them), enforcement (speed and red-light cameras from OpenStreetMap). radius_km caps at 160. |
| get_my_placesA | The user's saved places: Home, Work, favorites and recent destinations, synced from the CommuteScout site and apps. Available when this server is connected with the user's CommuteScout
API key; otherwise These belong to the user who connected: never repeat them to anyone else. |
| find_placeA | Look up a US address or place and get its coordinates. Use it to confirm which place the user means before planning, or
when a trip tool answers needs_clarification. Returns up to |
| plan_tripA | Everything about one drive between any two US places, in one call. Use this for "how's the drive to X", "how long to get to Y at 5", "anything on the way to Z". It returns:
Lead with |
| best_time_to_goA | When to leave (or visit) to beat traffic and weather, for any US trip. Answers "what's a good time to visit X", "when should I leave for the airport", "is 5 PM bad". It checks up to 16 departures across the window and returns, for each: drive minutes for that weekday and hour (TomTom historical traffic; live too within the hour), arrival time, the NWS forecast for the arrival hour with driving hazards flagged (snow, ice, fog, thunder), and how many incidents usually start on the route that hour (CommuteScout history since July 2026).
Pair with plan_trip for what is on the road right now. |
| get_weatherA | Hourly NWS forecast, active alerts and nearby road-weather stations for any US place, with driving hazards flagged by hour. Road-weather stations are state DOT sensors: pavement and air temperature, wind gusts and visibility, where a state publishes them. |
| get_trafficA | Live traffic speed against free-flow speed on the road nearest each point, anywhere in the US (TomTom). Use it for "is the bridge backed up right now"; for a whole drive, plan_trip is better. |
| get_area_historyA | What usually happens around a place: incidents and closures that started within the radius, by local hour and weekday, the common incident types and how long they typically last. Use it for "is this intersection bad at rush hour" or "when is it quietest around the stadium". These are counts CommuteScout saw in official feeds, not a crash database. |
| get_coverageA | Which states and sources CommuteScout covers right now, with each feed's freshness. Check it when an answer is unexpectedly empty. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| best_time | Find a good time to drive somewhere and what to expect on the way. |
| trip_check | Check a drive between any two US places. |
| road_trip_check | Check road conditions for a trip between two California places. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| coverage | States, sources and feed freshness. |
| about | What each tool is for and how fresh it is. |
TDQS
Scored across 18 tools
Several tools deliberately overlap on current road conditions: plan_trip, check_route, check_region, and get_nearby_events all return composites of incidents, closures, weather, and other feeds. The descriptions give useful scope rules (California vs outside, corridor vs region vs point), but the agent must parse lengthy guidance and could still misselect for border areas or mid-corridor destinations. The single-feed tools (cameras, chains, signs, wildfires, lane closures, incidents) are clearly distinct.
Nearly all tools use snake_case with a verb_noun shape (get_incidents, check_route, plan_trip, find_place, rank_routes). The main exception is best_time_to_go, which is a noun phrase rather than a verb-led name, and the get_/check_ split is semantically reasonable rather than chaotic. Overall the naming is predictable and readable.
Eighteen tools is slightly heavy but each maps to a distinct feed or capability: geocoding, saved places, trip planning, timing, traffic, history, coverage, weather, regional checks, corridor checks, cameras, chains, incidents, closures, signs, wildfires, and ranking. There is no obvious filler, though the surface is broad enough to feel large.
The surface covers the full car-commute lifecycle: finding and saving places, planning trips, choosing departure times, checking live traffic, incidents, closures, cameras, chain controls, signs, wildfires, weather, historical patterns, coverage, and route ranking. For a read-only commute-scouting server, there are no obvious dead ends in the core workflows.