noaa-marine-mcp-server

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it explains the distinction between data capabilities and physical platform (the two axes), notes that CO-OPS current stations are cataloged by monitoring capability, and warns about no_predictions from noaa_marine_get_currents. This is substantive, though it does not disclose rate limits or pagination details, which are minor for a read-only search 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?

The description is slightly long (about 200 words) but each sentence contributes unique information—ID formats, axes, search requirements, and the no_predictions note. It is front-loaded with the primary purpose and then provides necessary technical specifics. No redundant statements; it earns a 4 for being structured and efficient despite its length.

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 8 parameters, an output schema, and multiple search modes, the description is remarkably complete. It covers the two filtering axes, the source-specific behavior, the ID formats, and the prerequisite nature for other data tools. Since an output schema exists, it doesn't need to detail return values, and it doesn't. Nothing critical is missing for correct invocation.

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 meaning beyond the schema: it clarifies that 'state' applies only to CO-OPS stations (excluding NDBC), that the 'buoy' type filters by physical platform rather than data capability, and that latitude/longitude must be provided together. This helps the agent avoid common parameter misuse, 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 states a specific verb ('Find') with a clear resource ('CO-OPS tide/water-level/current stations and NDBC buoys') and distinguishes it from sibling data tools by noting it is the 'required first step to resolve place names or coordinates to station IDs before calling data tools.' It also clarifies the unified station list content, making the tool's role 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 explicitly states when to use this tool: 'This is the required first step... before calling data tools.' It also gives practical guidance on search modes ('Provide latitude and longitude together for proximity search, or query/state for name-based search'), and mentions the fallback behavior when no_predictions are encountered. This goes beyond implicit usage and clearly routes the agent.

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

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

Annotations declare readOnlyHint=true and openWorldHint=true; the description adds significant behavioral context: unit conventions (SI except TIDE/VIS), the possibility of null values as normal (sensor non-reporting), the ~10-minute update cadence with potential 10–20 min staleness, and the note that many NDBC stations lack data. No contradiction and rich 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?

The description is structured logically: core data first, then units, then nulls and staleness, then usage guidance. Every sentence contributes new information—no filler. It is appropriately sized for the tool's complexity and front-loads the most critical facts.

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 an output schema (so return structure is documented elsewhere) and one parameter with full schema coverage, the description comprehensively covers the non-obvious context: unit exceptions, null behavior, freshness, and station-finding prerequisites. An agent can call this tool correctly with no gaps.

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 single parameter station_id has complete schema coverage (100%), so the baseline is 3. The description reinforces the schema's guidance by explaining how to obtain valid station IDs via the find tool and why 'met' type matters, adding practical value beyond the schema alone.

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 states a specific verb ('get'), a specific resource ('live marine conditions from an NDBC buoy'), and enumerates the exact measurements returned. It clearly differentiates from siblings by its focus on real-time buoy observations rather than forecasts or other marine 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?

It explicitly instructs to first use noaa_marine_find_stations with source='ndbc' and types=['met'] to obtain station IDs, and warns that omitting the types filter will yield IDs this tool cannot read. This gives clear when-to-use guidance and a key prerequisite, leaving no room for misinterpretation.

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

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

Goes well beyond annotations (readOnlyHint, openWorldHint) by detailing return units (depth in meters, direction in degrees true, speed in cm/s), null behavior when sensor components are missing, and the fact that depth bins are reported only when NDBC provides a depth. These behavioral details are crucial for correct interpretation and are not present in 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 sentences and dense with information: core purpose, measurement details, distinction from sibling, null handling, and lookup instructions. It is front-loaded with the most important facts and contains no filler.

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 all essential aspects: purpose, return fields and units, distinction from the closest sibling, null semantics, and station discovery method. With an output schema present (as indicated), the return shape is already documented, so nothing critical is missing.

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 reinforces the station_id origin and adds a caution about unfiltered find_stations queries returning incompatible IDs. While this is more usage guidance than new parameter format, it is actionable and directly tied to the parameter, justifying 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?

States a specific verb+resource: 'Observed ocean-current depth profile from an NDBC ADCP buoy' and specifies it returns the most recent measurement of speed and direction at each depth bin. Explicitly distinguishes from noaa_marine_get_currents (tidal predictions), making the tool's unique 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?

Provides explicit when-to-use guidance: contrasts with noaa_marine_get_currents and directs the user to noaa_marine_find_stations with source='ndbc' and types=['current_profile'] to obtain compatible station IDs. Also warns that unfiltered searches yield unusable IDs, which is a clear usage constraint.

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

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

Annotations already establish readOnlyHint, openWorldHint, and idempotentHint. The description adds valuable behavioral context beyond that: it specifies the data source (CO-OPS forecast predictions, not observations), the 1-year date range limit, and warns that current station IDs are alphanumeric and distinct from numeric tide/water-level IDs. 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 dense but every sentence contributes value: core capability, sibling distinction, default interval rationale, optional detail mode, station ID caveat, and date limit. It is front-loaded with the primary purpose and flows logically, with no fluff or 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 presence of an output schema (which covers return values) and the rich annotations, the description covers all essential context: data source (CO-OPS forecast vs observations), how to obtain valid inputs (find_stations), key constraints (1-year limit, station ID format), and the distinction from sibling tools. An agent has everything needed to decide when and how to 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?

