NOAA Tides and Currents

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

Adds behavioral details beyond annotations: supports date ranges, lists output fields, and states computation is local (no external API). Annotations already indicate idempotent read-only operation, so description adds useful context.

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 brief paragraphs front-load the core functionality. Every sentence adds value: output fields, range capability, tide context, local computation. No redundant or irrelevant content.

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 main aspects: purpose, output fields, optional range, tide context, and computation source. Minor omission: default behavior when no date given (today) is only in schema. Still sufficient for a simple 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 covers 100% of parameter descriptions. Description provides extra meaning: explains that latitude/longitude affect distance/diameter precision, and mentions response_format options (markdown/json).

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

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

Description clearly states 'Get the moon phase for a date (or each day of a date range)'. Lists specific output fields (phase name, illuminated fraction, etc.) and distinguishes from sibling tools by mentioning local computation (no NOAA data).

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

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

Provides context for usage: tide relevance (spring/neap tides) and clarifies local computation. Implicitly differentiates from sibling tools like astro_get_next_moon_phase, but does not explicitly mention when to avoid using this 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 readOnlyHint, idempotentHint, destructiveHint. The description adds that it finds occurrences 'from a starting date' and mentions spring tides, but does not disclose additional behavioral traits like timezone handling or accuracy. No contradiction with annotations.

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

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

Two concise sentences plus a brief use case example. No wasted words, front-loaded with purpose.

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

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

No output schema, but the response_format parameter covers output control. The description is complete enough for a simple read-only tool with annotations covering safety and idempotency. Could mention that results are forward-looking from the start date.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description reinforces 'principal moon phase' but does not add significant meaning beyond the schema definitions.

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

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

The description clearly states the tool finds date(s) of the next occurrence of principal moon phases, listing all four phases explicitly. It differentiates from sibling astro_get_moon_phase by focusing on 'next occurrence' rather than phase on a given date.

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 use cases: 'when is the next full moon?' and planning around spring tides. Does not explicitly state when not to use or mention alternative tools, but the context is clear for selecting this tool among siblings.

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=true and idempotent=true. Description adds context about multiple occurrences and event types but does not disclose output format details or other behaviors beyond annotations.

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

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

Two brief sentences plus a use case line, front-loaded with purpose. No redundant words.

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

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

No output schema, so description could explain return values but does not. Adequate for a query tool with good annotations, but fails to describe output format beyond 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 baseline is 3. Description paraphrases parameters and gives context but does not add significant new meaning 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?

Description clearly states the tool finds next sun events at a location from a start date, listing all event types. Use cases differentiate it from sibling tools like astro_get_sun_times and astro_get_sun_position.

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

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

Provides specific use case examples ('when is sunset today?', golden-hour photography) indicating when to use. However, it does not explicitly mention when not to use or compare with sibling tools.

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 (readOnlyHint, idempotentHint) are already present, and the description adds value by disclosing local computation and approximate nature of declination/RA. No contradictions.

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

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

Two clear, front-loaded sentences with no wasted words. The first sentence states purpose and outputs, the second provides usage guidance and caveats.

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

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

Given the tool's complexity (5 params, 2 required) and no output schema, the description sufficiently explains what the tool returns. All key behaviors are covered.

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 by naming the output fields (azimuth, altitude, declination, RA) and clarifying that date/time default to today/now. This goes beyond the schema's parameter descriptions.

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

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

The description clearly states the tool gets the sun's position for a given date, time, and location, listing specific outputs (azimuth, altitude, declination, right ascension). It distinguishes from siblings like astro_get_sun_times by focusing on position rather than times.

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

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

Provides explicit use cases (shadow/lighting analysis, solar exposure) and notes the local computation and approximation of declination/RA. Could be improved by explicitly stating when not to use or comparing to astro_get_sun_times.

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, and destructiveHint=false. The description adds valuable behavioral context: times are in ISO UTC unless a timezone is given, and some events may be null at high latitudes (e.g., no astronomical night in summer). This goes beyond the annotations.

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

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

The description is three sentences, concise, and front-loaded with the core purpose. Every sentence provides necessary information without redundancy or unnecessary elaboration.

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 there is no output schema, the description adequately informs the agent about what will be returned (list of sun events) and important nuances (null values at high latitudes, timezone handling). It could mention the output format options, but the response_format parameter covers that.

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

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

