Tools Reference

All tools are registered on the mcnoaa-tides MCP server and available through any MCP-compatible client. Parameters with defaults are optional.

Tip

Date parameters accept yyyyMMdd or yyyyMMdd HH:mm format. The maximum time range is 720 hours (~30 days).

Tool Annotations

Every tool declares MCP tool annotations so clients can make informed decisions about retries, caching, and approval:

Annotation	Value	Meaning
readOnlyHint	true (all tools)	Tools never write or modify data — safe to retry
openWorldHint	true (13 tools)	Fetches data from NOAA’s external API
openWorldHint	false (diagnostics)	test_client_capabilities only inspects the MCP session

Structured Logging

Tools send diagnostic messages to the client via MCP notifications/message:

• ctx.info() before data fetches (e.g., “Fetching hilo predictions for station 8454000”)
• ctx.warning() for data quality issues (preliminary/unverified readings), unavailable products, and NO-GO/CAUTION deployment assessments
• ctx.debug() for search result counts and phase classification details

These messages appear in the client’s log stream, not in the tool return value.

Sampling Summaries

Three tools — marine_conditions_snapshot, deployment_briefing, and water_level_anomaly — attempt to generate a natural-language "summary" key via MCP sampling. If the connected client supports sampling, the server asks its LLM to synthesize a concise briefing from the raw data. If sampling is unavailable, the raw data is returned without a summary — the feature is purely additive.

---

Station Discovery

Tools for locating NOAA CO-OPS tide stations by name, geography, or ID.

search_stations discovery

Search the station catalog (~301 stations) by name, state, or tidal flag. Returns up to 50 matches.

Parameter	Type	Default	Description
query	str	""	Case-insensitive substring match against station name or ID
state	str	""	Two-letter state abbreviation (e.g. "RI", "WA")
is_tidal	bool | None	None	Filter by tidal capability. None returns all stations

Example call:

{
  "tool": "search_stations",
  "arguments": {
    "state": "WA",
    "is_tidal": true
  }
}

Example response:

[
  {
    "id": "9447130",
    "name": "Seattle",
    "state": "WA",
    "lat": 47.6026,
    "lng": -122.3393,
    "tidal": true,
    "greatlakes": false,
    "shefcode": "SEWW1"
  },
  {
    "id": "9449424",
    "name": "Cherry Point",
    "state": "WA",
    "lat": 48.8633,
    "lng": -122.7583,
    "tidal": true,
    "greatlakes": false,
    "shefcode": "CHYW1"
  }
]

---

find_nearest_stations discovery

Find the closest NOAA stations to a GPS coordinate. Distances are in nautical miles.

Parameter	Type	Default	Description
latitude	float	required	Decimal degrees latitude
longitude	float	required	Decimal degrees longitude
limit	int	5	Maximum number of stations to return (minimum 1)
max_distance_nm	float	100	Search radius in nautical miles (must be positive)

Example call:

{
  "tool": "find_nearest_stations",
  "arguments": {
    "latitude": 41.49,
    "longitude": -71.32,
    "limit": 3
  }
}

Example response:

[
  {
    "id": "8452660",
    "name": "Newport",
    "state": "RI",
    "lat": 41.5043,
    "lng": -71.3261,
    "tidal": true,
    "greatlakes": false,
    "shefcode": "NWPR1",
    "distance_nm": 0.9
  },
  {
    "id": "8454000",
    "name": "Providence",
    "state": "RI",
    "lat": 41.8071,
    "lng": -71.4012,
    "tidal": true,
    "greatlakes": false,
    "shefcode": "PRVR1",
    "distance_nm": 19.4
  }
]

---

get_station_info discovery

Retrieve expanded metadata for a single station, including available sensors, datum offsets, supported products, and disclaimers.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID (e.g. "8454000")

Example call:

{
  "tool": "get_station_info",
  "arguments": {
    "station_id": "8454000"
  }
}

Example response (abbreviated):

