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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new operational context: the values are 'Computed locally — no NOAA data involved,' which tells the agent not to expect a NOAA dataset lookup or external calls, plus the exact fields returned.

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 first sentence is front-loaded and efficient, and the second paragraph delivers a compact domain hint. The enumeration of return fields overlaps with the existing output schema and is the only mildly expendable part.

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 an output schema present, the return-value list is optional, and the description still covers range behavior, local computation, and tide interpretation. It would be complete if it acknowledged the sibling for 'next' phase queries or clarified the latitude/longitude role.

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 the baseline is 3; the schema already documents date format, end_date range semantics, lat/long bounds, and the response_format enum. The description adds only the day-by-day range behavior, and never explains what latitude/longitude actually change (topocentric vs geocentric precision).

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 (moon phase for a date/range) and enumerates the returned quantities, and the 'each day of a date range if end_date is given' clause implicitly separates it from astro_get_next_moon_phase. It stops short of naming that sibling, so the differentiation is inferred rather than 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?

Usage is implied by the date/range framing (use it for a specific day or a span), but there is no explicit when-to-use/when-not guidance and no mention of the alternative astro_get_next_moon_phase for forward-looking queries. The tide-context paragraph explains relevance but not tool selection.

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, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds domain context (spring tides lag new/full moons by 1-2 days) but says nothing about defaults, the 24-count ceiling, computational behavior, or edge cases beyond what annotations provide.

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 tight sentences: the core action is front-loaded, followed by a compact 'Use for' block with zero redundancy. Every clause 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?

With a full input schema, an output schema, and complete annotations, the description needn't explain parameters or return values, and it doesn't overreach. The only shortfall is the missing sibling differentiation from astro_get_moon_phase, which is a modest gap for a simple read-only 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 description coverage is 100% and an output schema exists, so both phases, the date default, the count bounds, and response_format are already documented structurally. The description only loosely echoes these via 'date(s)' and 'occurrence(s)', adding no syntax or format detail beyond the schema. Baseline 3 applies.

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 and resource: finding the date(s) of the next occurrence of a named principal moon phase from a start date, enumerating the four phases. This is clear and actionable, but it never distinguishes itself from the sibling astro_get_moon_phase (likely current-phase), leaving the agent to infer the difference.

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 'Use for:' line gives concrete triggering questions ('when is the next full moon?') and a planning scenario (spring tides following new/full moons by 1-2 days). However, no when-not-to-use guidance or explicit alternative (e.g., use astro_get_moon_phase for the current phase) is provided.

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, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds only the forward-searching notion of 'next occurrence(s)', and says nothing about timezone defaulting or how count interacts with the starting date. Adequate but thin beyond structured fields.

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?

Front-loaded with the core purpose in the first clause, and the usage examples come second. The inline enumeration of all thirteen event names is somewhat redundant given the schema enum and costs length, but it is at least a single readable block rather than padding.

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 an output schema present, annotations covering safety, and 100% schema description coverage, the description only needs to establish purpose and domain, which it does. The missing piece is routing versus astro_get_sun_times/astro_get_sun_position, which is a real but modest gap for a 7-parameter read-only query 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 description coverage is 100% with bounds, defaults, enum values and formats all documented inline, so the baseline is 3. The description's one added nuance, that date is a 'starting date' for a forward search, is already conveyed by the parameter description ('Search start date'), so it adds little.

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 ('Find') and resource ('next occurrence(s) of a sun event') and enumerates all thirteen event values, so the agent knows exactly what domain this covers. However, it never distinguishes itself from the very similar sibling astro_get_sun_times (all sun events for a day) or astro_get_sun_position, so the boundary between 'next event' and 'sun times' is left to inference.

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 'Use for:' line gives concrete triggering scenarios ("when is sunset today?", golden-hour photography, dawn fishing around tide windows) and even links it to the NOAA tide siblings. It provides clear positive context but no exclusions or disambiguation against astro_get_sun_times, which is the closest competing tool.

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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: computation is done locally with suncalc and declination/right ascension are approximate, which tells the agent how much to trust the values.

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 short sentences, front-loaded with the purpose and the returned values, then the usage line and caveat. No filler and no repetition of what the schema already says.

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 a rich output schema, full parameter coverage, and strong annotations, the description only needs to add what those fields cannot. It does that with the local-computation note and the approximation caveat; the remaining omission (date/time defaults, timezone) is already documented in the 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 description coverage is 100%, so the schema already documents date, time, latitude, longitude, and response_format in detail. The description adds only the vague "azimuth ... as rendered here" convention note and the approximation caveat, which barely extends the schema. 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?