The input schema has 100% description coverage for all 6 parameters, so the baseline is 3. The description mentions the range capability via end_date and timezone handling, but does not add significantly more semantic detail than the schema already provides for each 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?

The description uses a specific verb ('Get') and resource ('sun times'), lists the specific events included (sunrise, sunset, solar noon, etc.), and explicitly mentions the date range capability. This clearly distinguishes it from sibling tools like astro_get_moon_phase or astro_get_sun_position.

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

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

The description implicitly indicates usage for obtaining a comprehensive set of sun events for a given location and date or range. However, it does not provide explicit guidance on when to use this tool versus alternatives (e.g., astro_get_next_sun_event) or any conditions to avoid.

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 safe, read-only, idempotent behavior. Description adds that distance uses Haversine formula and that the tool maintains a cached station directory, clarifying internal caching behavior.

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

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

Three well-structured sentences: purpose, usage guideline with examples, technical note. No redundant words, front-loaded with key action.

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

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

Covers purpose, usage, parameter guidance, and internal caching. Could mention that returned station IDs are used in other NOAA tools, but not essential. Output format is addressed via parameter.

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 covers 100% of parameters. Description adds usage context for 'type' (e.g., filter before calling noaa_get_tide_predictions) and explains the purpose of 'response_format'. This goes beyond schema descriptions.

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

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

Clearly states 'Find the NOAA stations closest to a latitude/longitude point, sorted by distance.' Differentiates from sibling tools like noaa_search_stations.

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

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

Provides explicit usage scenario: 'to answer "what's the tide station near <place>?"' and instructs to geocode first. Also guides filtering by type for downstream tools.

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 destructiveHint. The description adds behavioral details: time span limits (1 year for max_slack, 31 days for others), bin=0 behavior (returns all bins but caps at 7 days), and the units warning about cm/s for currents. No contradictions with annotations.

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

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

Well-structured with logical sections. Each sentence adds value, no fluff. Efficiently packs critical information about usage, parameters, and warnings without redundancy.

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

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

With 11 parameters, 100% schema coverage, and no output schema, the description covers most key aspects: time span constraints, bin behavior, units, velocity types. It mentions subordinate stations, which is important. Lacks explicit description of return fields, but response_format offers markdown/json.

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

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

Schema coverage is 100%, but the description adds substantial meaning: explains bin depth and how to find valid bins, clarifies date shortcuts, details range logic, distinguishes units for wind vs currents, explains vel_type output differences, and adds context for time_zone requirement for daily_mean data. Goes well beyond schema.

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

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

The description clearly states it gets predicted tidal currents for NOAA current prediction stations. It distinguishes from siblings like noaa_get_currents and noaa_get_tide_predictions by specifying 'predictions' and detailing different output options like flood/ebb events.

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

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

Provides explicit guidance: recommends interval='max_slack' for navigation, explains other intervals for time series, and notes subordinate stations need offsets from noaa_get_prediction_offsets. Does not explicitly state when not to use, but context with siblings implies 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 indicate read-only, idempotent, non-destructive behavior. The description adds constraints (max 7 days per request) and details the return fields (time, speed, direction, bin number). No contradictions with annotations.

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

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

The description is front-loaded with purpose, then provides essential details in a logical order: ID format, units warning, return fields, constraints. Every sentence adds value with no redundancy.

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

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

Despite 10 parameters and no output schema, the description covers how to find stations, unit handling, date/time options, bin usage, and return fields. It is sufficient for correct selection and 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 covers 100% of parameters with descriptions. The description enriches parameter understanding: explains unit system differences for currents (cm/s vs knots), clarifies bin=0 behavior (returns all bins but caps at 7 days), and distinguishes station ID formats.

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

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

The description explicitly states the tool retrieves observed current speed and direction from NOAA current meter stations. It distinguishes current stations (alphanumeric IDs) from water-level stations (numeric IDs), and the sibling list includes noaa_get_current_predictions, making the observational nature clear.

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

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