{
  "id": "8454000",
  "name": "Providence",
  "state": "RI",
  "lat": 41.8071,
  "lng": -71.4012,
  "sensors": [
    {"name": "Water Level", "status": "active"},
    {"name": "Air Temperature", "status": "active"},
    {"name": "Wind", "status": "active"},
    {"name": "Barometric Pressure", "status": "active"}
  ],
  "datums": [
    {"name": "MLLW", "value": 0.0},
    {"name": "MSL", "value": 2.235},
    {"name": "NAVD", "value": 2.159}
  ],
  "products": {
    "predictions": true,
    "water_level": true,
    "air_temperature": true,
    "wind": true,
    "air_pressure": true,
    "water_temperature": false
  }
}

Caution

Not all stations support all products. Always call get_station_info first to verify which sensors and products are available before requesting observations.

---

Tides

Tools for tide predictions and observed water levels.

get_tide_predictions tides

Retrieve tide predictions for a station. Defaults to high/low (hilo) predictions for the next 48 hours — the most useful interval for trip planning.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
begin_date	str	""	Start date (yyyyMMdd or yyyyMMdd HH:mm)
end_date	str	""	End date
hours	int	48	Duration from now (ignored if both dates are set)
interval	str	"hilo"	Prediction interval: "hilo", "h" (hourly), or "6" (6-minute)
datum	str	"MLLW"	Vertical datum reference. See Datum Options

Example call:

{
  "tool": "get_tide_predictions",
  "arguments": {
    "station_id": "8454000",
    "hours": 24,
    "interval": "hilo"
  }
}

Example response:

{
  "predictions": [
    {"t": "2026-02-22 03:18", "v": "0.287", "type": "L"},
    {"t": "2026-02-22 09:42", "v": "4.521", "type": "H"},
    {"t": "2026-02-22 15:54", "v": "0.143", "type": "L"},
    {"t": "2026-02-22 22:06", "v": "4.893", "type": "H"}
  ]
}

The type field is only present with the "hilo" interval. "H" indicates high tide, "L" indicates low tide.

---

get_observed_water_levels tides

Retrieve actual observed water level readings from a station. Returns 6-minute interval observations by default.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
begin_date	str	""	Start date
end_date	str	""	End date
hours	int	24	Duration from now
datum	str	"MLLW"	Vertical datum reference

Example call:

{
  "tool": "get_observed_water_levels",
  "arguments": {
    "station_id": "8454000",
    "hours": 6
  }
}

Example response (truncated):

{
  "data": [
    {"t": "2026-02-22 12:00", "v": "2.145", "s": "0.003", "f": "0,0,0,0", "q": "p"},
    {"t": "2026-02-22 12:06", "v": "2.098", "s": "0.004", "f": "0,0,0,0", "q": "p"},
    {"t": "2026-02-22 12:12", "v": "2.051", "s": "0.003", "f": "0,0,0,0", "q": "p"}
  ]
}

Compare observed levels against predictions to see how actual conditions differ from forecast. The q field indicates data quality: "p" for preliminary, "v" for verified.

---

Weather

Meteorological observations from NOAA station sensors.

get_meteorological_data weather

Retrieve a single meteorological product from a station. Not all stations support all products — use get_station_info to check available sensors first.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
product	Literal	required	One of the products listed below
begin_date	str	""	Start date
end_date	str	""	End date
hours	int	24	Duration from now

Available products:

Product	Response fields	Units
air_temperature	t, v, f	degrees Fahrenheit
water_temperature	t, v, f	degrees Fahrenheit
wind	t, s, d, dr, g, f	speed/gust in knots, direction in degrees
air_pressure	t, v, f	millibars
conductivity	t, v, f	mS/cm
visibility	t, v, f	nautical miles
humidity	t, v, f	percent
salinity	t, v, f	PSU

Temperature

{
  "tool": "get_meteorological_data",
  "arguments": {
    "station_id": "8454000",
    "product": "air_temperature",
    "hours": 6
  }
}

{
  "data": [
    {"t": "2026-02-22 12:00", "v": "38.5", "f": "0,0,0"},
    {"t": "2026-02-22 12:06", "v": "38.7", "f": "0,0,0"}
  ]
}

Wind

{
  "tool": "get_meteorological_data",
  "arguments": {
    "station_id": "8454000",
    "product": "wind",
    "hours": 6
  }
}

