noaa-climate-mcp-server

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

Annotations already declare readOnlyHint=true and openWorldHint=true, but the description adds substantial non-obvious behavioral details: the per-request date range limits (1 year vs 10 years), the special proxy year for normals, and the crucial units behavior (raw tenths-of-unit integers unless units=metric/standard is passed). It also states the return format (flat tuples). This goes well beyond the annotations and provides the agent with critical knowledge to correctly interpret results.

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

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

The description is long (six sentences) but every sentence carries critical information: purpose, required params, date limits, normals exception, return format, and units warning. It is front-loaded with the core purpose and requirements. While concise would be shorter, the density of essential pitfalls justifies the length. Slightly verbose but not wasteful.

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, 3 required, an output schema, and annotations, the description covers the main decision points: what to pass, how to bound the date range, how to handle normals, and how to read values. It does not explicitly mention pagination strategy (offset/limit) or how to discover station IDs, but those are covered in the schema (e.g., stationId description says to use noaa_climate_find_stations). The output schema provides return structure, so the description need not repeat that. Overall, nothing critical is missing for a competent agent.

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

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

Schema description coverage is 100%, but the description adds meaning beyond the schema: it gives concrete dataset examples (GHCND, GSOM), explicitly ties date limits to dataset groups, warns about the units pitfall ('TMAX=256 = 25.6°C'), and explains the proxy-year behavior for normals. These details are not in the schema and meaningfully increase the agent's ability to call the tool correctly.

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 opens with a specific verb and resource: 'Fetch historical observation records from a NOAA CDO dataset for a given date range.' It clearly separates this from the sibling metadata/list tools (find_stations, list_datasets, etc.) by focusing on data retrieval. The verb 'fetch' plus the resource 'historical observation records' is unambiguous.

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

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

The description gives clear context on what the tool needs (datasetId, startDate, endDate) and provides detailed guidance on date range limits per dataset type, plus a special instruction for NORMAL_* datasets to use the 2010 proxy year. It does not explicitly contrast this tool with alternatives (e.g., 'use this tool when... not when...'), but the sibling tools are all lookup/metadata operations, so the usage context is clear by implication. No explicit exclusions are given, hence a 4.

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, so safety is covered structurally, but the description adds genuinely non-obvious behavior: the CDO API exposes no name parameter, so this server enumerates the category and performs substring matching itself; the 4000-location bound on that behavior; and the fact that datasetId/datacategoryId can shrink an oversized category back under the limit. This mechanical disclosure goes well beyond what the annotations convey. No contradiction with annotations.

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

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

The description is long, running as a single dense paragraph, but every sentence earns its place — purpose, category enumeration, naming workaround, size limits, pagination fallback, ID formats, downstream routing. Information density is high and the purpose is front-loaded before implementation details. It could be tightened into structured bullets, which costs it one point, but there is 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?

For a 10-parameter lookup tool with output schema and openWorldHint, the description covers everything needed to call it correctly: the search mechanism, the nameContains workaround and its bound, category sizes, sort/pagination fallback for oversized categories, and explicit routing of results to downstream tools. Potential failure modes (oversized categories) are anticipated with concrete mitigations. Nothing an agent needs 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?

Though schema coverage is 100% (baseline 3), the description adds substantial meaning the schema lacks: worked location-ID formats (FIPS:37 for NC, CITY:US530018 for Seattle, ZIP:98101, FIPS:US), the enumeration/size-limit mechanics behind nameContains, and concrete category semantics (ST=51 entries, CITY=thousands, ZIP). These worked examples and behavioral notes materially improve the agent's ability to construct correct parameter values.

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 opens with a specific verb+resource combination — 'Search for geographic locations by category' — and immediately states the tool's actual purpose: returning location IDs that feed into station search and data queries. It distinguishes itself from siblings by name (noaa_climate_find_stations, noaa_climate_fetch_data) and by its role as the upstream ID lookup step. No ambiguity remains about what this tool does or how it fits the workflow.

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, actionable guidance: use locationCategoryId=ST to list US states (with the 51-entry size note), pass nameContains alongside locationCategoryId to find by name, and route to noaa_climate_list_location_categories when the category is unknown. It even gives a fallback strategy ('sort alphabetically with sortField=name and page through results') for oversized categories. Usage conditions and alternatives are named directly rather than 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 declare readOnlyHint=true and openWorldHint=true, so the agent knows this is a read-only search that may return changing results. The description adds that station IDs are used in noaa_climate_fetch_data and returns coverage date fields, but it doesn't disclose any additional behavioral nuances (e.g., pagination behavior, ordering defaults) beyond what the schema and annotations already imply. This is slightly above baseline given the annotations exist.

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 dense paragraph but is well-organized: purpose first, then filter list, then the compatibility advice, then common ID formats. No redundant filler; each sentence earns its place. Slightly long but justified by 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?