The description advises on finding stations using noaa_search_stations or noaa_find_nearest_stations, warns about unit differences (knots vs cm/s), and mentions the 7-day max request window. It does not explicitly state when to avoid this tool (e.g., use noaa_get_current_predictions for forecasts), but the context is sufficiently clear.

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, idempotentHint, and openWorldHint. The description adds useful behavioral context: 'Levels are relative to the station's datums for the 1983–2001 epoch' and the condition on station record length. No contradictions.

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

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

Two concise sentences in the first paragraph plus a short usage note. Every sentence adds value, front-loaded with key information. No wasted words.

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

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

No output schema exists, so the description should clarify return structure. It mentions what is returned (exceedance levels and events) but does not describe the format (e.g., columns or data types) beyond the response_format parameter. Slightly incomplete for a tool with 5 parameters.

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 descriptive parameter descriptions. The description does not add extra meaning beyond the schema, but the schema itself is thorough. Baseline score of 3 is appropriate.

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

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

The description clearly states it retrieves 'annual exceedance probability levels' and 'historical extreme events' for a station, providing a specific example ('100-year level'). It distinguishes from sibling tools like noaa_get_water_levels and noaa_get_top_ten_water_levels by focusing on extreme statistics.

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

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

The description explicitly says 'Use for flood risk questions' and gives a concrete example. It also notes that 'Only long-record stations have this product,' which helps set expectations. However, it does not explicitly state when not to use or mention alternative tools.

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, openWorldHint, idempotentHint, and destructiveHint. Description adds behavioral context: explains output data structure (amplitude, phase, speed) and differences between water-level and current stations. No contradiction.

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

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

Three sentences, each earning its place: first states purpose, second details output per station type, third gives use cases and caveats. Front-loaded and efficient.

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

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

Given the complexity (station types, bin, units, output format), the description is complete. No output schema, but description explains what the output contains and how to interpret it. Covers required vs optional parameters and gives examples.

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

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

Schema has 100% coverage, but description adds significant context beyond schema: for bin ('for current stations: restrict to one depth bin'), for units (explains english vs metric differences), for station (explains numeric vs alphanumeric IDs and how to find them).

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

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

Description clearly states it retrieves harmonic constituents (amplitude, phase, speed) for tide/current predictions. Distinguishes from siblings by noting only reference stations have constituents, while subordinate stations use offsets (noaa_get_prediction_offsets). Includes specific use cases.

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

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

Explicitly says 'Use for: building custom tide computations, checking a station's dominant constituents, verifying whether a station is harmonically predicted at all.' Also states the alternative: 'subordinate stations use offsets (noaa_get_prediction_offsets).'

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, openWorldHint, idempotentHint, and destructiveHint false. The description adds value by detailing report behavior (e.g., daily requires start_date and end_date) and station preconditions. No contradictions with annotations.

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

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

The description is well-structured with a bullet list of report types. It is front-loaded with the main purpose. Though lengthy, each sentence serves a purpose. Could be slightly trimmed but overall efficient.

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

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

Given 12 parameters, 100% schema coverage, and no output schema, the description adequately covers report selection, parameter requirements, and station prerequisites. It does not describe the structure of results, but the response_format parameter partially addresses this.

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

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

Input schema has 100% coverage. The description adds semantic grouping of parameters by report type and explains how parameters like year, month, range, and decade are used. It aids in parameter selection without duplicating schema descriptions.

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

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

The description clearly states it retrieves NOAA high tide flooding statistics for a station, listing many specific report types. It distinguishes from siblings by explaining that not all stations have HTF products, referencing a sibling tool (noaa_get_station_info) for checking the HTFhistorical flag.

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

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

The description provides usage context: 'Use for: how often does X flood?, trends in nuisance flooding, future flooding projections.' It also warns about station compatibility. However, it does not explicitly state when NOT to use this tool (e.g., other flood-related tools among siblings) beyond the station check.

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, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral details like max time span, unit systems, time zone handling, and output formats. 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 detailed and well-structured with clear sections for products, units, span/interval, and cross-references. It is front-loaded with the core purpose. Slightly verbose at ~150 words but every sentence adds value.

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

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

Given the tool's complexity (10 parameters, 2 required, no output schema), the description is comprehensive. It covers all key behaviors, constraints, and relationships to sibling tools, including how to find stations and check sensor availability.

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

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

Schema coverage is 100%, but the description adds significant meaning: explains date shortcut behaviors (today, latest, recent), range semantics, unit system differences, station ID formats, and time zone nuances. This exceeds 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?