{
  "data": [
    {
      "t": "2026-02-22 12:00",
      "s": "8.75",
      "d": "225.00",
      "dr": "SW",
      "g": "12.40",
      "f": "0,0"
    }
  ]
}

---

Planning

Composite tools that aggregate multiple data sources for marine decision-making.

marine_conditions_snapshot planning

Fetch tide predictions, observed water levels, and meteorological data in a single call. Fires 6 parallel API requests and gracefully handles products that are unavailable at a station.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
hours	int	24	Duration for all data products

Products fetched: predictions (hilo), water_level, water_temperature, air_temperature, wind, air_pressure

Example call:

{
  "tool": "marine_conditions_snapshot",
  "arguments": {
    "station_id": "8454000"
  }
}

Example response (abbreviated):

{
  "station_id": "8454000",
  "fetched_utc": "2026-02-22T14:30:00.000000+00:00",
  "predictions": {
    "predictions": [
      {"t": "2026-02-22 09:42", "v": "4.521", "type": "H"},
      {"t": "2026-02-22 15:54", "v": "0.143", "type": "L"}
    ]
  },
  "water_level": {
    "data": [
      {"t": "2026-02-22 14:24", "v": "1.203", "s": "0.003", "f": "0,0,0,0", "q": "p"}
    ]
  },
  "wind": {
    "data": [
      {"t": "2026-02-22 14:24", "s": "12.50", "d": "180.00", "dr": "S", "g": "18.20", "f": "0,0"}
    ]
  },
  "unavailable": {
    "water_temperature": "ValueError: No data for station '8454000' product 'water_temperature'."
  }
}

Products that fail or lack sensor support appear under the "unavailable" key rather than causing the entire request to fail.

---

SmartPot

Tidal intelligence tools designed for autonomous crab pot deployments. These bridge NOAA tide data with field operations: phase awareness, deployment assessment, catch enrichment, and anomaly detection.

tidal_phase smartpot

Classify the current tidal phase at a station or GPS location. Returns one of four phases: ebb, flood, slack_high, or slack_low.

Parameter	Type	Default	Description
station_id	str	""	7-digit NOAA station ID
latitude	float | None	None	Decimal degrees latitude
longitude	float | None	None	Decimal degrees longitude

Tip

Provide either station_id OR both latitude and longitude. GPS coordinates automatically resolve to the nearest tidal station.

Example call:

{
  "tool": "tidal_phase",
  "arguments": {
    "latitude": 47.6,
    "longitude": -122.34
  }
}

Example response:

{
  "station": {
    "id": "9447130",
    "name": "Seattle",
    "lat": 47.6026,
    "lng": -122.3393
  },
  "station_distance_nm": 0.2,
  "timestamp_utc": "2026-02-22T14:30:00+00:00",
  "phase": "flood",
  "description": "Tide is rising (flood) -- water moving shoreward",
  "previous": {
    "type": "low",
    "time": "2026-02-22 08:15",
    "level_ft": -1.23
  },
  "next": {
    "type": "high",
    "time": "2026-02-22 14:48",
    "level_ft": 10.87
  },
  "minutes_since_previous": 375,
  "minutes_to_next": 18,
  "progress_pct": 95.4,
  "latest_observed": {
    "time": "2026-02-22 14:24",
    "level_ft": 10.52
  }
}

Slack window is defined as 30 minutes around a high or low event. The progress_pct field indicates how far through the current phase the tide has progressed (0 = just started, 100 = reaching next event).

---

deployment_briefing smartpot

GO/CAUTION/NO-GO assessment for crab pot deployment. Finds the nearest station, fetches tide predictions covering the soak window, and evaluates current conditions.

Parameter	Type	Default	Description
latitude	float	required	Deployment latitude
longitude	float	required	Deployment longitude
soak_hours	int	48	Planned soak duration in hours

Assessment thresholds:

Condition	GO	CAUTION	NO-GO
Wind sustained	< 15 kn	15-20 kn	> 20 kn
Wind gust	< 25 kn	25-30 kn	> 30 kn
Water temp	—	—	< 40 F (cold-water advisory)
Pressure trend	stable	—	dropping > 3 mb/3hr (weather advisory)

