Skip to main content
Glama
Sign In

noaa-marine-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Get Monthly Means

noaa_marine_get_monthly_means
Read-onlyIdempotent

Verified monthly means for a CO-OPS water-level station, one row per station-month: the month's highest and lowest water, its tidal datums (MHHW, MHW, MSL, MTL, MLW, MLLW, DTL), tidal ranges (GT, MN, DHQ, DLQ), and lunitidal intervals (HWI, LWI) — the record a sea-level or tidal-range trend over years to decades is read from. Heights are relative to the requested datum in the requested units. A value CO-OPS publishes no figure for is omitted rather than reported as zero; a Great Lakes station carries only highest, msl, and lowest. A range may span up to 73,000 days, checked before the call, and CO-OPS verifies this product monthly, for the prior month, so a window ending on or after the first day of the prior month can fail with verified_data_lag. Each call returns up to limit months from offset; a range of at most limit months returns whole, and a longer one reports rows_matched, rows_returned, and next_offset, the offset that reaches the rest — raise limit to read a decades-long record in one call. Use noaa_marine_find_stations with types=["water_level"] first to resolve a station name or location to a station ID.

Input Schema

NameRequiredDescriptionDefault
datumNoDatum the monthly heights are referenced to. MLLW (default) is the US nautical chart datum; MHHW, MHW, MTL, MSL, and MLW are the other tidal planes. NAVD is NAVD88 and reads only where the station has an NAVD88 tie. STND is the station's own datum and reads any station. IGLD and LWD apply at Great Lakes stations only, which carry no tidal datum, and CRD at Columbia River stations only. A datum this station does not carry comes back as datum_unavailable, whose hint names a datum to retry with, and a station with no water-level gauge at all as no_gauge.MLLW
limitNoMonths to return on this page. Default 24; a larger value returns at most 1,000 and says so.
unitsNoUnit system for the heights: english = feet; metric = meters. The lunitidal intervals are hours either way.english
offsetNoMonth offset into the matched series, for reading a range longer than one page. 0 (default) starts at the first month; pass the next_offset from a previous call to continue. An offset past the last month returns an empty page rather than an error.
end_dateYesEnd date (inclusive), YYYYMMDD or YYYY-MM-DD, e.g. "20251231" or "2025-12-31". The month it falls in is the last month returned.
begin_dateYesStart date, YYYYMMDD or YYYY-MM-DD, e.g. "19750101" or "1975-01-01". The month it falls in is the first month returned.
station_idYesCO-OPS water-level station ID (numeric, e.g. "9447130" for Seattle). Obtain from noaa_marine_find_stations with types=["water_level"].

Output Schema