The description clearly states it retrieves observed meteorological/oceanographic sensor data from a NOAA station. It lists specific products and explicitly distinguishes from water-level data served by 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?

Provides explicit guidance: max span of ~31 days, default interval of 6 minutes, sensors not at all stations, and refers to noaa_get_station_info to check availability. Also clearly segregates water-level data to another 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 indicate readOnly, idempotent, non-destructive, and open world hints. The description adds critical behavioral details: returns specific offset fields per kind, reference stations yield empty results, and current offsets require bin suffix. No contradictions.

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

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

Organized into clear paragraphs by kind, with front-loaded main purpose. Could be slightly more concise, but no wasted 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?

No output schema, but the description fully explains the return structure for both kinds, including special cases (reference stations, bin indexing). Covers all necessary details 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%, but the description adds significant value by explaining what each kind returns (e.g., refStationId, time/height offsets, ratios for tide; mean flood/ebb, time adjustments, amplitude ratios for current). Also clarifies the bin suffix requirement for current stations.

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

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

The description clearly states it retrieves offsets for subordinate stations, distinguishes between 'tide' and 'current' kinds, and explicitly notes that reference stations return empty. This differentiates it from sibling tools like noaa_get_tide_predictions or noaa_get_currents.

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

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

Provides clear guidance on when to use (for subordinate stations) and when not (reference stations return empty). Also advises using bin suffix for current stations. Lacks direct mention of alternatives but context is sufficient.

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, and destructiveHint=false, covering safety. The description adds content details (e.g., what each topic contains) but does not disclose additional behavioral traits like caching or error handling. It neither contradicts annotations nor adds significant behavioral context.

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

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

The description is well-structured with a clear opening sentence followed by a bulleted list of topics. It is front-loaded with the main purpose. While the list is comprehensive, it is not overly verbose for a reference tool with 10 topics. Slightly longer than necessary but retains clarity.

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

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

Given one enum parameter and no output schema, the description covers all possible topics and provides guidance on which are most important. It is fully adequate for an agent to understand and invoke this 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?

The input schema covers 100% of the parameter with an enum and description, but the description enriches it by explaining what each topic includes (e.g., 'products: Every NOAA CO-OPS data product and which tool serves it'). This adds substantial meaning beyond the schema's minimal description.

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

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

The description clearly states the tool's purpose: 'Get curated reference documentation for NOAA CO-OPS concepts and parameters.' It lists all 10 topics explicitly, making the function unambiguous. This distinguishes it from sibling tools that fetch data rather than provide documentation.

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 advises consulting the guide 'before constructing unusual requests' and highlights specific topics like 'datums', 'units', and 'data_limits' for special attention. While it does not explicitly state when not to use this tool, the context suggests it should be used prior to data-retrieval tools. Clear but lacks explicit 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 provide readOnlyHint, idempotentHint, and destructiveHint=false, so the tool's safe, read-only nature is clear. The description adds context about scenario selection and projection years but does not disclose additional behavioral traits beyond what annotations provide. It does not contradict annotations.

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

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

The description is concise with only two sentences plus a brief list of scenarios and a usage note. It is front-loaded with the core purpose and every sentence adds value, with no unnecessary repetition.

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 absence of an output schema, the description provides some context about return values (projected relative sea level in meters/feet) and allows markdown or json format. However, it does not detail the structure of the markdown table or JSON payload, leaving the output somewhat underspecified for a tool with 5 optional parameters.

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 5 parameters with descriptions. The description adds minimal extra meaning beyond mentioning units and scenarios. Baseline 3 is appropriate as the description does not significantly enhance parameter understanding.

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

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

The description clearly states the tool gets NOAA's Interagency Sea Level Rise Scenario projections for a station, specifying the data source (2022 technical report), the output (projected relative sea level in meters or feet), and the time horizon (per decade through 2150). It distinguishes itself from sibling tools by mentioning pairing with noaa_get_sea_level_trends and noaa_get_high_tide_flooding.

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

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

