The CommuteScout MCP server gives an AI assistant live road conditions — incidents, closures, chain controls, wildfires, cameras, signs, and tolls — plus route and region condition checks, mostly in California with nationwide nearby-event coverage.
check_route — everything active along a major CA corridor between two places (CHP incidents, lane closures, chain controls, wildfires within ~10 mi), ordered by mile from start, with a summary.
check_region — area-scale current-conditions sweep for a CA region (Bay Area, SoCal, Tahoe/Sierra, etc.), severity-sorted with exact counts.
get_incidents — live statewide CHP incidents, filterable by highway, CHP dispatch area, or a lat/lon radius.
get_lane_closures — Caltrans closures physically in place now, by route, district, or radius, each labeled with a closure class (full-roadway vs ramp vs lane, etc.).
get_chain_controls — current R-1/R-2/R-3 chain requirements at CA mountain checkpoints, by route or radius.
get_wildfires — active CA wildfires (WFIGS) with size and containment, filterable by proximity to a highway or place.
rank_routes — ranks the 17 tracked corridors by live activity or measured congestion, with a reason per entry.
get_cameras — verified-live Caltrans camera snapshots (and HLS streams) near a point or on a route, nearest-first.
get_road_signs — verbatim text currently displayed on Caltrans changeable message signs, by route or radius.
get_nearby_events — normalized incidents, closures, chain advisories, fires, signs, RWIS, cameras, and tolls near any point in the 37 covered states (use for non-CA or border locations).
All tools are read-only, current-conditions only (no forecasts or history), and responses carry per-source data_as_of timestamps.
Integrates optional TomTom traffic data feeds to provide live road conditions such as incidents and closures.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@CommuteScout What's the traffic like on I-5 between LA and Sacramento?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
CommuteScout reads 53 official agency feeds (CHP dispatch, state DOT closures and incidents, chain controls, cameras, message signs, wildfire perimeters, road weather, toll prices) and turns them into one live picture of the road. Look at the map, plan a route and see what is actually on it, or ask about a drive in plain English. The same data is served over MCP, so Claude and other AI assistants can use it as a tool instead of guessing about traffic.
A live national map: incidents by type, closures by class, chain controls, wildfires with real burn footprints, roadside weather stations, roughly 18,000 traffic cameras, and every message sign currently displaying something.
Toll and express-lane pricing: current rates on tolled corridors and bridges, drawn along the actual carriageway with hand-verified gantry positions, so a price tag never floats over the wrong road.
A route planner that knows the roads: autocomplete, route options, turn-by-turn directions, live conditions along the way, and print, GPX, KML, or share-link export.
An assistant that reads the feeds: plan a route, tap a suggested question, and the answer streams in from the same live data with per-source timestamps.
Plain-English incident detail: CHP dispatch logs are translated from radio shorthand into readable timelines, with each unit's arrival and clearance in order.
Watch areas: draw a circle, polygon, or route corridor and get a push or email alert when an incident, closure, chain control, or wildfire appears inside it.
An MCP server: ten tools over curated corridors and regions, with a closure taxonomy that keeps a closed on-ramp from reading as a closed highway.
Turn-by-turn navigation on your phone: native iOS and Android apps that speak what is ahead on the route, not just the next turn. Closures, crashes, chain controls and fires are announced by distance and filtered to your direction of travel, so a northbound ramp closure stays quiet when you are heading south. See commutescout-app.
Plugins, and a protocol for them: Flare is an open spec any source can implement to put its own alerts on the map. Plugins appear in a marketplace, are labelled by how far they have been vetted, and an unreviewed one can never close a road for a driver. A reference plugin and its conformance tests live in this repo.
A public API: the same ten tools over plain HTTP, with an OpenAPI document, one error envelope, and keys with published rate limits. Nothing to sign up for to try it.
Public evals: 91 golden questions on recorded fixtures, scored by an LLM judge that is never one of the evaluated models. The scorecard is a dated snapshot that names the version it reflects, not a release gate; it and its full history are committed to this repo.
Related MCP server: wsdot-mcp-server
The map covers 37 states. Coverage is not uniform, because it is built from what each agency actually publishes: some states offer every layer keylessly, some publish roadwork only, and a few offer nothing usable. The map says so directly, shading unsupported states and naming what is missing rather than showing an empty region.
California is the deepest. It is the only state with CHP dispatch logs, per-lane closure detail, chain-control levels, and CAL FIRE perimeters. The assistant and the MCP tools answer for every covered state, but a California question gets that richer detail, while elsewhere they answer from the normalized state DOT feeds.
Per-state matrix of what is live and why the gaps exist: docs/state-coverage.md. States not yet integrated, with the reason for each: docs/state-expansion-audit.md.
Open commutescout.com. Nothing to run, nothing to sign up for, feeds already warm. The phone apps are in commutescout-app.
Watch areas and the assistant are free on the hosted app; watch-area accounts need approval for now, because each one polls on your behalf.
Give Claude live road data with a custom connector:
https://mcp.commutescout.com/mcpSee it on the site: commutescout.com/mcp. Local stdio setup and the full tool reference: docs/mcp.md.
The code is MIT licensed and the repository is complete, so nothing stops you running a copy. It is worth being straight about what that takes: a Cloud Run deployment, credentials for a dozen state feeds, a Firestore database, map snapshot publishing, a scheduler for watch areas, and a paid map provider. Keeping that current is most of the work of the project, and it is not a path I recommend or support.
The MCP server alone is the reasonable exception, since it needs no accounts or keys:
{
"mcpServers": {
"commutescout": {
"command": "uvx",
"args": ["--from", "git+https://github.com/nicglazkov/commutescout", "ca-roads-mcp"]
}
}
}Read the code, lift what is useful, open an issue if something here is wrong. docs/deploy.md documents the deployment for the sake of the record rather than as a recipe to follow.
CHP incidents and dispatch logs; Caltrans and 30-plus other state DOT closures, incidents, cameras, message signs, and road weather; chain controls from California and the Pacific Northwest; WFIGS and CAL FIRE wildfires with perimeters; NWS alerts; USGS quakes; toll and express lane pricing; and optional TomTom and 511 SF Bay feeds.
Every response carries per-source data_as_of timestamps, and a failing
feed is never silent: the last good data is served, flagged stale, with
the error attached and surfaced all the way to the UI.
Full source table, refresh rates, and the closure taxonomy: docs/data-sources.md.
An eval suite scores the assistant against recorded fixtures: four scenarios (a Sierra storm day, a fire-closure day, a quiet day, and a byte-for-byte capture of a real fire-season day), 91 golden questions with ground truth including traps, and an LLM judge that is never an evaluated model.
Runs are triggered manually rather than on every release. Firing a full suite on each release turned out to cost more per month than the hosted assistant serves, so it now runs when a prompt or tool change actually warrants re-scoring. Every run appends to a committed history file, so the trend stays public: EVALS.md.
Three cleanly layered Python packages sharing one data spine: a feed layer with stale-while-revalidate caches and parsers that salvage complete records from truncated feeds, the MCP surface, and the web app.
The map does not boot through the API. A publisher builds the whole coverage area once per cycle and uploads pre-gzipped snapshots to object storage behind a CDN, so first paint is an edge-cached static file and no visitor request waits on a server assembling JSON. A map left open on a wall monitor keeps updating in place indefinitely.
Diagram and design notes: docs/architecture.md.
PRs welcome. The test suite is fixture-based and runs without network access. Start with CONTRIBUTING.md, and see adding a data source if you want to wire up a new feed.
CommuteScout is MIT licensed: the map, the planner, the MCP server, and every data parser, with no open-core carve-outs. The hosted app at commutescout.com will soon offer optional premium features (deeper history, more alerts); that is what funds the servers and keeps the free tier free.
Data comes from CHP, Caltrans and the other state DOTs listed in docs/state-coverage.md, plus WFIGS, CAL FIRE, NWS, and USGS. Not affiliated with any agency. Conditions change faster than any feed; verify before you drive (511 or your state DOT, and quickmap.dot.ca.gov in California).
Routing and place-name lookup come from Stadia Maps, which sees the coordinates involved. The base map is drawn from this project's own map files (built from the Protomaps OpenStreetMap build, served from maps.commutescout.com on Cloudflare R2) on the website and in the phone apps, so no third party sees where the map is being looked at; the Positron and Bright styles on the website load their tiles from OpenFreeMap instead, which sees the viewer's address and map area. Fonts and map libraries are served locally.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly and openWorld annotations, the description discloses important behaviors: sources are severity-sorted, lane closure types are called out, results are capped for large regions with exact counts, truncation is indicated in the response, and freshness ranges from live CHP to a 5-minute cache.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured, front-loaded with the core purpose, and every subsequent sentence adds distinct value: usage guidance, data categories, valid regions, truncation behavior, and freshness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description adequately conveys what the response contains, how items are sorted, and what limitations apply. An agent has enough information to decide when to call it and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description coverage for the region parameter, but the description fully compensates by listing the valid region names and explaining that an unrecognized region name returns the list of valid regions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Full current-conditions report for a California region.' It clearly distinguishes itself from point-query siblings by stating that it sweeps every source over the whole region at once, and it enumerates the categories it covers.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says to use this for area-scale questions like 'how is the Bay Area?' and contrasts it with 'instead of stitching together point queries.' This tells an agent when to prefer this tool and what alternative pattern it replaces.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| to_place | Yes | ||
| to_coords | No | ||
| from_place | Yes | ||
| from_coords | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the read-only safety profile is covered. The description adds genuinely useful behavioral context: the 1-minute refresh for CHIP incidents vs 5-minute cache for closures/chain controls/fires, the clipping behavior of coordinates to the driven span, and the limitation that it cannot forecast future conditions. It does not overclaim, and it explicitly disclaims forecast ability. Small deduction because it doesn't state the exact 'within ~10 miles' definition precisely or say what the summary contains, but the annotation coverage lowers the burden and it still adds solid value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every sentence earns its place: core purpose in the first sentence, the flagship positioning, concrete result content, a clear imperative about coordinates, covered corridors, an explicit non-goal, fallback instruction, and freshness. The most critical instruction (ALWAYS pass coordinates) is front-loaded immediately after the what-it-does. Structure is scannable with clear paragraphs. No filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, 0% schema coverage, no output schema, and 10 siblings, the description is remarkably complete: it covers what the tool returns, the geographic scope, coordinate behavior, freshness semantics, fallback behavior, and explicit exclusions. The agent has enough to decide when to pick it and how to call it correctly. The response shape is described at a sufficient level (list of incident types plus summary) even without an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% so the description must carry the meaning of each parameter, and it does: it explains that from_coords and to_coords are 'lat,lon' strings, optional but recommended, and describes exactly what they do (resolve unlisted places and CLIP the route span). It also clarifies the meaning of from_place and to_place by context ('start and end place'). This far exceeds the schema's bare string properties and fully compensates for the 0% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is explicit: 'Check current conditions along a major California highway corridor' and positions the tool as 'The flagship trip-check tool.' It names the resource (major CA highway corridors) and the verb (check current conditions) and specifies the kinds of results returned (CHP incidents, lane closures, chain controls, wildfires), distributed from a list of covered corridors. This clearly separates it from siblings like get_incidents, get_lane_closures, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance: 'ALWAYS pass from_coords and to_coords... when you know where the places are' and 'for landmarks, small towns, or anything not a major city they are required for a good answer.' It also says when NOT to use the tool: 'This is NOT a general router... fall back to the filtered tools with center= for anything else.' That is direct and actionable, and it names the sibling categories to use as fallback.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| route | No | ||
| center | No | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds valuable behavior: ~3,000 in-service cameras, offline cameras are filtered out, every returned image_url was verified live moments ago, snapshots refresh roughly every minute, stream_url is HLS, and results sort nearest-first when a center is given. This is rich, non-obvious context that helps an agent trust and use the results directly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Every sentence earns its place. Purpose is front-loaded, followed by data freshness, filtering, result ordering, and a concrete use case. There is no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description still covers output fields (image_url, stream_url), refresh behavior, offline filtering, filter semantics, and sort order. It provides enough for an agent to call the tool correctly and decide when it is appropriate, without needing to inspect the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It explains center as 'lat,lon', states it is required unless route is given, gives route examples ('I-80', '50'), and mentions radius_km. 'limit' is the one parameter not explicitly described, though its name and default make its purpose reasonably inferable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description opens with a specific resource: 'Live Caltrans roadside camera snapshots near a point or on a route.' It clearly differentiates from sibling tools like get_incidents, get_chain_controls, and get_road_signs by being explicitly about visual camera imagery, not status or incident data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear usage context: cameras are for letting the user SEE conditions such as fog, snow, or traffic density. It also explains filter semantics ('center required unless route is given', 'route narrows to that highway'). It does not explicitly name alternatives like check_route or get_incidents, but the use case is clear enough that an agent can route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | ||
| center | No | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true and openWorldHint=true, and the description adds substantial behavioral detail beyond that: 5-minute cache refresh, explicit off-season no-controls response instead of empty list, the meaning of each restriction level, and the caution that requirements change hour to hour. This fully informs the agent about expected behavior and edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is longer than average, but every section earns its place: source, levels, refresh, filters, off-season behavior, and safety caveat are each separated into digestible chunks. The primary purpose is front-loaded, and there is no redundant filler or repetition of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description still covers the essential invocation knowledge: data source, checkpoint routes, filter semantics, refresh cadence, off-season response, and the need to surface data_as_of time. An agent can select, call, and interpret the result correctly from this description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for explaining parameters. It does so with concrete examples: route accepts forms like '80', 'US-50', and 'SR-88'; center is a 'lat,lon' string; radius_km scopes checkpoints around a place such as Truckee. This adds meaning far beyond the bare schema property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource ('current chain-control requirements on California mountain highways') and a specific verb ('get'), then distinguishes its domain from sibling traffic tools like incidents, lane closures, wildfires, cameras, road signs, and events. It also defines the R-1/R-2/R-3 levels, making the tool's purpose concrete and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: it names the data source, the available filter modes (route vs. center+radius), and the off-season behavior. It advises on how to handle rapidly changing conditions, but it does not explicitly say when to use this tool instead of a sibling like check_route or get_incidents, so it stops short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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):
highway: a route like "I-80", "US 50", "17", "Hwy 99". Matches incidents whose location text mentions that route.
center: "lat,lon" with radius_km - incidents within that circle. THIS IS THE RIGHT FILTER FOR A TOWN OR PLACE NAME: use your knowledge of where the place is (e.g. Coyote, CA -> "37.22,-121.74") with radius_km 15-30. A circle catches every road around the place, not just one highway.
area: substring match on the CHP dispatch-area name. These are CHP communication-center names ("Hollister Gilroy", "East Sac", "Golden Gate"), NOT town names - do not pass a town here. There is no county filter because CHP's feed carries no county field; for a county, use center on the county seat with a radius covering the county.
Limits: locations are free-text from dispatchers; a few incidents lack usable coordinates and are omitted. No history - current logs only.
| Name | Required | Description | Default |
|---|---|---|---|
| area | No | ||
| center | No | ||
| highway | No | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description discloses live-fetch behavior, approximate refresh rate, incident disappearance when CHP closes logs, missing coordinates in some incidents, and no historical data. This gives agents an accurate model of volatility and data completeness.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into labeled sections, front-loaded with the core purpose, and every paragraph adds operational detail. It is long but dense with high-value guidance and contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by describing the feed content and limitations. For a 4-parameter, filterable live-data tool, it covers data source, filter behavior, freshness, missing-data caveats, and non-availability of history.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters, and it does. highway, center, radius_km, and area each receive concrete semantics, formatting examples, and usage caveats. It even provides a geographic example and radius recommendation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb and resource: 'Live CHP traffic incidents statewide, optionally filtered.' It clearly identifies the data source and scope, which differentiates it from sibling tools like get_cameras or get_road_signs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance, especially for filters: center is 'THE RIGHT FILTER FOR A TOWN OR PLACE NAME,' area is a CHP dispatch area 'NOT town names,' and county queries should use center. It also explains combinability and omits misinformation about a nonexistent county filter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
"full-roadway": the road itself is closed in that direction. The only class that means "you can't drive through".
"ramp": a ramp or connector is closed (even when the raw record says "Full", that means the ramp is fully closed, not the highway).
"one-way-traffic": alternating single lane with flagging; passable with delays. Common on two-lane mountain roads.
"alternating-lanes", "moving", "traffic-break": rolling or brief work; minor delays.
"lane": some lanes closed; the lanes field says how many of how many. estimated_delay_minutes is present when crews reported one. Shoulder-only work is excluded entirely.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | ||
| center | No | ||
| district | No | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite readOnlyHint and openWorldHint annotations, the description adds substantial behavioral detail: it cites the Caltrans LCS source, the 5-minute cache, the CHP 1097 inclusion rule, the meaning of each closure_class value, and that estimated_delay_minutes appears only when crews reported it. This goes well beyond the annotations and leaves little hidden behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but tightly organized with labeled sections and a bulleted closure_class breakdown. Every sentence provides decision-relevant information, and the 'RIGHT NOW' scope is front-loaded so the agent immediately understands the tool's core behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description takes on the burden of explaining return semantics, and it does so thoroughly: closure_class values, lanes field meaning, estimated_delay_minutes presence, and exclusions. An agent has enough to select filters, interpret results, and avoid misclassifying ramp closures as full-roadway closures.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates fully. It defines route with concrete examples, explains district values and regions, specifies center as 'lat,lon' with radius_km, and clarifies that center is the right way to capture work on all roads around a place. This adds meaning the bare schema entirely lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence says exactly what the tool does: returns 'Caltrans lane and road closures physically in place RIGHT NOW.' It names the resource, the scope (live closures, not a construction calendar), and explicitly distinguishes itself from scheduled-work data, so an agent can separate it from siblings like get_incidents or get_wildfires.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear when-to-use context: live closures only, with scheduled-but-not-started and shoulder-only work excluded. It also explains which filter is right for different situations, especially that 'center' catches work on every road around a town, and routes agents to read closure_class to interpret what each closure means.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Live road events near a point anywhere CommuteScout covers, not just California: 37 states today, growing.
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". 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). radius_km caps at 160.
| Name | Required | Description | Default |
|---|---|---|---|
| kinds | No | incident,closure,chain,fire | |
| center | Yes | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, so the description correctly extends them rather than repeating. It adds meaningful behavioral detail: data is normalized from multi-state feeds, coverage varies by state with a docs reference, later states appear automatically, and every event names its publishing agency in the source field. It does not mention pagination, rate limits, or the full event response shape, but the supplied annotations lower the burden; this is a strong, non-contradictory supplement.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is organized into clear paragraphs: scope, data details, California vs. nationwide usage, then parameter definitions. Every sentence carries useful information, though it is somewhat longer than strictly necessary. The front-loaded purpose and explicit usage guidance make it easy to scan; minor verbosity prevents a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero schema description coverage, the description covers all necessary invocation details: geographic scope, data types, state coverage variability with a doc pointer, parameter formats and limits, and sibling differentiation. It does not describe the response event structure beyond the 'source' field, which is a minor gap, but the tool's purpose and invocation are fully specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description fully compensates by explaining each parameter: 'center is "lat,lon"', '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)', and 'radius_km caps at 160.' It also clarifies the default behavior implicitly and gives valid values, which the schema alone does not provide.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Live road events near a point anywhere CommuteScout covers' – a specific verb, resource, and geographic scope. It explicitly differentiates from California-centric siblings by stating 'For CALIFORNIA questions prefer the dedicated tools above' and positions this tool for outside California, near borders, or as a supplement. An agent can immediately distinguish it from sibling tools like get_incidents or get_lane_closures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use/when-not-to-use guidance: 'prefer the dedicated tools above' for California, and 'Use THIS tool for any location outside California, near a state border, or as a supplement when a California tool comes back empty.' It even names the alternative tool category and the condition for falling back, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| route | No | ||
| center | No | ||
| radius_km | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint and openWorldHint, but the description adds substantial behavioral detail: blank and out-of-service signs are filtered, so every record is a physically visible message; there is a ~2-minute cache; and signs often lead other feeds in timeliness. These details go beyond the annotations and enrich the agent's mental model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tight and well-ordered: purpose, data characteristics, filters, and a directive on quoting. Each sentence earns its place, and the most actionable instruction ('Quote sign text verbatim') is near the end but still prominent. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional params, no output schema), the description covers all necessary aspects: what data is returned (sign text), how it is filtered (blank/out-of-service removed), how fresh it is (~2-min cache), how to filter (route/center/radius), and what to do with the output (quote verbatim). An agent can invoke it correctly without ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description carries the full burden for parameters. It explicitly defines the route format ('I-80') and center format ('lat,lon'), and explains radius_km as a radius. It also clarifies that route and center are alternative filters ('and/or'). This fully compensates for the empty schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a precise verb and resource: 'What Caltrans changeable message signs are displaying right now.' It clearly distinguishes this tool from siblings by focusing on CMS sign text, not incidents or closures, and even notes that signs often precede other feeds. The purpose is unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context on when to use this tool: it provides the most current and local signal, and instructs to quote sign text verbatim. It also explains filtering by route or center/radius. However, it does not explicitly name alternative tools for other data types (e.g., incidents) or state when not to use it, so it stops short of a full exclusionary guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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:
near_route (e.g. "I-5", "101") - only fires within ~10 miles of that highway's corridor line.
center "lat,lon" with radius_km - fires around a place, regardless of
highway.
Without either, every active CA fire is returned, each carrying a
near_highways list of major corridors within ~10 miles (empty = not
near a covered major highway; it may still affect local roads).
This tool does NOT know about road closures caused by fires - cross-check get_incidents and get_lane_closures for the affected area.
| Name | Required | Description | Default |
|---|---|---|---|
| center | No | ||
| radius_km | No | ||
| near_route | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint and openWorldHint, and the description substantially expands on both: it discloses the 5-minute cache, the once-or-twice-daily update cadence for size/containment, that points are ORIGIN not perimeter, and that small fires may appear in CHP logs first. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is long but every section earns its place: data-source context, the origin-not-perimeter caveat, filter semantics, and the cross-check warning. It is organized with clear headers and front-loads the tool's core purpose before details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Even without an output schema, the description covers key return fields (name, size in acres, percent contained, discovery date, near_highways list) and explains the empty-list case. It also covers the main limitation (no road-closure awareness) and refresh behavior, making it complete for an agent deciding how and when to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries full responsibility for parameter meaning, and it delivers: near_route is explained with examples ('I-5', '101') and a ~10-mile corridor threshold; center 'lat,lon' with radius_km is explained; and the no-filter default behavior is explicitly described.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Active California wildfires, flagged when close to a major highway,' naming a specific verb, resource, and scope. It also distinguishes itself from siblings by specifying the WFIGS/NIFC data source and noting it is not about road closures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit selection guidance: use the near_route or center+radius_km filters for targeted queries, and notes when to prefer get_incidents for small fast-moving fires. It also explicitly says to cross-check get_incidents and get_lane_closures for road closures, which this tool does NOT cover.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| by | No | activity | |
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes well beyond the readOnlyHint annotation by explaining ranking weights, the difference between activity and congestion modes, and the critical silent fallback to activity when the traffic feed is not configured. This is exactly the kind of behavioral nuance an agent needs to interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is moderately long but well-structured and front-loaded with the core question it answers. Each sentence adds information about ranking behavior, fallback handling, or result contents, with little wasted wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema, the description usefully notes that each entry carries counts and a one-line reason. It covers purpose, ranking modes, fallback behavior, and result shape. The only notable omission is the meaning of 'limit,' which is minor but still a gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must carry parameter meaning. It thoroughly explains the 'by' parameter and its two modes, but it never describes 'limit' beyond the schema's default value, leaving the agent to infer that it caps the number of returned corridors.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ranks major corridors by current activity or congestion, answering broad questions like 'what are the busiest routes' and 'which highways should I avoid today.' It distinguishes itself from the sibling get_* and check_* tools by operating across all 17 tracked corridors rather than returning raw lists or checking a specific route.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit usage context with example questions and explains why someone would call this tool instead of a more specific one. It does not name alternative tools or state when not to use it, so it falls just short of full exclusionary guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.82.1check_regioncheck_routeget_camerasget_chain_controlsget_incidentsget_lane_closuresget_nearby_eventsget_road_signsget_wildfiresrank_routesScored across 10 tools
Each tool targets a distinct data source or scope: corridor summaries, regional summaries, incidents, closures, chain controls, wildfires, ranking, cameras, signs, and multi-state events. Even where overlap exists (e.g., check_route vs check_region), the descriptions clearly separate corridor-level from area-level use.
All names follow a verb_noun pattern, which is predictable and readable. The only minor inconsistency is the use of 'check_' for two aggregate tools while most others use 'get_', plus 'rank_routes' as the sole ranking verb.
Ten tools is well-scoped for a traffic and road-conditions domain. Each tool covers a meaningful slice of the surface—incidents, closures, chains, fires, cameras, signs, route summaries, regional summaries, ranking, and multi-state coverage—without redundancy.
The tool set covers the full current-conditions lifecycle for driving: incidents, lane closures, chain controls, wildfires, live cameras, message signs, corridor/region rollups, and a worst-route ranking. Multi-state coverage is provided as a fallback, and expected gaps like forecasting are explicitly out of scope.
WA highway conditions, ferry schedules, vessel locations, toll rates, and border waits via MCP.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
MCP observability. Query live traffic, errors, duration, and alerts from your AI agent.
511 SF Bay Transit MCP — live departures, vehicle positions and service