Schema documentation covers all 6 parameters with descriptions, enums, defaults, and patterns (100% coverage), so the baseline is 3. The description supplements this by clarifying the station_id format (alphanumeric, distinct from numeric IDs) and noting the 1-year date range constraint, which helps agents understand the scope of begin_date/end_date beyond what the schema states.

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 provides tidal current predictions for a CO-OPS station, listing the specific outputs (max flood/ebb speeds, slack times, directions). It also explicitly names the sibling noaa_marine_get_current_profile and contrasts it (NDBC observed ocean-current measurements, depth-binned), so an agent can immediately distinguish the two without inspecting their schemas.

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 directs users to noaa_marine_find_stations for obtaining valid station IDs and highlights the difference from noaa_marine_get_current_profile for observed data. It also explains when to use the default MAX_SLACK interval (planning view) versus the optional 6-minute continuous predictions (detailed analysis), providing clear context for choosing this tool over alternatives.

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

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

Annotations already declare readOnlyHint and openWorldHint, but the description goes further, disclosing that unreported values come back null (not zero), that lat/lon are null when a station is absent from the active list, and that sensor coverage is sparse. It also specifies the error condition. 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 long but each sentence earns its place, covering purpose, distinctions, data behavior, and failure modes. It is front-loaded with the core purpose and follows a logical structure, though slightly dense.

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 presence of an output schema (so return values do not need describing), the description covers data list, null-handling policy, coordinate behavior, station coverage caveats, and error handling. It also connects to sibling tools. Nothing essential is missing for an agent to call this 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% and the schema itself provides a detailed station_id description with pattern and example. The tool description supplements this by explaining that station IDs should be sourced from find_stations and that coverage is not guaranteed, adding practical context 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 states a specific verb-resource pairing: 'Live sub-surface oceanographic observations from an NDBC station's water-quality sensors.' It enumerates the data types returned and explicitly contrasts with the sibling noaa_marine_get_conditions, leaving no ambiguity about what the tool does.

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?

Gives explicit when-to-use guidance: 'use this tool for what the water is doing below the surface, that one for weather and sea state at the buoy.' Also instructs how to obtain candidate IDs via noaa_marine_find_stations with source="ndbc" and warns that many stations will produce an observations_not_found error. This thoroughly differentiates from alternatives.

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

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

Annotations already carry readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds valuable non-obvious behavior: the 1-year request cap, the hilo vs 6min return granularity, the H/L tide-type coding, and the MLLW datum default rationale. No contradiction with annotations — 'predictions' aligns with readOnly semantics.

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, front-loaded with the core purpose, then layering return format, datum, constraints, and routing. Dense but each sentence earns its place — the only minor issue is the paragraph wall could use slight structural separation, but nothing is wasted.

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 7-parameter tool with a rich schema and an output schema (so return values need not be spelled out), the description covers the critical operational constraints: date-range cap, interval modes, datum meaning, and the prerequisite station-ID resolution. Moderately complex tool, and nothing an agent needs to call it correctly is missing.

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 detailed per-parameter descriptions and enums, so the schema carries the load — baseline 3 is appropriate. The description does add a touch of context (MLLW as US chart datum, hilo vs 6min behavior), but these largely echo the schema's own parameter descriptions, so marginal value above 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?

States a specific verb+resource: 'High/low tide predictions for a CO-OPS tide station over a date range.' It clearly differentiates from siblings by naming the data type (tides) and the station source (CO-OPS), letting an agent distinguish it from get_water_level, get_currents, and get_conditions without opening schemas.

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?

Gives explicit pre-usage routing: 'Use noaa_marine_find_stations first to resolve a station name or location to a numeric station ID.' Also flags the 1-year date-range limit and directs splitting longer ranges. It lacks explicit when-not-to-use guidance versus the water_level sibling, but the resolution step and limit are clear, actionable context.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, so safety is covered. The description adds valuable behavioral details: 6-minute observation/prediction interval, the residual calculation (observed−predicted) and its interpretation for surge/drawdown, and the date range limit. These go well beyond the annotations and enrich agent understanding.

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 compact—four sentences that sequentially cover purpose, key output feature, constraint, and prerequisite. Every sentence earns its place, and the most important information (what it does) is 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 moderate complexity and that an output schema exists, the description covers all necessary operational aspects: station resolution, date limits, output granularity, and interpretation of residuals. Nothing critical for successful invocation is missing.

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%, so all parameters are documented (e.g., datum meanings, units, time zones). The description adds no new parameter-specific semantics; its mention of station_id from find_stations duplicates the schema. However, it does contextualize the date parameters with the 31-day limit, which provides slight value beyond the raw 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 a specific resource (CO-OPS water-level station), the data type (observed water level), and the paired predictions, which distinguishes it from siblings like get_conditions or get_tide_predictions. The mention of residual analysis adds specificity to what the tool returns.

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 instructs to use noaa_marine_find_stations first, which is a clear prerequisite and usage guideline. It also provides the 31-day date range constraint and advises splitting longer ranges. However, it does not explicitly contrast with alternative tools like get_tide_predictions, though the purpose clarity covers that implicitly.

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