States a specific verb and resource ("Get the sun's position") and enumerates the returned quantities: azimuth, altitude, declination, right ascension. It is clearly distinct from siblings like astro_get_sun_times or astro_get_next_sun_event, but it never names or contrasts those siblings explicitly.

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?

"Use for: shadow/lighting analysis, solar exposure" gives concrete contexts where this tool is the right pick, which is more than implied usage. However, it offers no exclusions or pointers to the related sun-time tools, so an agent must still infer the boundary cases.

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 cover readOnly/idempotent/non-destructive, so the description is freed to add real behavioral context: output is ISO UTC unless an IANA timezone is supplied, high-latitude events may be null (no astronomical night in summer), and computation is done locally. That null-handling note is exactly the kind of edge case an agent needs and is not derivable from 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?

Two tightly packed sentences: the first front-loads the returned events and the range behavior, the second front-loads timezone semantics and the high-latitude null caveat. No filler, no restatement of the title.

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 an output schema present, the description need not explain return values, yet it still usefully flags the timezone-dependent format and the possibility of nulls. Combined with 100% schema coverage and full annotations, an agent has everything required 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%, so every parameter including date, end_date, timezone, and response_format is already documented in the schema. The description's timezone sentence reinforces the schema's default behavior but adds no new syntax or format detail. Baseline 3 is appropriate when the schema carries the parameter burden.

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 ('Get') and resource ('sun times') and enumerates the exact events returned (sunrise, sunset, solar noon, dawn/dusk variants, golden hour, day length). This distinguishes it from siblings like astro_get_next_sun_event and astro_get_sun_position, which return a different slice of solar 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?

The description implies usage via the 'for a location and date (or each day of a range if end_date is given)' clause, which tells the agent how to get single vs. multi-day output. However, it never names when to prefer astro_get_next_sun_event or astro_get_sun_position instead, so the agent must infer the boundary from the sibling names.

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 readOnly, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds real context beyond that: distance is great-circle (Haversine) reported in km and miles, and the tool relies on a cached directory because NOAA's API has no native coordinate search. No rate-limit or freshness caveats, but the added context is meaningful.

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 tight paragraphs, each front-loaded: scope first, then usage/workflow, then the implementation note. No sentence is filler — every one adds routing, prerequisite, or distance-semantics 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?

