Give an agent the smallest surface that answers its task. In order of preference:
| If the agent | Give it |
|---|---|
| Is an MCP client | The MCP server: https://opensnotel.com/mcp |
| Can fetch URLs | The docs index: https://opensnotel.com/llms.txt |
| Needs one concept or endpoint | That page's Markdown: its address plus .md, such as https://opensnotel.com/docs/data/measurements.md |
| Must hold every page at once, offline | https://opensnotel.com/llms-full.txt, deliberately and not by default |
Paste this into an agent's instructions:
Use the official Snotel documentation and machine-readable interfaces at
https://opensnotel.com/llms.txt and https://opensnotel.com/mcp.
Verify measurement semantics, units, freshness and API details there before coding.
The interfaces
They are different forms of the same documentation and the same data, never separate sources:
- MCP (
/mcp): tools that search stations and read their latest conditions and history, and find ski resorts and the SNOTEL stations that relate to them, with provenance in every result. Use it when the agent should fetch data, not read about it. See connect and tools. /llms.txt: a short index of every docs page with what each one answers. Read it first, then fetch only the pages a task needs.- Page Markdown: every docs page at its address plus
.md, with no site chrome. Links inside it point at other pages' Markdown, so an agent that follows them stays in Markdown. Each ends with the pages to read next and the address of its HTML page. /sitemap.xml: every page's address, for crawling the hierarchy./llms-full.txt: every page concatenated, with what values mean before how to request them. It is much larger than any task needs; prefer the index and single pages.- OpenAPI (
/api/v1/openapi.json): the REST contract, for generating a typed client. See OpenAPI.
The HTML pages, their Markdown, llms.txt, llms-full.txt and the docs search are all built from the same Markdown sources, so they never disagree.
Rules that prevent wrong answers
Each rule is stated where it is owned; the link is the authority.
- Snow water equivalent (code
WTEQ) is the water the snowpack holds; snow depth (SNWD) is how deep it is. They are different measurements, and neither can be computed from the other. (measurements) - A rise in snow depth is not snowfall. Snotel measures no snowfall and never estimates it in stored data. (provenance)
PRECis precipitation accumulated since October 1, the start of the water year. It is neither snowfall nor a daily amount; subtract two readings to get the precipitation between them. (measurements)- A
nullvalue means the source reported nothing. It is never zero: a snow depth of0means bare ground, andnullmeans unknown. (measurements) - Observations are observed at the station. Anything else, such as an NWS forecast or an NWS observation from another station, is labeled with what it is and where it was measured. (provenance)
- Daily and hourly values are separate series. A daily value is not the average of that day's hourly values. (measurements)
observedAtis when the station measured, in UTC.sourceUpdatedAtis when the source last revised the value. Neither is the time Snotel stored it. (freshness)localDateis the station's calendar day at a fixed offset from UTC with no daylight saving, and that offset is a property of the station, not the state. (time and dates)- A recent value can still be revised by the source;
revisioncounts the changes. (quality) - The source's quality letters pass through unchanged, and
isProvisionalistrueonly for provisional values andfalseonly for reviewed ones. (quality) - Values keep the source's units, inches and degrees Fahrenheit for the core elements. Snotel converts nothing. (measurements)
freshness.statesays whether data is reaching Snotel, not whether the snow changed: an unchanged zero is stillfresh. (freshness)- Store a station as its triplet, such as
312:ID:SNTL, whole. The station number alone is not unique. (station IDs) - The nearest station is the closest one in a straight line, not the one that represents a place; it can be on another slope or at another elevation. (nearest stations)
- There is no bulk download of observation history. Read it in ranges of up to 366 days of daily or 31 days of hourly data. (observations)
Common tasks
The latest snow water equivalent at a station, over REST:
curl 'https://opensnotel.com/api/v1/stations/312:ID:SNTL/latest?elements=WTEQ'
and over MCP:
{
"tool": "station_latest",
"arguments": { "station": "312:ID:SNTL", "elements": ["WTEQ"] }
}
The stations nearest a latitude and longitude, over REST:
curl 'https://opensnotel.com/api/v1/stations/nearest?lat=44.31&lng=-115.2&limit=5'
and over MCP:
{
"tool": "stations_nearest",
"arguments": { "lat": 44.31, "lng": -115.2, "limit": 5 }
}
| To | Read |
|---|---|
| Read a season of history | Observations over a range |
| Compare today's snowpack with its history | Snowpack Context |
| Show the weather around a station | Weather |
| Look up a ski resort or download the registry | Resorts |
| Credit the source of the data to your users | Provenance |
| Handle an error | Errors |