Example call:

{
  "tool": "deployment_briefing",
  "arguments": {
    "latitude": 47.6,
    "longitude": -122.34,
    "soak_hours": 72
  }
}

Example response (abbreviated):

{
  "station": {
    "id": "9447130",
    "name": "Seattle",
    "lat": 47.6026,
    "lng": -122.3393
  },
  "station_distance_nm": 0.2,
  "timestamp_utc": "2026-02-22T14:30:00+00:00",
  "soak_window": {
    "begin_utc": "20260222 14:30",
    "end_utc": "20260225 14:30",
    "hours": 72,
    "tidal_cycles": 6
  },
  "tide_schedule": [
    {"type": "high", "time_utc": "2026-02-22 14:48", "level_ft": 10.87},
    {"type": "low", "time_utc": "2026-02-22 21:12", "level_ft": 3.45}
  ],
  "conditions": {
    "wind": {
      "speed_kn": 12.5,
      "gust_kn": 18.2,
      "direction": "S"
    },
    "water_temperature_f": 46.3,
    "air_pressure_mb": 1013.2
  },
  "assessment": "GO",
  "advisories": []
}

---

catch_tidal_context smartpot

Batch-enrich catch events with tidal phase data. Groups events by nearest station and fetches hilo predictions once per station for the entire time window.

Parameter	Type	Default	Description
events	list[dict]	required	Array of catch event objects (max 100)

Required fields per event:

Field	Type	Description
timestamp	str	ISO-8601 or "YYYY-MM-DD HH:MM" (UTC)
latitude	float	GPS latitude of the pot
longitude	float	GPS longitude of the pot

Extra fields (catch_count, species, weight, pot_id, bait_type, etc.) are passed through unchanged.

Example call:

{
  "tool": "catch_tidal_context",
  "arguments": {
    "events": [
      {
        "timestamp": "2026-02-20T08:30:00Z",
        "latitude": 47.6,
        "longitude": -122.34,
        "catch_count": 12,
        "species": "dungeness"
      },
      {
        "timestamp": "2026-02-20T14:15:00Z",
        "latitude": 47.6,
        "longitude": -122.34,
        "catch_count": 7,
        "species": "dungeness"
      }
    ]
  }
}

Example response:

[
  {
    "timestamp": "2026-02-20T08:30:00Z",
    "latitude": 47.6,
    "longitude": -122.34,
    "catch_count": 12,
    "species": "dungeness",
    "tidal": {
      "station_id": "9447130",
      "station_distance_nm": 0.2,
      "phase": "flood",
      "description": "Tide is rising (flood) -- water moving shoreward",
      "previous": {"type": "low", "time": "2026-02-20 06:45", "level_ft": -0.82},
      "next": {"type": "high", "time": "2026-02-20 13:12", "level_ft": 11.03},
      "minutes_since_previous": 105,
      "minutes_to_next": 282,
      "progress_pct": 27.1
    }
  },
  {
    "timestamp": "2026-02-20T14:15:00Z",
    "latitude": 47.6,
    "longitude": -122.34,
    "catch_count": 7,
    "species": "dungeness",
    "tidal": {
      "station_id": "9447130",
      "station_distance_nm": 0.2,
      "phase": "ebb",
      "description": "Tide is falling (ebb) -- water moving seaward",
      "previous": {"type": "high", "time": "2026-02-20 13:12", "level_ft": 11.03},
      "next": {"type": "low", "time": "2026-02-20 19:30", "level_ft": 2.14},
      "minutes_since_previous": 63,
      "minutes_to_next": 315,
      "progress_pct": 16.7
    }
  }
]

---

water_level_anomaly smartpot

Compare observed water levels against predictions to detect storm surge, seiche events, or sensor drift.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
window_hours	int	6	Lookback window for comparison
threshold_ft	float	0.5	Deviation threshold in feet

Risk levels:

Level	Condition	Meaning
normal	max deviation < threshold	Conditions as expected
elevated	threshold <= deviation < 2x threshold	Moderate deviation, monitor conditions
high	deviation >= 2x threshold	Possible storm surge, seiche, or weather influence