The description provides explicit usage context: 'Use for coastal planning questions' with a concrete example ('how much sea level rise is projected at X by 2050?'). It also lists alternative tools to pair with, clarifying when to use this tool versus siblings.

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 indicate read-only, non-destructive, open-world, and idempotent behavior. The description adds context by explaining the units (mm/yr or inches/decade) with the trendUnits field, the observation period, seasonal amplitude, and the concept of relative sea level combining ocean rise and land movement. No contradictions.

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

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

The description is efficient, using about three sentences to convey purpose, output details, and parameter usage. It is front-loaded with the main action. However, it could be slightly more structured with separate lines for clarity, and the dense information may require careful reading.

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

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

Given no output schema, the description explains key output fields (trend, error, period, seasonal amplitude) and the trendUnits field. It also explains the concept of relative sea level. However, it does not describe the structure when listing multiple stations (e.g., array format), leaving some ambiguity for agents.

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

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

All parameters have schema descriptions (100% coverage). The description adds meaning beyond the schema: it explains that omitting station returns a list, affil filters the network, and provides examples of station ID formats. It also references other tools for finding stations, enhancing understanding.

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 gets long-term relative sea level trend for a NOAA station, listing specific fields like trend, error, period, and seasonal amplitude. It distinguishes from siblings by focusing on long-term trends and mentioning the need for a long water-level record, though it does not explicitly differentiate from similar tools like noaa_get_sea_level_rise_projections.

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 for long-term relative sea level trends, but does not explicitly state when not to use it or provide alternatives. It mentions the need for a station with a long record, which hints at prerequisites, but lacks clear guidance on choosing between siblings.

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 indicate read-only, idempotent, non-destructive behavior. The description adds value by explaining that all values share one reference zero and that datum-to-datum conversion is subtraction, plus the meaning of the epoch parameter. No contradiction.

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

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

The description is a single, well-structured paragraph that front-loads the purpose, then explains the epoch parameter, and ends with practical usage advice. Every sentence adds value with no wasted words.

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

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

Given 4 parameters, rich enums, and no output schema, the description is quite complete. It explains the data returned and conversion utility. The response_format parameter is covered by the schema, so the description's omission of format details is acceptable.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaning by listing all datums in detail, explaining the epoch options, and providing usage context for conversion. This goes beyond the schema descriptions.

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

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

The description clearly states the tool retrieves accepted tidal datum values for a station, listing specific datums (MHHW, MHW, etc.) and explaining the epoch parameter. It distinguishes itself from sibling tools like noaa_get_tide_predictions by focusing on datum values and conversion.

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 provides two use cases: checking which datums a station supports before requesting data, and converting heights between datums. Also notes that not all stations have a 'superseded' epoch, guiding proper usage.

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 provide readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds context about expanding sub-resources, units behavior, and station ID patterns, which goes beyond the annotations.

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

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

The description is well-structured with bullet points for expand options, and every sentence serves a purpose. It is concise without being terse.

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 four parameters and no output schema, the description thoroughly explains tool purpose, usage context, parameter details, and expected output formats. It leaves no significant 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?

Schema coverage is 100%, but the description adds significant meaning: it explains the station ID format (numeric vs. alphanumeric), the units system details (e.g., wind vs. current units), and the expand options with station-type applicability. This greatly enhances understanding.

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

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

The description clearly states the tool gets a NOAA station's full metadata record, listing specific fields like location, state, time zone, and capability flags. It distinguishes from sibling tools by explicitly mentioning noaa_get_station_datums and noaa_get_harmonic_constituents for datum values and 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?

The description explicitly says 'Use this before requesting data to confirm what the station actually collects.' It also directs to sibling tools for specific data (datums, harmonic constituents), providing clear when-to-use guidance.

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?

Disclosures beyond annotations: predictions are astronomical only (no weather effects), heights relative to datum, Great Lakes have no tides, and subordinate stations limited to hilo. This adds significant behavioral context without contradicting readOnlyHint or openWorldHint.

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

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

Three well-organized paragraphs: summary, interval details, and special notes. Every sentence adds value, no redundancy. Front-loaded with the primary action.

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 key behavioral aspects (intervals, datums, limitations, distinction from water levels). Lacks mention of authentication or error handling, but these are minor given the tool's maturity and input schema richness.

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

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