For an 11-parameter search tool with an output schema, the description covers the key functional aspects: filtering by location/extent/dataset/datatype/date, the returned fields, and the station ID formats used downstream. It omits explicit guidance on pagination (offset/limit) and sorting, but the schema documents those with defaults, and the output schema exists so return types are known. Overall complete for an agent 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 coverage is 100%, so all 11 parameters are documented. The description adds real value by providing concrete examples for locationId ('FIPS:37'), extent ('47.5,-122.4,47.7,-122.1'), datasetId ('GHCND'), and datatypeId (['TMAX','TMIN','PRCP']). It also clarifies that date filters should be combined with datasetId to ensure data exists. This exceeds what the bare schema provides.

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 ('Search for... stations') with a clear resource and lists both the filter dimensions (location, bounding box, dataset, data type) and the return fields (IDs, names, coordinates, elevation, coverage dates). It is immediately distinguishable from siblings like noaa_climate_find_locations (locations) and noaa_climate_get_station (single station detail).

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 context for when to use the tool: when you need to find stations by filters. It gives practical advice ('filter by datasetId and startDate/endDate to ensure compatibility') and explains the relationship to noaa_climate_fetch_data. However, it does not explicitly state when NOT to use it or name alternatives (e.g., noaa_climate_get_station for a specific station).

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 the readOnlyHint and openWorldHint annotations, the description discloses critical behavioral details: the unit conversion (whole US dollars with declaredCostUnit), the state-scope caveats (national cost not state share, double-counting risk, binned cost ranges for per-year rows), and the coverage window (1980 to assessed year, not current calendar). It even warns about overlap inclusion rules and the difference between per-event and per-year outputs.

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 dense paragraph but every sentence carries unique value—no filler. It front-loads the primary purpose and then layers in filtering, unit, and state-scope nuances. While it is lengthy, it is appropriately compact for the complexity (8 optional parameters, two output modes); a bulleted format would improve skimmability but is not necessary.

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 high complexity and subtle edge cases, the description covers all critical aspects: the two output modes (default vs summary), filtering semantics, cost unit conversion, state-scope double-counting warning, coverage years, and the distinction from other NOAA tools. It even explains the meaning of coveredYears and the binned cost range, so an agent has everything needed to call it correctly without additional probing.

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?