Example call:

{
  "tool": "water_level_anomaly",
  "arguments": {
    "station_id": "8454000",
    "window_hours": 12,
    "threshold_ft": 0.3
  }
}

Example response:

{
  "station_id": "8454000",
  "window_hours": 12,
  "threshold_ft": 0.3,
  "risk_level": "elevated",
  "explanation": "Water levels are 0.42 ft above predictions -- moderate deviation, monitor conditions",
  "max_deviation_ft": 0.42,
  "mean_deviation_ft": 0.18,
  "direction": "above",
  "sample_count": 120
}

---

Visualization

Chart generation tools. Require the mcnoaa-tides[viz] optional dependency (matplotlib for PNG, plotly for HTML).

visualize_tides visualization

Generate a tide prediction chart with high/low markers and optional observed water level overlay.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
hours	int	48	Time window for the chart
include_observed	bool	True	Overlay observed water levels as a dashed line
format	Literal["png", "html"]	"png"	Output format

Return value:

• "png" — Returns an inline Image object (rendered directly in MCP clients that support images)
• "html" — Saves an interactive Plotly chart to artifacts/charts/ and returns the file path

Example call:

{
  "tool": "visualize_tides",
  "arguments": {
    "station_id": "9447130",
    "hours": 72,
    "format": "html"
  }
}

Example response (html format):

Interactive tide chart saved to: artifacts/charts/9447130_tides_20260222_143000.html

---

visualize_conditions visualization

Generate a multi-panel marine conditions dashboard with up to 4 panels: tides with observed overlay, wind speed and gust, air and water temperature, and barometric pressure with trend.

Parameter	Type	Default	Description
station_id	str	required	7-digit NOAA station ID
hours	int	24	Time window for all panels
format	Literal["png", "html"]	"png"	Output format

Products unavailable at a station are omitted from the dashboard rather than causing an error.

Example call:

{
  "tool": "visualize_conditions",
  "arguments": {
    "station_id": "9447130",
    "hours": 48,
    "format": "png"
  }
}

Return value: Same behavior as visualize_tides — inline image for PNG, file path for HTML.

Note

Install visualization dependencies with uv pip install mcnoaa-tides[viz]. The server runs without them but these two tools will raise a ValueError with an install hint if the dependencies are missing.

---

Diagnostics

Tools for inspecting the MCP session and client capabilities.

test_client_capabilities diagnostics

Report which MCP features the connected client supports. Returns the client implementation info, protocol version, and capability flags for sampling, elicitation, roots, and tasks. Useful for understanding what features are available before calling tools that depend on optional client capabilities.

No parameters required.

Example call:

{
  "tool": "test_client_capabilities",
  "arguments": {}
}

Example response:

{
  "session_id": "cb6ddc2d-f866-4fa3-bf2e-15eebd133481",
  "client": {
    "name": "claude-code",
    "version": "2.1.38"
  },
  "protocol_version": "2025-11-25",
  "capabilities": {
    "sampling": false,
    "elicitation": false,
    "roots": true,
    "tasks": false
  },
  "roots_detail": {
    "list_changed": false
  }
}

When a capability is true, additional *_detail keys are included with sub-capability flags. For example, a client that supports sampling would include:

{
  "sampling_detail": {
    "context": true,
    "tools": true
  }
}

Tip

Call this tool first to discover whether the client supports sampling (which enables natural-language summaries in marine_conditions_snapshot, deployment_briefing, and water_level_anomaly).

---

Datum Options

Several tools accept a datum parameter. The most common options:

Datum	Full Name	Description
MLLW	Mean Lower Low Water	Default. The average of the lower of the two daily low tides
MSL	Mean Sea Level	Average water level over the tidal epoch
NAVD	North American Vertical Datum (1988)	Fixed geodetic reference
STND	Station Datum	The station’s internal reference zero
MHW	Mean High Water	Average of all high tide levels
MHHW	Mean Higher High Water	Average of the higher of the two daily high tides
MLW	Mean Low Water	Average of all low tide levels
MTL	Mean Tide Level	Midpoint between MHW and MLW