NOAA tides and currents: water levels, tide predictions, currents, met data, flooding, sun and moon
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
Average 4.5/5 across 26 of 26 tools scored. Lowest: 3.6/5.
Every tool has a clearly distinct purpose, with clear groupings by prefix (astro_, noaa_, nws_, perigee_). Within groups, tools like noaa_get_water_levels vs noaa_get_tide_predictions are well-differentiated by observed vs predicted data.
Most tools follow a consistent prefix_verb_noun pattern (e.g., astro_get_moon_phase, noaa_get_tide_predictions). The only outlier is perigee_whoami, which uses a different verb style, but it's a single tool.
At 26 tools, the count is slightly above the typical sweet spot but still well-scoped for the broad domain of tides, currents, astronomy, and forecasts. Each tool serves a specific purpose without redundancy.
The tool surface is exceptionally comprehensive, covering observed and predicted water levels, currents, datums, sea level trends and projections, astronomical data, NWS forecasts, and station metadata. No obvious gaps for the stated domain.
astro_get_moon_phaseGet Moon PhaseAGet the moon phase for a date (or each day of a date range if end_date is given): phase name (New Moon, Waxing Crescent, ...), illuminated fraction, age in days within the 29.53-day cycle, distance (km), apparent diameter (degrees), and waxing/waning.
Tide context: spring tides (largest range) occur just after new and full moons; neap tides after quarter moons. Computed locally — no NOAA data involved.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. | |
| end_date | No | Optional range end (YYYY-MM-DD): returns one entry per day from date through end_date. | |
| latitude | No | Optional latitude for distance/diameter precision. | |
| longitude | No | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. Description adds local computation detail and explains output fields, but does not cover potential limits or side effects. Useful extra context beyond 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?
Two concise paragraphs: first listing outputs, second providing tide context and computation note. No fluff, front-loaded with essential information. Every sentence adds value.
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?
Covers purpose, output fields, optional parameters (date, end_date, lat/lon, format), and context (tides, local computation). No missing pieces for a read-only retrieval tool with five optional inputs.
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?
All five parameters have schema descriptions (100% coverage). The tool description adds meaning by explaining what the tool returns (phase name, illuminated fraction, etc.), complementing the schema without redundancy. Adds value beyond baseline.
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?
Clearly states the tool retrieves moon phase data for a date or date range, listing specific output fields (phase name, illuminated fraction, age, distance, diameter, waxing/waning). Distinguishes from sibling tools like astro_get_next_moon_phase which focuses on upcoming phases.
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?
Explicitly mentions tide context (spring/neap tides) and notes 'Computed locally — no NOAA data involved,' guiding users away from NOAA siblings when local computation is acceptable. Provides clear when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
astro_get_next_moon_phaseGet Next Moon Phase OccurrenceAFind the date(s) of the next occurrence(s) of a principal moon phase (New Moon, First Quarter, Full Moon, Last Quarter) from a starting date.
Use for: "when is the next full moon?", planning around spring tides (which follow new/full moons by 1–2 days).
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Search start date (YYYY-MM-DD). Defaults to today. | |
| count | No | How many occurrences to return. | |
| phase | Yes | Which principal phase to find. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent behavior. The description adds that it finds 'next occurrence(s)' but does not elaborate on other behavioral traits (e.g., no side effects, output behavior). The description adds minimal value beyond 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 two concise sentences, front-loaded with the core function and followed by practical use cases. No unnecessary words.
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?
The description covers the core purpose and usage context. With good schema coverage and annotations, it is mostly complete, though it could briefly mention output format options (though defined in 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 100%, so the schema already describes all parameters. The description only implicitly references parameters ('starting date' for date, 'next occurrence(s)' for count) without adding new semantic detail.
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 it finds the next occurrence of a principal moon phase from a starting date, with examples like 'when is the next full moon?'. However, it does not explicitly distinguish itself from the sibling tool 'astro_get_moon_phase', which may have a different purpose, but the purpose is still clear.
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 provides usage examples ('when is the next full moon?', planning around spring tides) but does not specify when not to use this tool or compare it to alternatives like astro_get_moon_phase for specific dates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
astro_get_next_sun_eventGet Next Sun EventAFind the next occurrence(s) of a sun event (sunrise, sunset, dawn, dusk, solarNoon, night, nightEnd, goldenHourStart, goldenHourEnd, nauticalDawn, nauticalDusk, astronomicalDawn, astronomicalDusk) at a location from a starting date.
Use for: "when is sunset today?", planning golden-hour photography or dawn fishing around tide windows.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Search start date. Defaults to today. | |
| count | No | How many occurrences to return. | |
| event | Yes | Sun event to find. | |
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| timezone | No | IANA timezone for output times (e.g. "America/New_York"). Defaults to UTC ISO timestamps. | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety. It adds context about searching from a starting date but lacks details on behavior when an event has already occurred on the start date (e.g., does it skip to next day?). No contradiction 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?
Two sentences, zero wasted words. The first sentence captures the core functionality, the second provides practical use cases. Front-loaded and efficient.
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, the description could mention return format or timezone handling, but the schema covers response_format and timezone. Mostly complete for a read-only lookup tool with rich annotations.
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 100% with all parameters well-documented. The description adds little beyond listing event types and implying date/count usage, so baseline 3 is appropriate.
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 uses specific verbs ('Find the next occurrence(s) of a sun event') and explicitly lists all event types. It clearly distinguishes from siblings by focusing on 'next occurrence' of a single event, unlike astro_get_sun_times which returns all events for a day.
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 provides concrete use cases ('when is sunset today?', 'planning golden-hour photography'), but does not explicitly mention when not to use it or suggest alternatives like astro_get_sun_times for multiple events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
astro_get_sun_positionGet Sun PositionAGet the sun's position for a date, time, and location: azimuth (degrees clockwise from north as rendered here), altitude above the horizon (degrees), plus approximate declination and right ascension.
Use for: shadow/lighting analysis, solar exposure. Computed locally with suncalc; declination/RA are approximate.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. | |
| time | No | Time of day (HH:MM[:SS], interpreted in the local runtime timezone). Defaults to now. | |
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, not destructive. The description adds that computation is local using suncalc and declination/RA are approximate, which are useful behavioral traits beyond the 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 concise: two sentences plus a use-case line. No redundant information. Key details are front-loaded.
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?
Without an output schema, the description explains the return values (azimuth, altitude, declination, RA) and their meanings. It also notes computation method and approximation. Missing a few nuances like 'as rendered here' but overall covers essential information.
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 100% with clear descriptions for each parameter. The description does not add extra parameter details but explains output units (degrees clockwise from north) which indirectly aids parameter understanding. Baseline 3 is appropriate.
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 computes sun position (azimuth, altitude, declination, right ascension) for a given date, time, and location. It uses a specific verb 'Get' and resource 'sun position', distinguishing it from sibling tools like moon phase or sun times.
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 explicitly mentions use cases: 'shadow/lighting analysis, solar exposure'. However, it does not provide exclusions or compare directly with siblings like astro_get_sun_times, which could be an alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
astro_get_sun_timesGet Sun TimesAGet sunrise, sunset, solar noon, dawn/dusk (civil), nautical dawn/dusk, astronomical dawn/dusk, golden hour, and day length for a location and date (or each day of a range if end_date is given).
Times are ISO UTC unless an IANA timezone is provided. At high latitudes some events may be null (e.g. no astronomical night in summer). Computed locally.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Date in YYYY-MM-DD format. Defaults to today. | |
| end_date | No | Optional range end: one entry per day. | |
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| timezone | No | IANA timezone for output times (e.g. "America/New_York"). Defaults to UTC ISO timestamps. | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only and idempotent. Description adds value by specifying timezone handling (ISO UTC unless IANA provided) and noting potential null events at high latitudes, which are beyond what annotations convey.
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?
Two sentences front-load the key capabilities and edge cases. Every sentence serves a purpose with no redundancy.
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 6 parameters and no output schema, the description adequately covers output content, timezone behavior, and potential nulls. A minor gap is not detailing the exact structure of the JSON/markdown output.
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 100%, so baseline is 3. Description does not add new per-parameter meaning beyond listing overall output and timezone behavior.
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 uses specific verbs ('Get') and lists multiple resources ('sunrise, sunset, solar noon, dawn/dusk...'), clearly distinguishing from siblings like astro_get_moon_phase and astro_get_sun_position.
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?
No explicit guidance on when to use this tool versus alternatives; only implied by the description of what it returns. Context about null events at high latitudes is useful but does not directly address tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_find_nearest_stationsFind Nearest NOAA StationsAFind the NOAA stations closest to a latitude/longitude point, sorted by distance.
Use this to answer "what's the tide station near ?" — geocode the place to coordinates first, then call this. Filter by type to match the data you need (e.g. type "tidepredictions" before calling noaa_get_tide_predictions, "currents" before noaa_get_currents — current stations have different IDs than water-level stations).
Distance is computed great-circle (Haversine) and reported in both km and miles. (NOAA's API has no native coordinate search; this tool maintains a cached station directory.)
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Station capability filter. Common: "waterlevels" (active water level), "tidepredictions", "currents" (observed currents), "currentpredictions", "met" (weather sensors). Full list via noaa_get_reference_guide topic "station_types". | |
| limit | No | Number of stations to return. | |
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| max_distance_km | No | Optional cutoff radius in kilometers. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds technical detail (Haversine computation, km/miles reporting, cached station directory) and mentions output format options. No contradiction.
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?
Five sentences with clear sections: purpose, usage example, technical note. No redundant information. Well-structured and efficient.
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?
All 6 parameters are explained. Output behavior (sorted by distance, km/miles) is covered. No output schema exists, but description gives sufficient summary. Some detail about response fields could be added, but acceptable.
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 100%. Description adds value by explaining type filter examples, default limit, max_distance_km as optional cutoff, and response_format options. Adds context beyond 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?
Description starts with a clear verb+resource: 'Find the NOAA stations closest to a latitude/longitude point, sorted by distance.' It uniquely identifies the tool's function and distinguishes it from siblings like noaa_search_stations.
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 usage context: geocode first, filter by type, and links to sibling tools (e.g., noaa_get_tide_predictions). Missing explicit 'when not to use' but covers key usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_current_predictionsGet Current PredictionsAGet predicted tidal currents for a NOAA current prediction station.
interval="max_slack" (recommended for navigation) returns the tidal-current events — maximum flood, maximum ebb, and slack water times — up to 1 year per request. Other intervals (h, 1, 6, 10, 30, 60 minutes) return a velocity time series — up to 31 days.
UNITS WARNING: english = knots; metric = cm/s.
vel_type="speed_dir" returns Speed/Direction pairs; "default" returns velocities projected on the flood/ebb axis (Velocity_Major: positive = flood direction, negative = ebb) with meanFloodDir/meanEbbDir. Subordinate (type "S") prediction stations derive from a reference station — see noaa_get_prediction_offsets.
| Name | Required | Description | Default |
|---|---|---|---|
| bin | No | Depth bin number (current meters measure at multiple depths). Find valid bins with noaa_get_station_info (expand ["bins"]). bin=0 returns ALL bins but caps the request at 7 days. Omit at single-bin stations. | |
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| interval | No | "max_slack" = max flood/ebb + slack events (1-year max span); h/1/6/10/30/60 = time series (31-day max span). | max_slack |
| vel_type | No | "default" = flood/ebb-axis velocity (Velocity_Major signed: + flood, - ebb); "speed_dir" = speed and compass direction. | default |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint. The description adds valuable context about bin behavior (bin=0 returns ALL bins but caps at 7 days), subordinate stations, and the difference between 'default' and 'speed_dir' velocity types. 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 well-structured with clear sections for intervals, units, velocity type, and station types. Every sentence adds value without repetition. It is concise yet comprehensive.
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 11 parameters and no output schema, the description covers essential aspects (interval behavior, unit differences, velocity types, station types). It lacks details about output structure (e.g., whether results include timestamps for each event), but the key behaviors are explained.
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 100%, so baseline is 3. The description adds meaningful context for several parameters (e.g., bin explains depth bins and the 7-day cap; range explains how hours are counted; units clarifies cm/s for currents while m/s for wind). This extra information justifies a 4.
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 uses specific verbs ('Get predicted tidal currents') and clearly identifies the resource (NOAA current prediction station). It distinguishes from sibling tools like noaa_get_currents and noaa_get_prediction_offsets by specifying the type of data and the station ID format.
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 provides explicit guidance on when to use different intervals (max_slack recommended for navigation, other intervals for time series) and includes a units warning. However, it does not explicitly compare this tool to similar siblings like noaa_get_currents, leaving some ambiguity about when to use each.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_currentsGet Observed CurrentsAGet observed current speed and direction from a NOAA current meter station.
Current stations use alphanumeric IDs (e.g. "cb0102" Chesapeake, "bh0101" Boston Harbor) — NOT the 7-digit water-level station IDs. Find them with noaa_search_stations (type "currents") or noaa_find_nearest_stations.
UNITS WARNING: english = knots, but metric = cm/s (centimeters/second, not m/s).
Returns per record: t (time), s (speed), d (direction, degrees true), b (bin number). Max 7 days per request. Set expand_detailed=true to include per-beam echo intensity and correlation diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| bin | No | Depth bin number (current meters measure at multiple depths). Find valid bins with noaa_get_station_info (expand ["bins"]). bin=0 returns ALL bins but caps the request at 7 days. Omit at single-bin stations. | |
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| expand_detailed | No | Include ADCP beam diagnostics (echo1-4, corr1-4) per record. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, not destructive), description discloses: return fields (t, s, d, b), unit behavior (metric currents in cm/s), depth bin behavior, expand_detailed adds beam diagnostics, max 7-day limit. Thoroughly covers behavioral traits and potential pitfalls.
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?
Well-structured: purpose first, then station ID clarification, units warning, return fields, max days. Each sentence earns its place; no redundancy. Efficiently packed with critical information.
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?
Covers essential aspects for a complex tool with 10 parameters. Explains bin, date, units edge cases. Missing: error handling, rate limits, explicit response format description (though response_format param is documented). Still, highly complete for no output schema scenario.
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 100% schema coverage, baseline is 3. Description adds substantial value: clarifies station ID pattern, units conversion specifics, date format examples, bin parameter behavior (omit vs 0), and expand_detailed effect. Goes well beyond schema definitions.
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?
Clearly states 'Get observed current speed and direction from a NOAA current meter station.' Distinguishes from siblings by clarifying station ID format (alphanumeric vs numeric) and contrasts with noaa_get_current_predictions for predictions. The description gives specific examples and clarifies scope.
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 guidance: how to find stations (noaa_search_stations, noaa_find_nearest_stations), units warning (knots vs cm/s), max 7 days per request, and advice on expand_detailed. Does not explicitly state when not to use, but the station ID distinction effectively warns against using water-level IDs. Lacks comparison to sibling tools like noaa_get_current_predictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_extreme_water_levelsGet Extreme Water LevelsAGet NOAA's extreme water level exceedance statistics for a station: the annual exceedance probability levels (e.g. the 1%-annual-chance "100-year" level) and historical extreme events, computed from the station's verified record.
Use for flood risk questions ("what water level has a 1% chance per year at X?"). Levels are relative to the station's datums for the 1983–2001 epoch. Only long-record stations have this product.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| levelType | No | High extremes (default) or low. | |
| extremeType | No | Extreme statistics basis: annual (default) or monthly extremes. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, open-world, idempotent, and non-destructive behavior. The description adds behavioral context: levels are relative to station's datums for the 1983–2001 epoch, and only long-record stations have this product. No contradictions.
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 three sentences long, front-loads the core purpose in the first sentence, and every sentence adds value. No wasted words.
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 complexity, the description covers what the tool returns, the datums and epoch used, and eligibility criteria. Although there is no output schema, the description sufficiently informs the agent of the output type.
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 100% with each parameter described. The description does not add additional parameter-level information beyond what the schema provides, so baseline score of 3 is appropriate.
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 retrieves NOAA's extreme water level exceedance statistics for a station, specifying it provides annual exceedance probability levels and historical extreme events. This distinguishes it from sibling tools like noaa_get_water_levels or noaa_get_high_tide_flooding.
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 explicitly says 'Use for flood risk questions' and mentions that only long-record stations have this product. While it doesn't explicitly contrast with all siblings, it gives sufficient context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_harmonic_constituentsGet Harmonic ConstituentsAGet the harmonic constituents NOAA uses to compute tide or current predictions at a station — the amplitude, phase, and angular speed of each tidal constituent (M2, S2, N2, K1, O1, ...).
For water-level stations: amplitude (feet/meters), phase_GMT and phase_local (degrees), speed (degrees/hour). For current stations (alphanumeric IDs) constituents are current ellipses (major/minor amplitudes and phases per depth bin — pass bin to filter).
Use for: building custom tide computations, checking a station's dominant constituents (M2 amplitude indicates semidiurnal range), verifying whether a station is harmonically predicted at all. Only reference (R) stations have constituents — subordinate stations use offsets (noaa_get_prediction_offsets).
| Name | Required | Description | Default |
|---|---|---|---|
| bin | No | For current stations: restrict to one depth bin. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, idempotent, non-destructive. Description adds detailed return values for water-level and current stations, including current ellipses and bin filtering. No contradictions.
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?
Three well-organized paragraphs: general purpose, station-specific details, use cases/limitations. Every sentence adds value. No 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?
Covers output format (amplitude, phase, speed, ellipses), filtering by bin, and limitation to reference stations. No output schema, but description sufficiently documents return structure. Links to related tools.
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 100% with good descriptions. Description adds extra context: explains bin is for current stations and units affect feet vs meters. Provides more value than baseline.
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?
Clearly states it gets harmonic constituents for tide/current predictions, lists specific values (amplitude, phase, speed) and distinguishes between station types. Differentiated from sibling noaa_get_prediction_offsets.
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?
Explicitly lists use cases (building custom tide computations, checking dominant constituents) and tells when not to use (subordinate stations → use offsets). Provides alternative tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_high_tide_floodingGet High Tide Flooding DataAGet NOAA high tide flooding (HTF, "nuisance"/"sunny day" flooding) statistics for a station. Reports:
daily: flood occurrence per day (REQUIRES start_date and end_date, YYYYMMDD)
monthly / seasonal / annual: counts of minor/moderate/major flood days per period (filter with year/month/season_months, or range = last N periods)
met_year_annual: counts by meteorological year (May–April)
annual_outlook: NOAA's projected flood-day outlook for the coming met year
projections: decadal flood-day projections through 2100 (filter by decade, flood_threshold)
record_days: record flood-day counts
likely_scenarios: likely decadal flooding scenarios
daily_likelihoods: day-by-day flood likelihood forecasts
Use for: "how often does X flood?", trends in nuisance flooding, future flooding projections. Not all stations have HTF products — check the HTFhistorical flag via noaa_get_station_info.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | Filter to a calendar year (monthly/seasonal/annual/record_days). | |
| month | No | Filter to a month (monthly report). | |
| range | No | Number of years to cover: with year (or met_year) set, returns year..year+range; without, returns the last N years. | |
| decade | No | Decade for projections/likely_scenarios (e.g. 2050). | |
| report | No | Which HTF report to retrieve (see tool description). | annual |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | YYYYMMDD — required for report "daily". | |
| met_year | No | Meteorological year (met_year_annual / annual_outlook). | |
| start_date | No | YYYYMMDD — required for report "daily". | |
| season_months | No | Season for the seasonal report (Dec-Jan-Feb, Mar-Apr-May, ...). | |
| flood_threshold | No | Flood severity threshold for projections/likely_scenarios. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context, such as parameter dependencies (e.g., 'daily REQUIRES start_date and end_date') and the ability to choose output format via the response_format parameter. 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 well-structured with a clear one-line summary followed by a bulleted list of report types. It front-loads key information and each line serves a purpose. While lengthy, the structured format aids readability and the content is necessary for such a parameter-rich tool.
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 has 12 parameters and no output schema, the description is fairly complete. It covers all report types, parameter requirements, and mentions a prerequisite check. It could further detail return behavior or edge cases, but overall it provides sufficient context for an agent to invoke the tool correctly.
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 100%, but the description goes beyond by explaining each report type's purpose and required parameters (e.g., start_date/end_date for daily). It also clarifies that year, month, range, and other filters apply to specific reports, adding meaning beyond the bare schema descriptions.
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 identifies the tool as retrieving NOAA high tide flooding statistics for a station. It explicitly lists the many report types (daily, monthly, seasonal, etc.) with brief explanations, distinguishing it from sibling tools like noaa_get_tide_predictions or noaa_get_water_levels.
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 states 'Use for: "how often does X flood?", trends in nuisance flooding, future flooding projections' and includes a critical caveat: 'Not all stations have HTF products — check the HTFhistorical flag via noaa_get_station_info.' This provides clear context and a prerequisite check, though it does not explicitly list when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_meteorological_dataGet Meteorological & Sensor DataAGet observed meteorological/oceanographic sensor data from a NOAA station.
Products: air_temperature, water_temperature, wind (speed/gust/direction), air_pressure, air_gap (bridge clearance to water surface), conductivity, visibility, humidity, salinity.
Units by system: temps °F/°C; wind knots (english) or m/s (metric); air_gap feet/meters; visibility nautical miles/kilometers; air_pressure always millibars; salinity always PSU. Max span ~31 days per request; interval "6" (6-minute, default) or "h" (hourly).
Not every station has every sensor — check with noaa_get_station_info (expand ["sensors"]). Water-level data is served by noaa_get_water_levels, not this tool.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| product | Yes | Sensor product to retrieve. | |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| interval | No | "6" = 6-minute observations (default), "h" = hourly. | 6 |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, which the description supports by describing safe read operations. Description adds useful behavioral details: max data range, interval behavior, unit system nuances, and suggestion to check sensor availability via another tool.
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?
Description is efficiently structured: opening sentence, product list, units, constraints, then cross-reference. No redundant or filler sentences; each sentence adds specific guidance.
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?
Comprehensive for a read-only sensor data tool with 10 parameters. Cross-references to noaa_get_station_info and noaa_get_water_levels. Lacks explicit output schema detail, though response_format parameter offers JSON option. Minimal gap given complexity.
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?
Despite 100% schema description coverage, the description adds significant value beyond schema: explains units per system, clarifies date/range interaction, notes time zone caveat for daily_mean data, and describes output format options. Every parameter's meaning is enriched.
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 starts with clear verb+resource ('Get observed meteorological/oceanographic sensor data from a NOAA station'), lists specific products, and explicitly distinguishes from sibling tool noaa_get_water_levels for water-level 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?
Description states when to use (for meteorological/oceanographic sensor data), notes max span ~31 days, and contrasts with water-level tool. However, it could more explicitly differentiate from other siblings like noaa_get_currents or tide predictions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_prediction_offsetsGet Prediction Offsets (Subordinate Stations)AGet the offsets a subordinate (type "S") prediction station applies to its reference station's predictions.
kind "tide": returns refStationId, time offsets for high/low tide (minutes), height offsets for high/low tide, and whether the height adjustment is a ratio (multiplied) or fixed value — this is how NOAA derives subordinate-station tide times from the reference harmonic station.
kind "current": returns refStationId/bin, mean flood/ebb directions, and time adjustments (minutes) for max flood, slack-before-ebb, max ebb, slack-before-flood plus amplitude ratios. Note: current prediction offsets are indexed per bin — pass the station_bin_suffix ID form (e.g. "ACT0091_1") if the plain ID returns nothing.
Reference (R) stations return empty/null offsets — they don't need any.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | "tide" = tidepredoffsets; "current" = currentpredictionoffsets. | tide |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly, idempotent, not destructive. Description adds behavioral context: returns structured offsets for tide/current, notes bin-indexing for current, and explains what is computed. No contradictions and adds value beyond 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?
Well-structured with a clear first line followed by detailed sections for tide and current, plus a note on reference stations. Slightly verbose but every sentence adds value.
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?
No output schema, but the description explains what is returned for each kind (refStationId, offsets, etc.) and includes a workaround. Sufficient for understanding the tool's output without being overly detailed.
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 has 100% coverage with descriptions for all parameters. The description elaborates on how 'kind' affects output but the schema already defines the parameter. Baseline 3 is appropriate given high schema 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 clearly states the tool gets offsets for subordinate (type 'S') prediction stations from reference stations, with distinct handling for tide and current kinds. It differentiates from sibling tools like noaa_get_tide_predictions by focusing specifically on offsets.
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 clear guidance: use for subordinate stations (type S), reference stations return empty, and for current prediction offsets pass bin suffix if plain ID fails. Could explicitly compare to sibling tools but the context is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_reference_guideGet NOAA API Reference GuideAGet curated reference documentation for NOAA CO-OPS concepts and parameters. Topics:
products: Every NOAA CO-OPS data product and which tool serves it
datums: Vertical datums (MLLW, MSL, IGLD...) and station applicability
units: What english vs metric means per measurement (incl. cm/s currents)
time_zones: gmt / lst / lst_ldt semantics and restrictions
intervals: Valid interval values per product family
station_types: Station type filters and station ID formats
data_limits: Maximum date-range span per product
quality_flags: Data quality fields (v/s/f/q), flag letters, HH/H/L/LL
date_formats: Accepted date formats and parameter combinations
marine_forecast: NWS wind & marine forecast tools vs CO-OPS observations
Consult this before constructing unusual requests — especially "datums" (which vertical reference to use and station applicability), "units" (english/metric asymmetries like cm/s current speeds), and "data_limits" (maximum date spans per product).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Reference topic to retrieve. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate read-only, idempotent, non-destructive behavior, which the description aligns with by noting it provides reference documentation. The description adds value by detailing the scope of topics covered, going beyond annotation information.
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 concise, using a bullet list for topics and emphasizing key ones in a single paragraph. Every sentence adds useful information without redundancy.
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 simple parameter (one enum) and no output schema, the description adequately explains the tool's purpose and the content of each topic. It doesn't specify return format but that's acceptable for a reference guide.
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 input schema has 100% coverage with a single enum parameter. The description adds context by explaining the content of each topic (e.g., what 'datums' includes), exceeding the schema's basic description.
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 provides curated reference documentation for NOAA CO-OPS concepts and parameters. It lists specific topics, distinguishing itself from sibling data retrieval tools by emphasizing its role as a reference guide.
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 explicitly advises consulting this tool before constructing unusual requests, highlighting specific topics like datums, units, and data_limits. It provides clear context for when to use it, though it doesn't explicitly state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_sea_level_rise_projectionsGet Sea Level Rise ProjectionsAGet NOAA's Interagency Sea Level Rise Scenario projections for a station (from the 2022 technical report): projected relative sea level (meters or feet, see units field) per decade through 2150 under the chosen scenario.
Scenarios: low, intermediate-low, intermediate, intermediate-high, high, extreme, or all. Use for coastal planning questions ("how much sea level rise is projected at X by 2050?"). Pair with noaa_get_sea_level_trends (observed) and noaa_get_high_tide_flooding (flooding impact).
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | No | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| scenario | No | Emissions/rise scenario from the 2022 Interagency report. | intermediate |
| projection_year | No | Filter to a single decade year (e.g. 2050). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, which clearly indicate a safe, read-only operation. The description adds that projections come from the 2022 technical report and span through 2150, which is useful context but not essential beyond annotations. 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 two sentences. The first sentence efficiently conveys the tool's purpose, data source, time range, and scenario options. The second sentence adds a use case and links to sibling tools. No filler words; every phrase earns its place.
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 annotations (read-only, idempotent) and the comprehensive parameter descriptions (100% schema coverage), the description covers all necessary aspects for an agent to invoke the tool correctly. No output schema is provided, but the response_format parameter handles that. The tool is straightforward, and the description is complete.
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 100% schema coverage, baseline is 3. The description adds value for each parameter: it explains scenarios come from the 2022 Interagency report, suggests how to find station IDs (via noaa_search_stations or noaa_find_nearest_stations), clarifies unit system details (e.g., knots for wind, nautical miles), and explains the purpose of projection_year and response_format outputs. This goes beyond the schema's field descriptions.
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 uses specific verbs ('Get NOAA's Interagency Sea Level Rise Scenario projections for a station') and resources ('projected relative sea level per decade through 2150'). It explicitly distinguishes from sibling tools by naming noaa_get_sea_level_trends and noaa_get_high_tide_flooding, clarifying what this tool does vs. related functionality.
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 states the tool is for coastal planning questions and provides an example query ('how much sea level rise is projected at X by 2050?'). It also suggests pairing with two sibling tools, giving clear context. However, it does not explicitly state when not to use this tool (e.g., if historical trends are needed instead), so it misses some exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_sea_level_trendsGet Relative Sea Level TrendsAGet the long-term relative sea level trend at a NOAA station: trend and error (reported by NOAA in mm/yr or inches/decade — the payload's trendUnits field says which), the observation period (startDate/endDate), and seasonal amplitude.
Relative sea level combines ocean rise AND local land movement (subsidence/uplift), so trends vary widely by station (e.g. strongly positive on the Gulf Coast, negative in Alaska). Requires a station with a long water-level record; omit station to list all (affil "US" or "Global" filters the network).
| Name | Required | Description | Default |
|---|---|---|---|
| affil | No | Network filter when listing multiple stations. | |
| station | No | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable context: relative sea level combines ocean rise and land movement, trends vary by region, and a long water-level record is needed. 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 three concise sentences, each serving a purpose: stating what the tool returns, explaining relative sea level, and giving usage conditions. No unnecessary words.
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?
Despite no output schema, the description mentions key fields (trendUnits, startDate/endDate) and covers the tool's behavior sufficiently. With rich annotations and all parameters optional, it provides complete context for effective use.
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 100% with descriptions. The description adds value by explaining the station parameter format (e.g., '9414290' for water-level stations) and clarifying the affil parameter's role. It also explains the response_format options in plain language.
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 explicitly states it gets long-term relative sea level trends at a NOAA station, including trend, error, period, and seasonal amplitude. It distinguishes from siblings by explaining the concept of relative sea level and noting the requirement for a long record, differentiating it from other NOAA tools like water levels or extreme events.
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 provides clear guidance on when to use: for long-term trends, and mentions omitting station to list all. It also points to sibling tools (noaa_search_stations, noaa_find_nearest_stations) for finding stations, but does not explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_station_datumsGet Station DatumsAGet the accepted tidal datum values for a station: the elevations of MHHW, MHW, MTL, MSL, DTL, MLW, MLLW, STND, NAVD88 (where computed), plus GT (great diurnal range), MN (mean range), LAT/HAT (lowest/highest astronomical tide), and the station's historical extreme min/max water levels with dates.
epoch "current" returns the present National Tidal Datum Epoch (1983–2001) values; "superseded" returns the prior epoch's values (useful for historical comparisons — not all stations have one).
All values share one reference zero (the station datum), so datum-to-datum conversion is subtraction: height_above_MLLW = height_above_MSL + (MSL − MLLW). Use this tool to (1) check which datums a station supports before requesting data, and (2) convert heights between datums.
| Name | Required | Description | Default |
|---|---|---|---|
| epoch | No | "current" = present NTDE (1983–2001); "superseded" = prior epoch values. | current |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive. The description adds value by explaining the return composition (various datums with relationships) and the conversion method, without contradicting any 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 well-structured in two paragraphs: first listing datums, second explaining epoch options and conversion. It is front-loaded with key information but could slightly be more concise without losing clarity.
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 read-only tool without output schema, the description fully explains what is returned (datum list and extreme values) and provides a practical conversion formula. No missing elements identified.
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 100% with descriptions already present. The description adds minor extra context for epoch and explains datum relationships, but does not significantly enhance parameter understanding beyond the 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 clearly states it retrieves accepted tidal datum values for a station, listing specific datums (MHHW, MHW, etc.), and distinguishes from sibling tools by focusing on datum values rather than water levels or predictions.
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?
Explicitly specifies two use cases: checking which datums a station supports before data requests, and converting heights between datums. Also explains the epoch parameter for historical comparisons. Missing explicit when-not-to-use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_station_infoGet Station InfoAGet a NOAA station's full metadata record: location, state, time zone, tide type, Great Lakes flag, capability flags, and links to available sub-resources.
Optionally expand sub-resources inline via the "expand" list:
details (established/removed dates), sensors (installed instruments + elevations), floodlevels (NOS/NWS minor/moderate/major flood thresholds), benchmarks, products (available data page links), notices, disclaimers — for water-level stations
bins (ADCP depth bins), deployments — for current stations (alphanumeric IDs)
Use this before requesting data to confirm what the station actually collects. For datum values use noaa_get_station_datums; for harmonic constituents use noaa_get_harmonic_constituents.
| Name | Required | Description | Default |
|---|---|---|---|
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| expand | No | Sub-resources to embed inline (availability varies by station type). | |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive. The description adds value by detailing the returned metadata, expandable sub-resources, and the ability to choose output format (markdown vs json). No contradiction 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 concise and well-structured. It starts with a clear summary, then uses a short list for the expand parameter (though not formal bullets), and ends with usage guidance. Every sentence adds value without redundancy.
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?
Covers the main return fields, expansion options, and format choices. Could mention how the 'units' parameter affects the output (e.g., feet vs meters for elevation), but overall it is sufficient for a metadata retrieval tool with no 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 100%, but the description enriches parameter meanings: for 'expand' it lists all sub-resources with brief explanations (e.g., 'details (established/removed dates)'), and for 'station' it distinguishes between numeric and alphanumeric IDs with examples. This adds significant value beyond the 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 clearly states it retrieves a full metadata record including location, state, time zone, tide type, and capability flags. It distinguishes itself from siblings like noaa_get_station_datums and noaa_get_harmonic_constituents by explicitly deferring to those for specific 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?
Provides explicit guidance: 'Use this before requesting data to confirm what the station actually collects.' It also tells when not to use it by directing to noaa_get_station_datums and noaa_get_harmonic_constituents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_tide_predictionsGet Tide PredictionsAGet NOAA harmonic tide predictions (future or past) for a station.
interval="hilo" (recommended for "when is high/low tide") returns the daily tide events with type H/L — up to 10 years per request. Other intervals (h, 1, 5, 6, 10, 15, 30, 60 minutes) return a height time series — up to 1 year per request.
Heights are relative to the requested datum (MLLW default). Notes:
Great Lakes stations have NO tide predictions (lake levels are not tidal).
Subordinate stations (type "S") only support interval=hilo; use the station's reference (R) station for interval series.
Predictions are astronomical only — they exclude weather effects (storm surge, wind setup). Compare with noaa_get_water_levels for actual conditions.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| datum | No | Vertical reference datum for heights. MLLW is the standard chart datum for coastal stations. IGLD and LWD apply to Great Lakes stations ONLY; NAVD/CRD exist only at stations where computed. Check a station's supported datums with noaa_get_station_datums. | MLLW |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| interval | No | "hilo" = high/low tide events only (max 10-year span). "h" = hourly, or 1/5/6/10/15/30/60-minute series (max 1-year span). | hilo |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnly, idempotent, etc.), the description adds critical behavioral details: max time spans (10 years for hilo, 1 year for others), datum relativity, limitations for specific station types, and exclusion of weather effects. No contradiction 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 concise and well-structured: opening sentence with core purpose, bullet points for key notes, and logical flow. Every sentence adds value without redundancy.
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 complexity (10 params, 1 required, many siblings), the description covers all necessary aspects: purpose, usage guidance, behavioral constraints, parameter context, and cross-references to related tools. No output schema needed as response_format parameter is documented.
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 100%, so parameters are already documented. The description adds value by explaining the behavior of interval types and constraints on usage (e.g., subordinate stations only support hilo). This goes beyond simple parameter listing, earning a 4.
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 fetches NOAA harmonic tide predictions for a station, distinguishes between interval types (hilo for high/low events vs. time series), and notes limitations (Great Lakes, subordinate stations, astronomical only). This differentiation from siblings like noaa_get_water_levels is explicit.
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 provides explicit usage guidance: recommends hilo for tide event queries, notes max time spans per interval, cautions about Great Lakes and subordinate stations, and suggests comparing with noaa_get_water_levels for actual conditions. This helps the agent decide when to use this tool vs. alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_top_ten_water_levelsGet Top Ten / Peak Water LevelsAGet a station's highest recorded water levels: analysis "toptenwaterlevels" returns the ten highest events on record (with date, height, causal event name like "Great New England Hurricane", and category); "peakwaterlevels" returns peak event records (optionally filtered by year).
Heights are relative to the requested datum (MHHW is typical for flood comparisons). Use for "what's the worst flooding ever recorded at X?".
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | For peakwaterlevels: filter to one year. | |
| datum | No | Reference datum for reported heights (MHHW is standard for flood context). | MHHW |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| analysis | No | "toptenwaterlevels" = ten highest on record; "peakwaterlevels" = peak event records. | toptenwaterlevels |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that heights are relative to datum, analysis types, and optional year filter. Annotations already indicate readOnly and idempotent, so no contradictions. Missing details like data availability limitations but acceptable.
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?
Two sentences, front-loaded with key purpose, efficient with no redundant words.
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 rich annotations, detailed schema, and no output schema, the description covers return content and datum interpretation thoroughly. It explains the practical meaning of the data (flood context) and is sufficient for an agent.
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?
Input schema already describes all 6 parameters with 100% coverage. Description adds context about datum for flood comparisons and output content (causal event names), but not essential given schema richness.
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 clearly states it retrieves highest recorded water levels with two analysis types. It distinguishes from sibling tools like noaa_get_water_levels or noaa_get_sea_level_trends by focusing on peak/record events.
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 a concrete use case ('what's the worst flooding ever recorded at X?') and explains when to use top ten vs peak. Could be more explicit about when not to use (e.g., for trends), but overall clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_water_levelsGet Observed Water LevelsAGet observed water levels from a NOAA tide station as a time series.
Choose the interval: "6" = standard 6-minute observations (preliminary or verified, max 31 days per request), "1" = 1-minute preliminary data (max 4 days), "hourly" = verified hourly heights (max 1 year). Heights are relative to the requested datum (MLLW by default — the US nautical chart zero).
Returns per record: t (timestamp in requested time zone), v (height), s (sigma), f (quality flags, decoded in output), q (p=preliminary, v=verified). Recent data is preliminary; verification takes days to weeks.
Use for: "what is the water level right now" (date=latest), storm surge analysis, comparing observed vs predicted tide. Do NOT use for future tides — use noaa_get_tide_predictions.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| datum | No | Vertical reference datum for heights. MLLW is the standard chart datum for coastal stations. IGLD and LWD apply to Great Lakes stations ONLY; NAVD/CRD exist only at stations where computed. Check a station's supported datums with noaa_get_station_datums. | MLLW |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| interval | No | Observation interval: "6" = 6-minute (standard, 31-day max), "1" = 1-minute preliminary (4-day max), "hourly" = verified hourly heights (1-year max). | 6 |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data is preliminary until verified (takes days/weeks), intervals have max durations, heights are relative to a datum, and output fields are documented. 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 well-structured: first sentence states purpose, then parameter details, then usage guidance. It is front-loaded with essential info, and every sentence adds value. No redundant or vague phrasing.
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 complexity (10 parameters, no output schema), the description covers all key aspects: what is returned (per record fields), how to interpret data (preliminary vs verified), caveats, and alternatives. It is complete enough for an agent to select and invoke correctly.
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 100%, but the description adds significant meaning beyond schema: explains interval types (standard vs preliminary), default datum (MLLW), unit system quirks (air pressure in both systems), and time zone details (daily_mean requires lst). This saves the agent from inferring these nuances.
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 gets observed water levels from a NOAA tide station as a time series. It specifies the resource (water levels), action (get), and scope (observed). Sibling tools like noaa_get_tide_predictions are distinguished by noting the tool is not for future tides, providing clear differentiation.
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 explicitly lists use cases (current water level, storm surge analysis, comparing observed vs predicted) and explicitly states what not to use it for (future tides, directing to noaa_get_tide_predictions). It also explains interval constraints (max days per request) and datum behavior, giving comprehensive guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_get_water_level_summariesGet Water Level Summaries (High/Low, Daily, Monthly)AGet verified summary water-level products from a NOAA station:
high_low: each day's observed highs/lows with ty = HH (higher high), H, L, LL (lower low). Max 1 year per request.
daily_mean: daily mean levels — GREAT LAKES STATIONS ONLY; NOAA requires local standard time, which this tool applies automatically. Max 10 years.
daily_max_min: daily maxima/minima from hourly and 6-minute data with completeness percentages. Max 10 years.
monthly_mean: monthly tidal datum means (columns MHHW, MHW, MSL, MTL, MLW, MLLW, DTL, GT, MN, DHQ, DLQ, HWI, LWI, highest, lowest). Max 200 years — ideal for long-term climatology.
Use for: historical extremes, mixed-tide analysis (HH vs H), long-term averages. For raw time series use noaa_get_water_levels; for future tides use noaa_get_tide_predictions.
| Name | Required | Description | Default |
|---|---|---|---|
| date | No | Shortcut window: "today" = midnight to now, "latest" = single most recent reading, "recent" = last 72 hours. Mutually exclusive with begin_date/end_date/range. | |
| datum | No | Vertical reference datum for heights. MLLW is the standard chart datum for coastal stations. IGLD and LWD apply to Great Lakes stations ONLY; NAVD/CRD exist only at stations where computed. Check a station's supported datums with noaa_get_station_datums. | MLLW |
| range | No | Number of hours. With begin_date: hours forward. With end_date: hours back. Alone: hours back from now. | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| product | Yes | Summary product: high_low (daily tide extremes, 1yr max), daily_mean (Great Lakes only, 10yr), daily_max_min (10yr), monthly_mean (datum means, 200yr). | |
| station | Yes | Station ID. Water-level/met stations use 7-digit numeric IDs (e.g. "9414290" San Francisco); current stations use alphanumeric IDs (e.g. "cb0102"). Find stations with noaa_search_stations or noaa_find_nearest_stations. | |
| end_date | No | End date/time. Same formats as begin_date. | |
| time_zone | No | Time zone for timestamps: gmt = UTC, lst = station local standard time (no DST), lst_ldt = station local time with DST. Note: daily_mean data requires lst. | lst_ldt |
| begin_date | No | Start date/time. Formats: yyyyMMdd, "yyyyMMdd HH:mm", MM/dd/yyyy, or ISO yyyy-MM-dd[THH:mm]. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds critical behavioral context: per-product request limits (1 yr for high_low, 10 yr for daily_mean/daily_max_min, 200 yr for monthly_mean), the Great Lakes-only constraint for daily_mean, and automatic application of local standard time. 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 efficiently structured: a lead sentence, bullet points for each product, and a concise usage line at the end. Every sentence adds value without redundancy. It is about 7 lines, front-loading key actions and constraints.
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 complexity (10 parameters, no output schema), the description is remarkably complete. It covers all product types with time limits, station applicability, datum nuances, and references to sibling tools for alternatives and supporting info (e.g., noaa_get_station_datums for supported datums). Handles edge cases like Great Lakes-only and mandatory mode for daily_mean.
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 100%, so baseline is 3. However, the description adds significant value beyond schema: it explains each product option in detail, caveats for datum types (e.g., IGLD/LWD Great Lakes only, NAVD/CRD only where computed), and clarifies that daily_mean requires lst which the tool handles automatically. This elevates the score.
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 retrieves summary water-level products from NOAA stations, listing four specific product types with detailed explanations (high_low, daily_mean, daily_max_min, monthly_mean). It distinguishes from sibling tools by specifying when to use noaa_get_water_levels and noaa_get_tide_predictions instead.
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?
Explicit usage guidance is provided: 'Use for: historical extremes, mixed-tide analysis (HH vs H), long-term averages.' It also directs users to alternatives: 'For raw time series use noaa_get_water_levels; for future tides use noaa_get_tide_predictions.' This clearly defines when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
noaa_search_stationsSearch NOAA StationsASearch the NOAA CO-OPS station directory by capability type, name, and/or state.
Filter with:
type: what the station does (waterlevels, tidepredictions, currents, currentpredictions, met, ...) — pick the type matching the data you plan to request.
name: case-insensitive substring ("San Francisco", "Boston").
state: two-letter code ("CA", "MA").
Returns id, name, location, tide type, Great Lakes flag, and for prediction stations whether they are reference (R, harmonic) or subordinate (S, offset-based — hilo predictions only). Results are paginated (limit/offset). For proximity search by coordinates use noaa_find_nearest_stations instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Case-insensitive substring of the station name. | |
| type | No | Station capability filter. Common: "waterlevels" (active water level), "tidepredictions", "currents" (observed currents), "currentpredictions", "met" (weather sensors). Full list via noaa_get_reference_guide topic "station_types". | |
| limit | No | Maximum stations to return. | |
| state | No | Two-letter US state/territory code, e.g. "CA". | |
| offset | No | Pagination offset. | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations, the description discloses return fields (id, name, location, tide type, Great Lakes flag, prediction station type), pagination behavior (limit/offset), and response format option. No contradiction 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?
Concise 6-sentence description, front-loaded with main purpose, then structured clearly with bullet-like details. No unnecessary words, every sentence adds value.
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?
Complete for a search tool: covers all filters, pagination, output fields, and differentiates from siblings. No output schema needed as description sufficiently explains returns.
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 100%, but description adds significant meaning: explains type common values, clarifies name as case-insensitive substring, state shows examples, response_format explains output formats. Complements schema well.
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 it searches NOAA stations by type, name, and state, with specific verb 'Search'. It distinguishes from sibling tool noaa_find_nearest_stations by mentioning proximity search as an alternative.
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?
Explicitly says when to use this tool (search by capability type, name, state) and when not (proximity search, use noaa_find_nearest_stations). Suggests picking the type matching the data planned, providing clear usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
nws_get_marine_forecastGet Marine Text Forecast (NWS)AGet the official NWS Coastal Waters Forecast (CWF) narrative for the marine zone covering a latitude/longitude — day-part wind/seas text ("SE winds 10 to 15 kt... Bay waters choppy"), including Small Craft Advisories.
The point must lie in (or very near) US coastal waters; CWF zones extend roughly 20-60 NM offshore. Returns the zone's segment from the latest bulletin plus the office-wide synopsis.
For numeric hourly wind values use nws_get_wind_forecast; for observed wind at a NOAA station use noaa_get_meteorological_data (product "wind").
| Name | Required | Description | Default |
|---|---|---|---|
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, and non-destructive behavior. The description adds beyond this: it explains that the tool returns the zone's segment from the latest bulletin plus the office-wide synopsis, includes Small Craft Advisories, and works only for coastal US waters. No contradictions.
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 concise at six sentences, each serving a purpose: stating the action, scope, return content, and explicit alternatives. No filler or repetition, information is efficiently front-loaded.
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 complexity (mapping point to marine zone, returning narrative), the description covers key aspects: what is returned, geographic limitation, and alternatives. Lacks explicit mention of error cases or prerequisites, but overall it provides sufficient context for correct invocation 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 100% with clear parameter descriptions. The description adds value by explaining how the provided lat/lon maps to a marine zone and what the response contains (day-part wind/seas text, Small Craft Advisories). This contextualizes parameters beyond the schema, particularly the response_format purpose.
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 retrieves the official NWS Coastal Waters Forecast narrative for a given point. It specifies the resource (CWF), verb (get), and includes sample output. It distinguishes from siblings by naming nws_get_wind_forecast and noaa_get_meteorological_data as alternatives, making the purpose unambiguous.
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 provides explicit guidance on when to use this tool (for narrative marine forecast) and when not to (for numeric wind or observed wind), naming specific alternatives. It also notes geographic constraints (point must be in US coastal waters, zone extends 20-60 NM offshore), offering clear context for appropriate use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
nws_get_wind_forecastGet Wind Forecast (NWS)AGet the NWS hourly wind FORECAST (speed, gust, direction — plus wave height where the grid carries it) for a latitude/longitude.
Data comes from the NWS forecast grid (api.weather.gov gridpoints — numeric NDFD values, not display strings). Horizon is up to ~7 days (156 hours), starting at the current hour. US and territories only. Wave height appears for marine/nearshore gridpoints; swell/period fields are typically only populated for open-ocean points.
Units: english = knots and feet (default), metric = m/s and meters. Direction is degrees true, the direction the wind blows FROM.
This is FORECAST data. For observed (measured) wind at a NOAA station right now, use noaa_get_meteorological_data (product "wind"). For the official marine text forecast (Coastal Waters Forecast narrative with small-craft advisories), use nws_get_marine_forecast.
| Name | Required | Description | Default |
|---|---|---|---|
| hours | No | Forecast hours to return, starting at the current hour (max 156 ≈ 7 days; the grid may end sooner). | |
| units | No | Unit system. english: feet, °F, knots (wind AND currents), nautical miles. metric: meters, °C, m/s for wind but cm/s for currents, kilometers. Air pressure is millibars and salinity is PSU in BOTH systems. | english |
| latitude | Yes | Latitude in decimal degrees (-90 to 90). | |
| longitude | Yes | Longitude in decimal degrees (-180 to 180). | |
| response_format | No | Output format: "markdown" for a readable summary table, "json" for the complete structured payload. | markdown |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds valuable context: data source, numeric NDFD values, wave height availability, units explanation, and direction convention. This goes beyond annotations but could be even more specific about output structure.
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 well-structured with clear sections. It front-loads the main purpose, then adds details on data source, units, horizon, and alternatives. Every sentence is informative with no redundancy.
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?
The tool has no output schema, so the description must cover return values. It describes the general content (speed, gust, direction, wave height) and explains the response_format parameter. While it mentions markdown as a summary table and json as payload, a bit more detail on the json structure could improve completeness.
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 100% schema coverage, baseline is 3. The description adds meaning: explains how 'hours' starts at current hour, clarifies units for wind (knots vs m/s), and mentions wave height conditions. This enhances understanding beyond the schema's own descriptions.
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 explicitly states the tool retrieves NWS hourly wind forecast (speed, gust, direction, wave height) for a lat/lon. It distinguishes from sibling tools by specifying alternatives for observed wind (noaa_get_meteorological_data) and marine text forecast (nws_get_marine_forecast).
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 provides clear when-to-use guidance (forecast data) and explicitly names two alternative tools for other use cases. It also notes geographic scope (US and territories) and horizon (up to ~7 days), helping the agent decide correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
perigee_whoamiWhich Perigee account is this connection using?AShow how this MCP connection is authenticated: the Perigee account it is linked to (if any), how it signed in (OAuth connector or API key), its rate-limit tier, and the requests-per-minute limit. Use when the user asks which account they're connected as, why they're rate limited, or whether their sign-in worked.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's disclosure that it 'shows' authentication details is consistent. It enriches transparency by listing the specific output fields (account, sign-in method, rate-limit tier, requests-per-minute), which is useful and goes beyond the annotation structure.
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?
Two sentences, no wasted words. The first sentence defines functionality, the second gives usage guidance. Perfectly front-loaded and concise.
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 parameters and no output schema, the description fully covers what the tool does and what it returns. There is no missing context for an agent to successfully invoke this tool.
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 tool has zero parameters, and schema coverage is 100%. According to guidelines, baseline is 4. The description does not need to add parameter information, and it doesn't contradict anything. The value is already clear.
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 verb 'show' and the resource 'authentication details of the MCP connection', specifying exactly what is returned (account, sign-in method, rate-limit tier, requests-per-minute). This distinguishes it from sibling tools which are all astronomical or NOAA-related, so no confusion.
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 explicitly provides three use cases: 'when the user asks which account they're connected as, why they're rate limited, or whether their sign-in worked.' While it lacks 'when not to use' or alternatives, the tool is unique enough that this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Sign in to create a connector for this server.