Schema has 100% parameter description coverage, providing baseline 3. The description adds valuable context not in schema (e.g., Great Lakes restrictions, subordinate station behavior, astronomical-only nature) that helps interpret parameters like interval and station.

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 exactly what the tool does ('Get NOAA harmonic tide predictions') and specifies the resources (stations). It clearly distinguishes between tidal events and time series via interval parameter, and contrasts with sibling tools like 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?

Provides explicit guidance: interval='hilo' for high/low tides, other intervals for time series, with maximum spans. Notes where tool is not applicable (Great Lakes, subordinate stations) and directs to alternatives (reference station, noaa_get_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 indicate read-only, idempotent, open-world behavior. The description adds useful context: heights are relative to a datum, the 'toptenwaterlevels' includes causal event names, and 'peakwaterlevels' can be filtered by year. No contradictions with annotations.

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

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

The description is concise, consisting of two short paragraphs. It front-loads the main purpose and adds key details without fluff. Every sentence contributes essential 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 tool with 6 parameters, two analysis modes, and no output schema, the description covers the main points: the two types of results, datum relevance, and use case. It could be more complete by briefly describing the 'peakwaterlevels' record structure, but overall it is adequate.

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 value by explaining that MHHW is typical for flood comparisons and providing a concrete station ID example. It also clarifies the two analysis modes beyond the schema's enum labels.

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 'Get a station's highest recorded water levels' and explains two analysis modes. It specifies the data returned for 'toptenwaterlevels' (date, height, causal event name, category). However, it does not explicitly distinguish this tool from siblings like noaa_get_extreme_water_levels, which might have overlapping functionality.

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

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

The description provides a clear use case: 'what's the worst flooding ever recorded at X?' and advises using MHHW datum for flood comparisons. However, it lacks explicit guidance on when not to use the tool or alternatives for related queries (e.g., regular water levels or extreme 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?

Beyond annotations (readOnlyHint, idempotentHint), the description explains data quality ('Recent data is preliminary; verification takes days to weeks'), output fields (t, v, s, f, q), and behavior of parameters like date shortcuts. This provides rich context about what the tool does and how responses are structured.

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

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

The description is well-organized: starts with purpose, then paragraphs for interval, datum, return record, and usage. Every sentence adds value, no redundancy, and it is front-loaded with the key action. Appropriate length for the tool's complexity.

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

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

Despite having 10 parameters and no output schema, the description fully explains return fields, data quality, parameter interactions, and appropriate use cases. It provides enough context for an agent to use the tool correctly without additional lookups.

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 value by explaining datum applicability (Great Lakes datums), interval max durations, station ID patterns, and date shortcut semantics. This goes beyond the schema's description by providing deeper context.

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 'Get observed water levels from a NOAA tide station as a time series.' It specifies the resource (observed water levels), action (get), and format (time series). It also distinguishes itself from sibling tools like noaa_get_tide_predictions by explicitly warning not to use for future tides.

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

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

Provides explicit guidance: 'Use for: "what is the water level right now" (date=latest), storm surge analysis, comparing observed vs predicted tide. Do NOT use for future tides — use noaa_get_tide_predictions.' Also explains interval constraints and time ranges, helping the agent choose correctly.

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 indicate read-only, open-world, and idempotent behavior. The description adds valuable context: automatic application of local standard time for daily_mean, product-specific data ranges (no further destructive mutations or side effects are noted). No contradictions with annotations.

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

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

The description is well-structured with a clear opening sentence, bullet-point list of products, and a closing sentence for usage guidance. It is moderately long but every sentence provides distinct value, and key information 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 complexity (10 parameters, 2 required, no output schema), the description thoroughly explains what each product returns (e.g., lists of columns for monthly_mean), addresses edge cases (Great Lakes constraints, time zone handling), and provides usage limits. It leaves no major gaps for an agent to select and invoke correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description goes beyond the schema by explaining each product's meaning, the significance of HH vs HL in mixed-tide analysis, and the long-term climatology use of monthly_mean. This adds meaningful semantic context for parameter 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?

The description clearly states it retrieves 'verified summary water-level products' from NOAA stations, lists four specific products (high_low, daily_mean, daily_max_min, monthly_mean) with concise explanations of each, and explicitly distinguishes from sibling tools (noaa_get_water_levels for raw time series, noaa_get_tide_predictions for future tides).

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

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

The description provides explicit guidance on when to use each product type, including maximum time ranges (e.g., high_low max 1 year, monthly_mean max 200 years), specific constraints (daily_mean for Great Lakes only), and directly names alternative tools for related but different data needs.

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, openWorldHint, idempotentHint. Description adds pagination details, output format options, and return fields, which are helpful but not contradictory.

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

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

Concise and well-structured: first sentence states purpose, followed by filter explanations, return fields, and sibling tool reference. No superfluous text.

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

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

Given 6 parameters, no required, no output schema, description covers all aspects: filters, pagination, output format, and alternative tool. Slight gap on default sorting, but minor.

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%, baseline 3. Description adds detail beyond schema: case-insensitive substring for name, examples for type, and guidance on selecting type. No param info missing.

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

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

The description clearly states the tool searches the NOAA CO-OPS station directory with filters by type, name, and state. It distinguishes from sibling noaa_find_nearest_stations for proximity search.

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 guidance on when to use this tool vs. noaa_find_nearest_stations and advises picking the type matching the data to request. Could be more explicit about exclusions, but adequate.

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?

Discloses that the tool returns the zone's segment from the latest bulletin plus the office-wide synopsis, including Small Craft Advisories. This adds context beyond the annotations (readOnly, openWorld, idempotent) without contradiction.

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

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

Three well-structured sentences: first states purpose and output, second adds geographic constraint, third lists alternatives. No wasted words, front-loaded with key 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?

Given no output schema, the description adequately covers return content (text, synopsis, advisories) and format options (response_format). Slightly limited on precise structure, but sufficiently complete for selection and 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 provides full parameter descriptions, and the description does not add new details for the parameters themselves. The baseline of 3 is appropriate given high schema coverage, though the description indirectly clarifies parameter usage through context.

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

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

The description clearly states the tool retrieves the NWS Coastal Waters Forecast narrative for a marine zone based on lat/lon, specifying the content (wind/seas text, Small Craft Advisories) and distinguishing it from sibling tools like nws_get_wind_forecast and noaa_get_meteorological_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?

Explicitly outlines when to use this tool (for CWF narrative) and when not to, providing clear alternatives (numeric wind use nws_get_wind_forecast, observed wind use noaa_get_meteorological_data), plus geographic constraints (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 readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds valuable context: the data source (NDFD numeric values), forecast horizon (156 hours), wave height availability (marine/nearshore), and unit systems. It does not contradict annotations.

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

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

Concise but packed with necessary information. Front-loaded with the main purpose, followed by clear sections on data source, units, and alternatives. Every sentence adds value.

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

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

No output schema, but the description adequately explains what to expect in the response (speed, gust, direction, wave height, swell). It covers units, direction convention, and geographic scope. Given the complexity, it is nearly 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 coverage is 100% (all parameters have descriptions). The description adds extra meaning: explains that direction is degrees true, clarifies unit systems, and notes that wave height appears only for marine gridpoints. This goes beyond the schema descriptions.

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

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

The description states the specific verb ('Get') and resource ('NWS hourly wind FORECAST'), specifying speed, gust, direction, and wave height. It clearly distinguishes from sibling tools by noting alternatives for observed wind (noaa_get_meteorological_data) and marine text forecast (nws_get_marine_forecast).

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

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

Explicit guidance on when to use this tool (for forecast data) versus when not (for observed wind or marine text forecasts). It also mentions geographic limitations (US and territories only) and the typical horizon (up to ~7 days).

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 and idempotentHint=true. The description adds context about the specific information returned (account, sign-in method, rate limits), which is useful but does not significantly expand on behavioral traits 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 sentences with zero waste: first sentence lists what the tool shows, second sentence gives usage scenarios. Front-loaded and efficient.

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

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

No output schema, but the description fully covers the return information: account, sign-in method, rate-limit tier, and requests-per-minute. For a simple read-only identity tool with no parameters, it is complete.

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

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

No parameters exist, so baseline is 4. The description does not need to add parameter 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 clearly states the tool shows authentication details: account, sign-in method, rate-limit tier, and requests-per-minute. It distinguishes from all sibling tools (astro, noaa, nws) which are environmental data 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?

The description explicitly mentions three use cases: asking which account, why rate limited, or if sign-in worked. It provides clear context but no when-not-to-use guidance, which is acceptable given the tool's narrow purpose.

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