With an output schema present, return values need no explanation, and the annotations carry the safety profile. The description covers scope, prerequisites, sibling routing, and distance computation, which is everything needed to invoke the 6-parameter 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 coverage is 100%, so the baseline is 3. The description goes further by explaining the filter-by-type workflow and flagging a genuine semantic subtlety: current stations have different IDs than water-level stations, which the schema does not convey.

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 (find), resource (NOAA stations), and scope (nearest to a lat/lon, sorted by distance). The coordinate-based scope implicitly distinguishes it from the name-based noaa_search_stations sibling, though it never names that sibling explicitly to sharpen the contrast.

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 an explicit trigger scenario ('what's the tide station near <place>?'), a prerequisite workflow (geocode the place first), and routing guidance to sibling tools ('type "tidepredictions" before calling noaa_get_tide_predictions, "currents" before noaa_get_currents'). When and how to use it are left to nothing.

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 cover the read-only/idempotent/non-destructive profile, so the description's value is the added context: per-request span caps (1 year vs 31 days), the unit-system inconsistency (knots vs cm/s), and the sign convention for Velocity_Major. It does not address error behavior or rate limits, keeping it short of a 5.

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?

Front-loaded with the core purpose, then organized into interval, units, and vel_type blocks with a capitalized UNITS WARNING that is easy to scan. Dense for its length but no sentence is 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?

For an 11-parameter tool the description covers the consequential knobs (interval, units, vel_type, station type) and an output schema exists so return values need no explanation. It stops just short of full completeness by not contrasting against the observed-currents sibling.

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 already documents interval spans, units, vel_type sign conventions, and station ID formats, so the description largely restates structured data. The only genuinely additive semantic is 'recommended for navigation' on max_slack; baseline 3 applies when the schema does the heavy lifting.

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 and resource — 'Get predicted tidal currents for a NOAA current prediction station' — and the word 'predicted' implicitly separates this from the observed-data sibling noaa_get_currents. An agent can identify the tool's scope without opening the schema.

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 real usage context: interval="max_slack" is 'recommended for navigation', and subordinate (type 'S') stations route to noaa_get_prediction_offsets. It does not, however, explicitly state when to prefer this over noaa_get_currents or noaa_get_tide_predictions, so it is clear on context but silent on exclusions.

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 the safe read-only/idempotent/openWorld profile, so the bar is lower; the description still adds real behavior beyond them: a hard max of 7 days per request, the meaning of expand_detailed, and the per-record return shape. It does not mention any auth/rate-limit constraints, but for a read-only NOAA endpoint those are minor.

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?

Front-loaded with the core verb+resource, then station-ID guidance, then the units warning in caps where it's most likely to be missed. Every sentence carries actionable information with 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?

An output schema exists so return values needn't be documented, yet the description still enumerates the per-record fields (t, s, d, b) and the diagnostics toggle. Together with station-finding guidance, units, and the 7-day bound, an agent has everything needed to invoke it 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%, so baseline is 3, but the description adds value by surfacing a genuine trap the schema buries: metric currents are cm/s, not the m/s used for wind. It also reinforces the station-ID format distinction and the 7-day/expand_detailed semantics, slightly exceeding 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 ("Get observed current speed and direction") and immediately scopes it to NOAA current meter stations. It explicitly distinguishes current stations from the 7-digit water-level station IDs that sibling tools like noaa_get_water_levels use, so an agent can route correctly 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?

Tells the agent how to obtain valid station IDs via noaa_search_stations (type "currents") or noaa_find_nearest_stations, and flags the 7-day cap. It stops short of an explicit when-to-use-this-vs-noaa_get_current_predictions statement, but "observed" vs. predicted is strongly implied.

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 this a safe, idempotent, read-only, open-world read, so the safety burden is lifted. The description adds genuine behavioral context beyond that: the statistics are computed from the station's verified record and are relative to the station's datums for the 1983–2001 epoch, plus the long-record availability constraint.

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 short paragraphs, front-loaded with the core deliverable and then the routing cue and availability caveat. Every sentence carries information; nothing is redundant with the name or schema.

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?

An output schema exists, so return values need not be explained. The description covers the key preconditions (long-record station) and the epoch/datum framing, leaving little an agent needs before invoking it; only the absence of explicit sibling routing keeps it just below 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?

Schema description coverage is 100%, so the schema already documents units, station, levelType, extremeType and response_format, including enums. The description adds no extra syntactic or default information about these parameters, so baseline 3 applies.

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 and resource ('extreme water level exceedance statistics for a station') and spells out the returned content: annual exceedance probability levels like the 1%-annual-chance 100-year level plus historical extreme events. This clearly separates it from siblings such as noaa_get_top_ten_water_levels 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?

Gives explicit usage context ('Use for flood risk questions...') and states a precondition/exclusion ('Only long-record stations have this product'). It does not name an alternative sibling for closely related risk products like noaa_get_high_tide_flooding or sea-level-rise tools, so it falls short of the 5 bar.

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, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: that constituent availability depends on station type (only R stations), that current stations require bin filtering, and what the returned quantities mean physically (current ellipses, degrees/hour speed).

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?

Front-loaded with the core purpose and the constituent list, then the station-specific data shapes, then usage. Three short paragraphs, each earning its place; minor redundancy with schema-documented unit and format details.

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?

An output schema exists, so return-value documentation is not required, and annotations cover safety. The description supplies the remaining decision-relevant context: station-type dependence, the R-vs-subordinate distinction, and the alternative tool for subordinate stations. Nothing needed to invoke 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%, so the baseline is 3, and the description marginally exceeds it by explaining that bin only applies to current stations and that station IDs split into numeric water-level IDs versus alphanumeric current IDs. Most of the units/station/format detail is duplicated from the schema, keeping it below a 5.

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?

Names a specific verb+resource (get harmonic constituents) and immediately scopes the result: amplitude, phase, and angular speed of each tidal constituent. It distinguishes the two station flavors (water-level vs. current stations, with current ellipses per depth bin), so an agent can tell what it will get before opening the schema.

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 an explicit 'Use for:' list (custom tide computations, dominant-constituent checks, verifying harmonic prediction status) and an explicit exclusion: only reference (R) stations have constituents, while subordinate stations must use noaa_get_prediction_offsets. That is a direct when-to-use / when-to-use-something-else routing statement.

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 cover the read-only/idempotent safety profile, and the description adds genuine operational context beyond them: the per-report filter requirements (daily REQUIRES start_date/end_date; year/month/season_months vs range semantics) and the station-availability caveat. It stops short of describing output shape, but output schema exists so that is 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?

Front-loaded with the core statement, then a scannable bulleted mapping of reports to filters, then a short 'Use for' block. It is long, but for a 10-mode report selector nearly every line carries distinct decision-relevant content; only minor redundancy in restating the daily date requirement.

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 12-parameter, multi-mode tool with an output schema, the description covers mode selection, per-mode required filters, and the station prerequisite. 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% so baseline is 3, but the description adds real meaning by mapping each filter to the reports it applies to (year for monthly/seasonal/annual/record_days, decade and flood_threshold for projections/likely_scenarios, met_year for met_year_annual/annual_outlook). This goes beyond the per-parameter schema text.

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?

Names a specific verb and resource (NOAA high tide flooding statistics for a station) and enumerates the report modes, which is exactly what separates it from siblings like noaa_get_sea_level_rise_projections or noaa_get_tide_predictions. An agent can identify the tool's scope without opening the schema.

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 states when to use it ("how often does X flood?", nuisance-flood trends, future projections) and adds a concrete prerequisite: not all stations have HTF products, check the HTFhistorical flag via noaa_get_station_info. Both the use case and the routing to a sibling tool are given.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds real operational context beyond that: a ~31-day max span per request, interval semantics, and the fact that sensor availability varies by station. It does not discuss rate limits or auth, but for a read-only tool this is a strong supplement.

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?

Front-loaded with purpose, then products, then units, then constraints and sibling routing — a logical order with no filler sentences. It is somewhat long and the units block partially restates the schema, but every paragraph carries usable content for a 10-parameter 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?

An output schema exists, so return-format detail is not required in the description. Given that, the description covers products, defaults (interval 6-minute, units english), span limits, station-ID conventions, and sibling routing — everything an agent needs to 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 description coverage is 100%, so the baseline is 3. The units-by-system paragraph adds cross-product coherence, but the same mappings (temps, wind, air_gap, visibility, pressure always millibars, salinity always PSU) already appear in the schema's units enum description, so the incremental value is limited rather than zero.

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 ('Get observed meteorological/oceanographic sensor data from a NOAA station') and enumerates the exact products returned. It explicitly distinguishes itself from the closest sibling by noting water-level data belongs to 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?

Names alternatives and conditions: check noaa_get_station_info with sensors expanded before calling, find stations via noaa_search_stations or noaa_find_nearest_stations, and use noaa_get_water_levels for water-level data instead. Both when-to-use and when-not-to-use are explicit.

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 cover the safety profile (readOnly, idempotent, non-destructive), but the description adds real behavioral context: the empty/null result for R stations and the bin-indexed quirk for current offsets, plus the ratio-vs-fixed semantics of the height adjustment. Some overlap with return fields likely covered by the output schema keeps this from a 5.

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?

Content is front-loaded with the core definition followed by the tide and current breakdowns, and the critical edge cases (R stations, bin suffix) land at the end. The enumerated field lists are somewhat verbose, but each sentence carries usable 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?

For a small read-only lookup with an existing output schema, the description supplies everything an agent needs: purpose, the two kind modes, the station ID conventions, the bin edge case, and the empty-result behavior. Nothing essential 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 the baseline is 3, but the description goes beyond the schema by explaining what kind="tide" versus kind="current" actually returns and by documenting the station_bin_suffix ID form (e.g. "ACT0091_1") for the current case, which meaningfully clarifies the station parameter.

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 and resource with scope qualifier: returns the offsets a subordinate (type "S") prediction station applies to its reference station. It also distinguishes the two data variants (tide vs current offsets) and notes that reference (R) stations return empty, which differentiates it from sibling prediction tools like noaa_get_tide_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?

Clearly frames when the tool yields meaningful output (subordinate stations) and when it does not (reference stations return empty/null offsets), and gives an actionable fallback for current offsets via the station_bin_suffix ID form when the plain ID returns nothing. It stops short of naming a specific alternative tool for reference-station predictions, so routing is implied rather than explicit.

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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds that the content is curated reference material and enumerates topics, but does not disclose format, length, or other operational traits; with strong annotations, this is useful but not rich.

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?

Purpose is front-loaded, followed by a well-structured topic list where each bullet adds distinct selection value. No filler; appropriate length for a 10-topic reference 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 that output schema handles return values and annotations cover the safety profile, the description provides complete selection guidance for this reference tool. Nothing an agent needs to call the tool 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% and the single enum parameter is documented in the schema, but the description goes well beyond by explaining what each of the 10 topic values contains. This meaningfully improves topic selection.

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 ('Get') and resource ('curated reference documentation for NOAA CO-OPS concepts and parameters'), then makes the scope explicit by listing all covered topics. This is clearly distinct from the sibling data-retrieval tools.

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 when-to-consult guidance ('Consult this before constructing unusual requests') and highlights three high-value topics. It does not name alternatives or exclusions explicitly, so it falls short of a 5.

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 readOnly/idempotent/non-destructive, lowering the bar. The description adds real context beyond them: the projection source, decadal resolution, and 2150 ceiling. It stops short of noting auth, rate limits, or latency, so a 4 rather than a 5.

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?

Front-loaded with the core purpose and tightly structured across three sentences. The mid-sentence re-listing of scenario values duplicates the schema enum and is the one mildly redundant element.

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 zero-required read tool with a full output schema, the description supplies everything the agent needs: data provenance, temporal scope, units pointer, and routing to siblings. Return-value documentation is correctly left to the 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 description coverage is 100%, so the schema already documents station, units, scenario, and projection_year. The description largely restates the scenario enum and units handling rather than adding syntax or semantics the schema lacks. Baseline 3 applies.

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 ('Get NOAA's Interagency Sea Level Rise Scenario projections for a station') and pins down the data source (2022 technical report), temporal resolution (per decade), and horizon (through 2150). It clearly distinguishes itself from sea-level-trends (observed) and high-tide-flooding siblings.

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 names the use case ('coastal planning questions') with a concrete example query, and routes the agent to complementary tools (noaa_get_sea_level_trends for observed, noaa_get_high_tide_flooding for impact) with the condition that selects each. Nothing is left to inference.

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 read-only, idempotent, open-world behavior, so the description earns credit for adding domain context the annotations cannot: relative sea level conflates ocean rise with local subsidence/uplift, so sign and magnitude vary by station (Gulf Coast positive, Alaska negative), and a long record is required. The trendUnits field disclosure also pre-empts a real ambiguity.

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 tight paragraphs, front-loaded with the primary output (trend and error) before the domain caveat and the listing-mode note. Dense but every clause carries information; only the parenthetical unit aside is mildly redundant with the payload field it names.

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?

An output schema exists, so return-value enumeration is unnecessary, and the description still flags the trendUnits ambiguity an agent would otherwise misread. With annotations covering safety and schema covering parameters, an agent has everything needed to call this correctly in either single-station or list mode.

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 baseline is 3, but the description adds genuine semantics: omitting station switches the call into list-all mode, and affil then filters that network by US/Global. That is behavior beyond the schema's field-level 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?

States a specific verb and resource ('long-term relative sea level trend at a NOAA station') and enumerates exactly what comes back: trend value, error, observation period, seasonal amplitude. This clearly separates it from siblings like noaa_get_sea_level_rise_projections (future projections) and noaa_get_water_levels (instantaneous readings).

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 clear context: 'Requires a station with a long water-level record; omit station to list all,' and explains the affil filter's role. It stops short of naming alternatives (e.g. projections vs. trends) or stating exclusions, so it is a strong 4 rather than a 5.

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 cover the read-only/idempotent safety profile, and the description adds genuine value beyond them: the shared station-datum reference zero, the datum-to-datum subtraction formula, the caveat that 'superseded' is not available for all stations, and that historical extreme min/max include dates.

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?

Front-loaded with the core purpose and scoped with a colon into the datum list; the long enumeration is justified because it tells the agent exactly what is retrievable. The clause structure is dense but no sentence 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?

With an output schema present, return-format details are not required, and the description still covers the key behaviors an agent needs: epoch semantics, station-datum reference zero, conversion formula, and availability caveats. Nothing material 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 the baseline is 3; the description still adds meaning, notably the semantics of epoch ('current' = present NTDE 1983–2001; 'superseded' = prior epoch) and the caveat that not all stations have a superseded epoch, which goes beyond the schema's terse enum note.

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?

Specific verb+resource ('get the accepted tidal datum values for a station') with an explicit enumeration of the datums returned (MHHW, MHW, MTL, MSL, etc.). This distinguishes it clearly from siblings like noaa_get_station_info (metadata) and noaa_get_water_levels (observations).

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 two explicit use cases: (1) check which datums a station supports before requesting data, and (2) convert heights between datums. Clear context, though it does not name a specific alternative tool or state exclusions (e.g., when to use harmonic constituents or prediction offsets instead).

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, idempotentHint, openWorldHint, and destructiveHint=false, covering the safety profile. The description adds behavior beyond that: it explains that expand availability varies by station type and distinguishes water-level sub-resources from current-station sub-resources (bins, deployments), which helps set expectations.

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 front-loaded with the tool's purpose, then uses a compact bullet list to unpack the expand options, and closes with usage routing. Despite its length, every section earns its place for a tool with nine expandable sub-resources.

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 that output_schema exists and annotations cover safety, the description only needs to cover purpose, usage, and parameter meaning. It does all three, including distinguishing station types and routing to alternative tools, so an agent has enough to call it 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%, so the baseline is 3. The description adds substantial meaning for the 'expand' parameter by defining each enum value (details dates, sensors with elevations, floodlevels thresholds, etc.) and tying sub-resources to station types—information not present in the schema's terse expand 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 states the specific verb ('Get') and resource ('a NOAA station's full metadata record') and enumerates the fields returned. It distinguishes the tool from siblings by directing datum requests to noaa_get_station_datums and harmonic constituent requests to noaa_get_harmonic_constituents.

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 gives explicit context: 'Use this before requesting data to confirm what the station actually collects,' and names the correct alternative tools for datum values and harmonic constituents. The expand parameter is framed as optional and its availability varies by station type, so an agent knows when to invoke it.

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, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description still adds genuinely useful non-obvious behavior: predictions are astronomical only and exclude storm surge/wind setup, Great Lakes stations are unsupported, and subordinate stations are hilo-only. Return format and pagination behavior are not discussed, but the output schema exists.

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?

Front-loaded with the core purpose, then a compact notes list of caveats; every sentence carries an actionable caveat or recommendation. Minor redundancy with the schema's interval and datum text keeps it just short of ideal.

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 10-parameter, single-required-parameter query tool with full schema coverage and an output schema, the description covers the remaining agent-critical gaps: interval choice, span limits, datum relativity, station-type restrictions, and the astronomical-only caveat. Nothing needed 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 description coverage is 100%, so every parameter including datum, interval spans, time_zone, units and date formats is already documented in the schema. The description largely restates interval spans and the MLLW default rather than adding syntax or format detail beyond the schema, so the baseline 3 applies.

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 and resource ('Get NOAA harmonic tide predictions ... for a station') and immediately scopes it to future or past predictions. It distinguishes itself from the closest sibling by contrasting with noaa_get_water_levels for actual conditions.

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 recommends interval=hilo for the 'when is high/low tide' question and routes the agent to noaa_get_water_levels for actual (non-astronomical) conditions. It also states when-not conditions: Great Lakes stations have no predictions, and subordinate stations only support hilo.

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 cover the read-only, idempotent, non-destructive nature of the tool. The description adds useful behavioral context: it describes the returned event details (date, height, causal event name, category), notes that heights are relative to a requested datum, and clarifies that peak events can be optionally year-filtered.

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 front-loaded with the primary purpose and efficiently covers the two analysis modes, datum relativity, and a use case in three sentences. It is appropriately sized, though the first sentence is dense with nested output details.

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 rich input schema, output schema, and annotations, the description provides enough context to call the tool correctly. It explains the key semantic choice between 'toptenwaterlevels' and 'peakwaterlevels' and the typical datum, though it does not differentiate from the similar extreme-water-level sibling.

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 the schema already documents all six parameters in detail. The description reinforces the analysis modes and datum context, but it largely repeats what the schema provides rather than adding new syntax, format, or constraint information.

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 and resource ('Get a station's highest recorded water levels') and clearly explains the two analysis modes. It distinguishes this from generic water-level tools by emphasizing 'highest recorded' and 'peak' events, but it does not name or contrast with the similar sibling noaa_get_extreme_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 gives a concrete use case ('what's the worst flooding ever recorded at X?') and explains when to use each analysis mode via the analysis parameter. It lacks explicit when-not guidance or direct comparison to alternatives such as noaa_get_extreme_water_levels.

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 readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: preliminary vs verified data status, the days-to-weeks verification lag, hard window limits per interval, datum semantics, and per-record field decoding (t, v, s, f, q). That is substantive disclosure well beyond the annotation layer.

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?

Front-loaded with the core action, then organized into labeled chunks (intervals, return record, use cases) so a reader can stop early. Slightly long for the payload, with some overlap between the interval paragraph and the interval parameter description, but no filler sentences.

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?

A 10-parameter tool with an output schema present, and the description still covers window limits, datum caveats, freshness caveats, and intended/forbidden uses. Nothing an agent needs to call it correctly is missing, and return-value detail is arguably bonus given the 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%, so baseline is 3, but the description adds practical selection meaning the schema does not: why to pick '1' vs '6' vs 'hourly', what MLLW means as chart zero, and that recent readings are preliminary. Its interval explanation does partially duplicate the schema's own wording, capping it below 5.

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 ('Get observed water levels from a NOAA tide station as a time series') and immediately distinguishes itself from the prediction siblings by scoping to observed data. An agent can tell it apart from noaa_get_tide_predictions, noaa_get_extreme_water_levels, and noaa_get_top_ten_water_levels without opening any schema.

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 names use cases ('what is the water level right now' with date=latest, storm surge analysis, observed vs predicted comparison) and an exclusion with a named alternative: 'Do NOT use for future tides — use noaa_get_tide_predictions.' This is the explicit when/when-not/alternative pattern at full strength.

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 readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. Beyond that, the description adds real behavioral context the annotations cannot: per-product request ceilings (1 year for high_low, 10 years for daily_mean/daily_max_min, 200 years for monthly_mean), the Great Lakes-only restriction and automatic local-standard-time handling for daily_mean, and the column set returned by monthly_mean.

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?

Front-loaded with the core purpose, then a scannable bullet per product, then a usage/routing sentence. Every bullet carries a limit or semantic distinction, though some content (the year caps, the lst requirement) duplicates the schema and could be trimmed.

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 an output schema present, annotations covering the safety profile, and 100% schema coverage, the description only needs to convey product distinctions, routing, and limits — all of which it does. An agent has everything required to select the tool and the correct product.

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 the schema already documents every parameter, and the description's product bullet list largely restates the product enum's own description (including the 1yr/10yr/200yr limits). The 'daily_mean requires lst' note is also already present in time_zone's schema description. Baseline 3 applies since the schema does the heavy lifting and the description adds little parameter-level syntax or constraints beyond it.

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 and resource ('Get verified summary water-level products from a NOAA station') and enumerates all four products with their distinguishing characteristics. It also names the siblings it is not (noaa_get_water_levels for raw series, noaa_get_tide_predictions for future tides), so an agent can route correctly without opening a schema.

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 when-to-use is given ('Use for: historical extremes, mixed-tide analysis (HH vs H), long-term averages') plus two named alternatives with the condition that selects each ('For raw time series use noaa_get_water_levels; for future tides use noaa_get_tide_predictions'). This is a complete routing statement.

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 readOnly/idempotent/openWorld/non-destructive, so safety is covered. The description adds real behavioral context beyond them: the result fields returned, pagination via limit/offset, and the R vs S reference/subordinate distinction with the 'hilo predictions only' caveat for subordinate stations. It omits auth/rate-limit notes, but adds substantial operational meaning.

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?

Front-loads the core purpose, then a tight bulleted filter list, then return contents, then the sibling hand-off. Every sentence carries distinct information with no repetition of the schema.

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 search tool with an output schema and full schema coverage, this covers purpose, filter semantics, result shape, pagination, and alternative routing. An agent has everything needed to select and invoke it 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%, so the baseline is 3. The description still adds meaning the schema does not: the semantic rationale for choosing a type, concrete name substring examples, and the two-letter state format. It does not fully explain every enum member, delegating that to noaa_get_reference_guide.

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 and resource ('Search the NOAA CO-OPS station directory') and enumerates the exact filter dimensions (capability type, name, state). It explicitly differentiates itself from the sibling noaa_find_nearest_stations by scoping itself to attribute search rather than coordinate proximity.

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 selection guidance ('pick the type matching the data you plan to request') and names the alternative tool with the condition that selects it ('For proximity search by coordinates use noaa_find_nearest_stations instead'). When-to-use and when-to-use-something-else are both covered.

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 readOnly, idempotent, non-destructive, openWorld. The description adds genuinely useful context beyond them: the ±20-60 NM offshore domain constraint and the fact that the return includes the zone segment plus the office-wide synopsis and Small Craft Advisories.

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 tight sentences, front-loaded with the core action and sample output, followed by constraints and routing. Every sentence earns its place, though the sample quote is slightly decorative.

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 an output schema present, the description needn't explain return values, yet it briefly notes what is returned (zone segment + synopsis). Coverage of purpose, domain constraint, and alternatives is sufficient 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 description coverage is 100%, so latitude, longitude, and response_format are already fully documented in the schema. The description adds no extra parameter syntax or format detail, so the baseline 3 applies.

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 ('Get'), resource ('official NWS Coastal Waters Forecast (CWF) narrative'), and scope ('for the marine zone covering a latitude/longitude'). It even quotes sample content, distinguishing it from sibling forecast tools at a glance.

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 routing: 'For numeric hourly wind values use nws_get_wind_forecast; for observed wind at a NOAA station use noaa_get_meteorological_data (product "wind").' It also states the geographic precondition (point must lie in or near US coastal waters, 20-60 NM offshore).

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 the safe read-only/idempotent profile, and the description goes well beyond them: data provenance (api.weather.gov gridpoints, numeric NDFD values not display strings), a hard 156-hour horizon, US-and-territories-only coverage, and the fact that wave height only appears on marine/nearshore grids while swell/period are open-ocean only. These are real constraints an agent could otherwise get wrong.

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?

Front-loads what the tool returns, then coverage/units caveats, then routing to alternatives. Four short paragraphs, each carrying distinct information (data source, horizon, units/direction convention, sibling disambiguation) with 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?

With an output schema present, the description need not explain return format. It covers everything else an agent needs: data source and value semantics, temporal and geographic limits, unit behavior, and the two relevant alternative 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 description coverage is 100%, so the schema already documents all five parameters, including the units enum and hour bounds. The description restates the units convention (knots/feet vs m/s/meters) and adds direction-is-degrees-true semantics, but that addition is small and largely duplicates the structured fields, so the baseline of 3 applies.

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 and resource (hourly NWS wind FORECAST: speed, gust, direction, optional wave height) and pins the input (lat/long). It explicitly distinguishes itself from the two closest siblings by naming them and their data types, so an agent can route 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 when-to-use alternatives: observed wind at a NOAA station goes to noaa_get_meteorological_data (product "wind"), and the official marine narrative goes to nws_get_marine_forecast. The forecast-vs-observed distinction is exactly the ambiguity an agent faces here.

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