Though schema coverage is 100% and the schema already provides rich parameter descriptions, the description adds essential semantics beyond the schema: the exact overlap rule for startYear/endYear, the state parameter's effect on row types and cost interpretation, the minCostInUsd behavior in summary mode (compared against 'All Disasters' or bin tops), and the 'coveredYears' reporting. This goes well beyond the baseline and significantly aids correct invocation.

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 ('Query') and a precise resource (NOAA/NCEI's Billion-Dollar Weather and Climate Disasters) while naming the exact content (curated disasters, cost classes, unit handling). It explicitly distinguishes itself from sibling tools by naming noaa_climate_search_storm_events and the CDO tools, so an agent can immediately tell this is a different corpus.

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 when-to-use guidance: it contrasts itself with the CDO tools and noaa_climate_search_storm_events, explains that it covers curated major disasters rather than every severe-weather event, and details default vs summary modes. It also clarifies the coverage years and how filters behave, leaving no ambiguity about when to choose 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?

With readOnlyHint=true and openWorldHint=false already declared, the bar is lower. The description adds context beyond the annotations by summarizing exactly what metadata is returned and the ID convention. No contradiction with the annotations; the return-summary adds value over the safety profile alone.

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 with zero waste: the core action with examples is front-loaded, the second sentence states what is returned, and the third gives usage guidance. Every sentence 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?

For a single-parameter, read-only tool with an output schema present, the description is complete. The agent knows the ID format, what the tool returns, and when to invoke it; the output schema covers return structure, so no further detail is needed.

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 layers on the meaning of the ID prefixes (GHCND, COOP) and reaffirms the source via find_stations, adding modest interpretive value beyond the schema's own stationId 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?

States a specific verb and resource: 'Fetch full metadata for a single weather station by its ID.' It names concrete ID formats with examples, lists the return content (name, coordinates, elevation, date range), and is clearly distinguishable from siblings like noaa_climate_find_stations and noaa_climate_fetch_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 an explicit workflow: use when you have an ID from noaa_climate_find_stations, for complete details or to verify a station before querying data. This gives clear when-to-use guidance and names the upstream sibling, but it stops short of an explicit when-not-to-use (e.g., directing raw data queries to noaa_climate_fetch_data).

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 openWorldHint=false, covering the safety profile. The description adds useful context about the total number of categories (42) and the grouping behavior, which goes slightly beyond annotations. However, it does not disclose additional operational traits like pagination limits or response size beyond what schema parameters imply.

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, with the core action and concrete examples in the first clause, followed by usage guidance and key facts. No redundant words or filler; every sentence earns its place.

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

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

Given an output schema exists and all parameters are documented, the description covers purpose, usage sequencing, and the key total count. It omits details like error handling or exact response shape, but these are typically beyond description scope and are covered by the output schema. It is sufficiently complete for an agent to decide when and how to call the 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 coverage is 100%, with each parameter having a detailed description. The description summarizes that filters exist for dataset, location, station, or date range, which is a high-level overview but does not introduce new semantics not already present in the schema. The baseline of 3 is appropriate when schema carries the parameter details.

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 'lists data categories' and provides concrete examples (Temperature, Precipitation, Wind). It explicitly contrasts with the sibling noaa_climate_list_data_types by positioning this as a discovery step before calling that tool. This distinguishes it from all siblings without ambiguity.

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

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

The description explicitly instructs users to 'discover what types of measurements are available before calling noaa_climate_list_data_types', providing a clear sequential usage context. It also mentions optional filters (dataset, location, station, date range), which helps agents decide when to use the tool. Though it doesn't state when not to use it, the alternative is named and the condition is 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 provide readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds valuable behavioral context: 'Returns all ~11 datasets by default (no required parameters)' clarifies default behavior, and the list of common datasets with temporal ranges gives the agent expectations. It does not mention pagination or rate limits, but these are not critical given the schema has pagination 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?

The description is three sentences: the first states purpose, the second covers default behavior and filtering, and the third lists common datasets and provides usage guidance. Every sentence adds value, and the most critical information (purpose and default behavior) is front-loaded. It is slightly longer than strictly necessary but remains 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?

The tool has 9 optional parameters and an output schema, so the description's job is to guide selection and usage. It covers the default behavior, filtering options, and common datasets, and it points to the next tool in the workflow. It does not explicitly explain pagination (limit/offset) or sorting, but those are fully documented in the schema. The description is adequate for an agent to use the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the filtering intent in plain language ('Optionally filter to datasets that contain a specific data type, cover a location or station, or overlap a date range'), which directly maps to datatypeId, locationId, stationId, startDate/endDate. It also gives concrete examples of datatype IDs (e.g., 'TMAX', 'PRCP') and dataset IDs, making the parameters more actionable.

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 clear verb+resource: 'List available NOAA CDO datasets with their IDs, names, and temporal coverage.' It distinguishes itself from siblings by explicitly positioning itself as a discovery tool: 'Use this first to discover available datasets before calling noaa_climate_fetch_data.' This makes the tool's role unambiguous.

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

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

The description gives explicit guidance on when to use this tool ('Use this first to discover available datasets before calling noaa_climate_fetch_data') and mentions the optional filters that shape usage. It does not explicitly state when NOT to use it or list alternatives beyond fetch_data, but the context is sufficient for an agent to choose it appropriately.

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, so the safety profile is covered. The description adds useful behavioral context: the scale ('Hundreds of types exist across all datasets'), the meaning of common type IDs (e.g., TMAX, PRCP), and the fact that filtering is optional. This goes beyond the schema without contradicting 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 four sentences, each earning its place: purpose, two usage patterns, an explicit when-to-use note, and a list of common types. It is front-loaded with the core action and avoids redundancy.

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

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

Given that the tool has an output schema (not shown but signaled) and 100% schema parameter coverage, the description adequately covers the orchestration need: it explains the tool's role in the workflow, how to filter, and what to expect in terms of scale. Nothing critical is missing for an agent 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 coverage is 100%, so baseline is 3. The description adds value by explaining how datasetId and datacategoryId are used with concrete examples ('TEMP' for temperature), and it enumerates common GHCND type IDs with their meanings. This enhances parameter understanding beyond the schema's terse 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 a specific verb-object ('List available data types') and gives concrete examples (TMAX, TMIN, PRCP, SNOW), making the purpose unmistakable. It also differentiates from the sibling tool noaa_climate_fetch_data by explicitly noting this is a precursor step when type IDs are unknown.

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 an explicit usage directive: 'Use this before calling noaa_climate_fetch_data when the data type IDs are unknown.' It also explains the two primary filtering modes (datasetId or datacategoryId), giving agents clear conditional guidance on when to select this tool over others.

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=true, but the description adds behavioral context: 'NOAA CDO ignores dataset, location, station, and date filters here, so none are offered.' This tells the agent why those parameters are absent and how the API behaves, which goes beyond the annotation. It also notes the total count (12 categories), which is useful for verification. No contradiction with annotations.

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

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

Two sentences, front-loaded with the core purpose and the category list. Every sentence contributes value: the first defines the tool and its relationship to find_locations, the second gives usage timing and a behavioral constraint. No fluff or 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?

The description covers purpose, usage conditions, behavioral constraints, and references the output schema implicitly. With full schema parameter coverage and an output schema present, nothing essential is missing. An agent can correctly decide to call this tool and know how to construct the request.

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

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

Schema description coverage is 100%, so all four parameters (limit, offset, sortField, sortOrder) are already documented in the schema. The description only summarises them as 'pagination and sort' without adding deeper semantics like sort field recommendations or pagination edge cases. Baseline 3 is appropriate since the schema carries the load.

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

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

The description clearly states the verb 'List' plus the resource 'location categories' and specifies it scopes noaa_climate_find_locations. It enumerates all 12 categories explicitly, making the purpose unambiguous and distinct from sibling tools that perform other operations like finding locations or fetching data.

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

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

It gives explicit when-to-use guidance: 'Call this first when you do not know which locationCategoryId to pass', including a specific mention of hydrological categories. It also clarifies that only pagination and sort are accepted, and that other filters are ignored, preventing the agent from attempting unsupported parameters. This is strong directional 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?

Annotations only provide readOnlyHint and openWorldHint, so the description carries the transparency burden. It discloses non-obvious behaviors: damage arrives as magnitude-suffixed strings and is parsed, unreported damage is omitted rather than zeroed, minDamageInUsd excludes unreported rows and reports how many were dropped, results come in source row order, and totalCount is the true match count for the full year. This far exceeds what annotations convey and contains 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?

Although long, every sentence earns its place: the main purpose is front-loaded, then the contrast with CDO tools, then filter specifics with examples, then the critical damage-parsing and pagination/totalCount behaviors. Dense but efficiently organized 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?

For a tool with 7 parameters, 1 required, and an output schema, the description covers everything an agent needs to call it correctly: the required year, filter semantics with examples, the tricky damage exclusion behavior, ordering, pagination, and the meaning of totalCount. Nothing important is missing, and the output schema handles return details.

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

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

Schema coverage is 100%, so baseline is 3. The description adds meaningful semantics beyond the schema for minDamageInUsd (omission behavior, exclusion logic, reported drop count) and clarifies the damage string format. However, for state and eventType it largely repeats schema examples, so it doesn't fully earn 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?

States a specific verb ('Search'), a specific resource ('NCEI Storm Events Database'), and a well-scoped subject (one calendar year of events). It enumerates event types and fields returned, and explicitly differentiates from the CDO tools on the server, making it easy for an agent to distinguish this from 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 contrasts with CDO tools ('different NOAA corpus... discrete severe-weather events rather than station observations'), states that no token is needed, and explains why year is required ('published as one bulk file per year'). This gives an agent clear when-to-use and when-not guidance, including the condition that drives the required parameter.

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