NameRequiredDescriptionDefault
datumNoDatum the heights are referenced to — echoed for correct interpretation.
errorNoPresent when the call failed. Absent on success.
unitsNoHeight units: "english" (feet) or "metric" (meters).
monthsNoOne row per station-month in the requested range, oldest first — the whole matched series when it holds at most limit months, otherwise the page of up to limit months starting at offset. rows_matched and next_offset report what a page left behind.
noticeNoThat limit was clamped to its cap, then what this page of the monthly series covers and how to reach the next page — whichever apply, composed into one string.
end_dateNoEnd of the requested range as sent to CO-OPS, YYYYMMDD.
truncatedNoTrue when this page stops short of the last matched month, so further months remain at next_offset. False on the final page and on a page past the end. Absent when the whole matched series was returned.
begin_dateNoStart of the requested range as sent to CO-OPS, YYYYMMDD.
station_idNoStation ID echoed from the request — for chaining.
next_offsetNoOffset to pass as offset on the next call, or null when this page reaches the last matched month. Absent when the whole matched series was returned.
page_offsetNoMonth offset this page starts at, echoed from the request. Absent when the whole matched series was returned.
rows_matchedNoMonths the requested range matched, before the page was cut. Absent when the whole matched series was returned.
station_nameNoStation name as returned by CO-OPS.
rows_returnedNoMonths this page carries — the length of months. Absent when the whole matched series was returned.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • changedInput schema / properties / datum / description
      Previous value: -"Datum the monthly heights are referenced to. MLLW (default) is the US nautical chart datum; MHHW, MHW, MTL, MSL, and MLW are the other tidal planes. NAVD is NAVD88 and reads only where the station has an NAVD88 tie. STND is the station's own datum and reads any station. IGLD and LWD apply at Great Lakes stations only, which carry no tidal datum, and CRD at Columbia River stations only. A datum this station does not carry comes back as datum_unavailable."New value: +"Datum the monthly heights are referenced to. MLLW (default) is the US nautical chart datum; MHHW, MHW, MTL, MSL, and MLW are the other tidal planes. NAVD is NAVD88 and reads only where the station has an NAVD88 tie. STND is the station's own datum and reads any station. IGLD and LWD apply at Great Lakes stations only, which carry no tidal datum, and CRD at Columbia River stations only. A datum this station does not carry comes back as datum_unavailable, whose hint names a datum to retry with, and a station with no water-level gauge at all as no_gauge."
    • addedInput schema / properties / limit / default
      Added value: +24
    • changedInput schema / properties / limit / description
      Previous value: -"Maximum months to return on this page, for a caller that wants fewer than the response budget allows. Omit for the largest page that fits; a value larger than the budget allows does not widen the page."New value: +"Months to return on this page. Default 24; a larger value returns at most 1,000 and says so."
    • removedInput schema / properties / limit / maximum
      Removed value: -9007199254740991
    • addedInput schema / properties / limit / multipleOf
      Added value: +1
    • changedInput schema / properties / limit / type
      Previous value: -"integer"New value: +"number"
    • changedInput schema / properties / offset / description
      Previous value: -"Month offset into the matched series, for reading a range whose months do not fit one response. 0 (default) starts at the first month; pass the next_offset from a previous call to continue. An offset past the last month returns an empty page rather than an error."New value: +"Month offset into the matched series, for reading a range longer than one page. 0 (default) starts at the first month; pass the next_offset from a previous call to continue. An offset past the last month returns an empty page rather than an error."
    • removedInput schema / properties / offset / maximum
      Removed value: -9007199254740991
    • addedInput schema / properties / offset / multipleOf
      Added value: +1
    • changedInput schema / properties / offset / type
      Previous value: -"integer"New value: +"number"
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: begin_date or end_date is not a real calendar date, or the range starts after it ends. `date_range_exceeded`: The requested range spans more than 73,000 days, the CO-OPS limit for monthly means. `station_not_found`: CO-OPS rejected the station ID as not a valid station. `datum_unavailable`: The station does not carry the requested datum — a Great Lakes station has no tidal datum, and IGLD and LWD apply at Great Lakes stations only. `verified_data_lag`: CO-OPS returned no months for a window ending on or after the first day of the prior month, which it may not have verified yet. `no_data`: CO-OPS returned no months for a window ending before the prior month — the station has no monthly means for it. `upstream_throttled`: CO-OPS answered the monthly-mean request with HTTP 403, which it returns for about two minutes while it throttles a burst of requests from one address. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: begin_date or end_date is not a real calendar date, or the range starts after it ends. `date_range_exceeded`: The requested range spans more than 73,000 days, the CO-OPS limit for monthly means. `station_not_found`: CO-OPS rejected the station ID as not a valid station. `datum_unavailable`: The station does not carry the requested datum — a Great Lakes station has no tidal datum, and IGLD and LWD apply at Great Lakes stations only. `no_gauge`: CO-OPS rejected the datum at a station that is in neither its active nor its historic water-level station list, so the station has never had a water-level gauge and publishes no monthly means at any datum. `verified_data_lag`: CO-OPS returned no months for a window ending on or after the first day of the prior month, which it may not have verified yet. `no_data`: CO-OPS returned no months for a window ending before the prior month — the station has no monthly means for it. `upstream_throttled`: CO-OPS answered the monthly-mean request with HTTP 403, which it returns for about two minutes while it throttles a burst of requests from one address. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "invalid_date_range",
-  "date_range_exceeded",
-  "station_not_found",
-  "datum_unavailable",
-  "verified_data_lag",
-  "no_data",
-  "upstream_throttled"
-]New value: +[
+  "invalid_date_range",
+  "date_range_exceeded",
+  "station_not_found",
+  "datum_unavailable",
+  "no_gauge",
+  "verified_data_lag",
+  "no_data",
+  "upstream_throttled"
+]
    • changedOutput schema / properties / months / description
      Previous value: -"One row per station-month in the requested range, oldest first — the whole matched series when it fits one response, otherwise the leading page starting at offset. rows_matched and next_offset report what a page left behind."New value: +"One row per station-month in the requested range, oldest first — the whole matched series when it holds at most limit months, otherwise the page of up to limit months starting at offset. rows_matched and next_offset report what a page left behind."
    • changedOutput schema / properties / notice / description
      Previous value: -"What this page of the monthly series covers and how to reach the next page."New value: +"That limit was clamped to its cap, then what this page of the monthly series covers and how to reach the next page — whichever apply, composed into one string."
  2. Changed1 schema field changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: begin_date/end_date is not a real calendar date or begin_date is after end_date. `date_range_exceeded`: The requested range spans more than 73,000 days, the CO-OPS limit for monthly means. `station_not_found`: CO-OPS rejected the station ID as not a valid station. `datum_unavailable`: The station does not carry the requested datum — a Great Lakes station has no tidal datum, and IGLD and LWD apply at Great Lakes stations only. `verified_data_lag`: CO-OPS returned no months for a window ending on or after the first day of the prior month, which it may not have verified yet. `no_data`: CO-OPS returned no months for a window ending before the prior month — the station has no monthly means for it. `upstream_throttled`: CO-OPS answered the monthly-mean request with HTTP 403, which it returns for about two minutes while it throttles a burst of requests from one address. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_date_range`: begin_date or end_date is not a real calendar date, or the range starts after it ends. `date_range_exceeded`: The requested range spans more than 73,000 days, the CO-OPS limit for monthly means. `station_not_found`: CO-OPS rejected the station ID as not a valid station. `datum_unavailable`: The station does not carry the requested datum — a Great Lakes station has no tidal datum, and IGLD and LWD apply at Great Lakes stations only. `verified_data_lag`: CO-OPS returned no months for a window ending on or after the first day of the prior month, which it may not have verified yet. `no_data`: CO-OPS returned no months for a window ending before the prior month — the station has no monthly means for it. `upstream_throttled`: CO-OPS answered the monthly-mean request with HTTP 403, which it returns for about two minutes while it throttles a burst of requests from one address. Other values are possible when a failure originates below the handler."
  3. Added

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover read-only/idempotent safety, and the description layers on genuinely non-obvious behavior: unpublished values are omitted rather than zeroed, Great Lakes stations carry only highest/msl/lowest, the span cap, the monthly verification lag with its error code, and how pagination and next_offset behave. This is far beyond what the structured fields convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded, with the core identity first and operational caveats after. The parenthetical lists of datums and intervals are long but earn their place by telling the agent what to expect in the output; a single unbroken paragraph is the only structural weakness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, annotations declaring safety, and 100% parameter coverage, the description fills the remaining gap: data-quality quirks, station-type variance, error codes, and pagination. An agent has everything needed to call this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents every parameter. The description still adds value by tying datum/units to the returned heights and explaining that raising limit lets a decades-long record come back in one call, which is a practical hint the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Verified monthly means for a CO-OPS water-level station') and enumerates exactly what a row contains: highs/lows, datums, ranges, lunitidal intervals. This is clearly distinct from the sibling tools that return raw water levels, tide predictions, or currents.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete before-call guidance: resolve the station with noaa_marine_find_stations and types=["water_level"], check the 73,000-day span limit, and watch for verified_data_lag on recent windows. It frames the use case (multi-decade trend reading) but never explicitly says when to prefer this over noaa_marine_get_water_level or noaa_marine_get_tide_predictions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All noaa-marine-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources