# Tools

> The thirteen MCP tools: stations, their readings, history and data quality, Snowpack Context, station weather, and ski resorts with their SNOTEL stations; arguments, limits, results, freshness and errors.

Each tool wraps the same domain function and cache the REST API uses, so a tool call and the equivalent API request return the same answer. `station_data_quality` has no single REST equivalent: it combines the latest conditions with the stored plausibility flags and known gaps. All thirteen tools are read-only, take no credentials, and return structured data.

## The tools

| Tool                   | Use it to                                                           |
| ---------------------- | ------------------------------------------------------------------- |
| `stations_search`      | Find stations by part of the name, state, network or active status. |
| `station_get`          | Read one station's metadata and the measurements it reports.        |
| `station_latest`       | Read the newest reading of each sensor, with a freshness verdict.   |
| `station_data_quality` | See whether a station's core readings can be trusted right now.     |
| `station_observations` | Read readings over a bounded date range.                            |
| `stations_nearest`     | Find the stations nearest a latitude and longitude.                 |
| `station_context`      | See how a station's snowpack compares with its history now.         |
| `station_climatology`  | Read a water year beside the station's historical band.             |
| `snow_rankings`        | Rank stations by recent gain, depth or anomaly.                     |
| `station_weather`      | Read the stored observed weather, NWS forecast and alerts nearby.   |
| `resorts_search`       | Find ski resorts by name, country, region or status.                |
| `resort_get`           | Read one ski resort's location, elevation and provenance.           |
| `resort_stations`      | See which SNOTEL stations relate to a resort, and why.              |

A station is always named by its triplet, such as `312:ID:SNTL`. Find one with `stations_search` or `stations_nearest`, then pass it to the others. A resort is named by its slug, such as `bogus-basin-mountain-recreation-area`; find one with `resorts_search`.

### stations_search

Inputs: `query` (part of the name), `state` (two letters), `network`, `active`, `limit` (1 to 50, default 20), `cursor` and `provider` (a data provider's code; default `nrcs`). Each station carries its `publicId` and `source`: who publishes its data and the credit line to use. Returns `data` (stations), `page.nextCursor` (pass it back as `cursor` for more) and `meta`.

### station_get

Input: `station`. Returns the station's name, location, elevation, `utcOffsetMinutes`, active status and period of record, and `elements`: each measurement with its duration, ordinal, unit and period of record.

### station_latest

Inputs: `station`, optional `elements` (up to 10 element codes, default snow water equivalent, snow depth, precipitation and air temperature) and `duration` (`DAILY` or `HOURLY`, default both). Each reading carries the observation time, `value`, `unit`, the source's `flag` and `qualityFlag`, `plausibilityFlags` (the checks the reading failed; see [quality](https://opensnotel.com/docs/data/quality.md#plausibility-flags)), `sourceUpdatedAt`, `newestObservedAt` and a `freshness` verdict:

- `fresh`: a recent period has a value. An unchanged or zero value is still fresh; no new snow is not stale data.
- `no_values`: periods keep arriving but the source reports no recent value.
- `stale`: no recent period has arrived, so the data is not reaching Snotel.

### station_data_quality

Input: `station`. Returns, for each core element (`WTEQ` snow water equivalent, `SNWD` snow depth, `PREC` accumulated precipitation and `TOBS` air temperature), the facts an agent needs before quoting it as current:

- `reportedDurations`: the durations the station's catalog lists the element at; empty when the station does not report it.
- `knownMissing`: known gaps for an element, each with the first station-local date (`from`), a `reason` and its `source`. `curated` gaps are listed by hand and open-ended, for an element the source can no longer serve for that station; `automatic` gaps are ones ingest recorded when the source answered the element with an error, bounded by `to` and naming their `duration`. Recent ones go once a scheduled read gets the element again; older ones stay until a backfill re-reads those dates.
- `sensors`: the newest reading with a value of each sensor, exactly as `station_latest` returns it, with its `freshness` verdict and `plausibilityFlags`.
- `recentFlagged`: for `DAILY` and `HOURLY`, how many readings in the recent window failed a [plausibility check](https://opensnotel.com/docs/data/quality.md#plausibility-flags) and which checks; `recentFlags` lists the newest ten, each with its value and flags.
- `reasons`: short sentences saying what is off (stale, no recent value, a flagged newest value, recent flags, a known gap, not reported). Empty when every sensor is fresh and nothing recent was flagged.

The recent window is the last 7 days for daily readings and the last 48 hours for hourly ones, measured from `meta.generatedAt`; `data.recentWindow` states both. Older flags are history: read them with `station_observations`. There is no score or single yes-or-no verdict; the tool reads only what is already stored and judged, and says what it found. A flag never changes a value, which is still what the source sent.

### station_observations

Inputs: `station`, `from` and `to` (station-local dates, `YYYY-MM-DD`, inclusive), optional `elements` and `duration` (`DAILY` by default; hourly is a separate series). Returns readings grouped by sensor. Each reading has `value` (null when the source reported none), the source's flags, `originalValue` and `originalQualityFlag` when the source edited or blanked it, `isProvisional`, `sourceUpdatedAt`, `revision` and `plausibilityFlags`, the checks a reading failed. A flagged value is a likely sensor fault; the value is still what the source sent.

### stations_nearest

Inputs: `lat`, `lng`, `limit` (1 to 25, default 5), `radiusKm` (up to 500) and `provider` (default `nrcs`). Returns stations nearest first with `distanceKm`, measured as the great-circle distance on a spherical Earth.

### station_context

Input: `station`. Returns the same answer as [`GET /api/v1/stations/{station}/context`](https://opensnotel.com/docs/api/snowpack.md#get-a-stations-current-snowpack-context): for snow water equivalent, snow depth, precipitation and air temperature, the newest observed reading, its 24 h and 72 h change, and, except air temperature, today's historical median, percent of median, historical percentile and rank against the station's WY1991–2020 values for the same day, plus any observed accumulation event. Each field is `current`, `stale` or `unavailable` with a `reason`; an unavailable value is never zero. Percent of median and percentile are different statements, and neither is an official NRCS percent of normal. A change in snow depth is not snowfall.

### station_climatology

Inputs: `station`, optional `element` (`WTEQ`, the default, `SNWD` or `PREC`), `waterYear` (named by the year it ends in; default the current one) and `previous` (`true` adds the previous water year). Returns every day of the water year with the observed value (null when none was reported) and the day's p10, median and p90 over WY1991–2020; a day with too few baseline years says `insufficient`. About 365 days come back, so summarize rather than repeat them.

### snow_rankings

Inputs: `kind` (required: `wteq_gain_24h`, `wteq_gain_72h`, `snwd_gain_24h`, `deepest_snowpack`, `highest_swe_percentile`, `largest_percent_of_median` or `strongest_active_event`), optional `state`, `network` (default `SNTL`), `bbox` (`minLon`, `minLat`, `maxLon`, `maxLat`) and `limit` (1 to 50, default 10). Returns ranked stations, each with its value, unit, freshness, the derivation behind it and an `explanation` in words. Only fresh values rank, so there may be fewer than `limit`, or none. There is no combined "best snow" score.

### station_weather

Input: `station`. Returns the same answer as [`GET /api/v1/stations/{station}/weather`](https://opensnotel.com/docs/api/weather.md), from stored data; a call never reaches the National Weather Service. `observed.primary` is the station's observed air temperature, from its own SNOTEL sensor when that is recent and otherwise from the best nearby NWS station; `observed.snotel` and `observed.nearby` list both sources as they are. `forecast` is the NWS forecast for the station's grid point (named periods and an hourly series), or null until the station is placed in the NWS grid. `alerts.items` are NWS alerts in effect, most severe first, quoted as issued. Every value carries a `kind`, `snotel_observation`, `nws_observation` or `nws_forecast`, and every part its own `freshness`. A forecast is not an observation; quote it as a forecast. NWS covers the US only.

### resorts_search

Inputs: `query` (part of the name), `country` (`US`, `CA` or `MX`), `region` (ISO 3166-2, such as `US-ID` or `CA-BC`), `status` (`operating`, `disused`, `abandoned`, `proposed`, `never_opened` or `unknown`), `limit` (1 to 50, default 20) and `cursor`. Returns the same answer as [`GET /api/v1/resorts`](https://opensnotel.com/docs/api/resorts.md#list-resorts): `data` (resorts, without their operating-area polygons), `page.nextCursor` and the registry's `license`.

### resort_get

Input: `resort` (a slug). Returns the same answer as [`GET /api/v1/resorts/{resort}`](https://opensnotel.com/docs/api/resorts.md#one-resort) without the operating-area polygon: location, region, status, website, the base and summit elevation and lift and run counts mapped in OpenStreetMap (null when nothing is mapped), upstream identifiers, which source supplied each field, and every upstream record. An old slug, or one of a resort merged into this one, still resolves, and `resolvedFrom` names the slug asked for with `reason` `renamed` or `merged`.

### resort_stations

Input: `resort` (a slug). Returns the same answer as [`GET /api/v1/resorts/{resort}/stations`](https://opensnotel.com/docs/api/resorts.md#stations-relevant-to-a-resort): the SNOTEL stations that relate to the resort, each with its `station` (triplet and name), `source`, `relationship`, `rank`, `distanceKm`, `elevationDifferenceM` and `rationale`. The `source` says which kind of statement it is:

- `curated`: reviewed. Its `relationship` (`representative`, `same_mountain`, `secondary` or `nearby`) and `rationale` say how the station relates to the resort.
- `candidate`: computed from distance alone, one of the five nearest reporting stations within 50 km, ranked by `rank`. Always `nearby`, with no rationale. The nearest station can be across a ridge or far lower than the resort, so call it the nearest station, never the resort's station.

Curated entries come first. Pass a `station.triplet` to `station_context` or `station_latest` for its snow.

## Provenance in every result

Every result has a `source` object naming the USDA NRCS SNOTEL service the values come from and how to read them: values are observed, not forecast or estimated; a null value is a missing reading and never zero; flags and units are the source's. Snowpack Context tools name Open SNOTEL's derivation instead, and `station_weather` names SNOTEL and the National Weather Service and says how to tell an observation from a forecast by `kind`. The resort tools name the resort registry and say how to tell a reviewed mapping from a computed one; their results also carry the registry's `license`, whose `attribution` the [Open Database License](https://opendatacommons.org/licenses/odbl/1-0/) asks you to show wherever resort data is shown. `meta.generatedAt` says when the answer was computed, which can be up to a minute before it was served for latest conditions.

## Limits

The tools enforce the same limits as the [REST API](https://opensnotel.com/docs/api/observations.md), and a few tighter ones so a result stays readable by a model:

- `station_observations` accepts at most 366 days of daily data or 31 days of hourly data, at most 10 elements, and returns at most 1,500 readings.
- `stations_search` and `resorts_search` return at most 50 a page, and `stations_nearest` at most 25.
- `snow_rankings` returns at most 50 stations, and its scope is always one network at most.

## Errors

A problem the caller can fix comes back as a tool error (`isError`) whose text is the same envelope the REST API uses, `{"error": {"code", "message", "details"}}`, with codes `invalid_parameter`, `station_not_found`, `resort_not_found`, `element_unavailable` and `range_too_large`. An argument outside a tool's schema is refused by the protocol before the tool runs. Anything unexpected comes back as `internal_error` with a generic message; no database or source text, credentials or stack traces reach the client. A client over the free rate limit gets HTTP `429` from the edge before the server answers, possibly without that envelope; wait as long as `Retry-After` says, then call more slowly (see [rate limits](https://opensnotel.com/docs/api/errors.md#rate-limits)).

## Next

- [Examples](https://opensnotel.com/docs/mcp/examples.md): Worked agent tasks over MCP: latest snow depth near a point, a week at three stations, the largest gains in snow water equivalent, how unusual today is, a water year against history, the SNOTEL stations for a ski resort, and freshness.
- [Provenance](https://opensnotel.com/docs/data/provenance.md): Which values are observed, derived, inferred or forecast, what to credit when you show Snotel data to users, and why a rise in snow depth is not snowfall.

Canonical page: https://opensnotel.com/docs/mcp/tools
