Smarter Weather

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint, providing safety profile. Description adds behavioral specifics: batched call, returns comparison matrix, accepts place names directly. 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 plus a focused example. No fluff. Purpose stated first. 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 4 parameters, 2 required, and presence of output schema, the description covers purpose, differentiation, and usage example. Agent has enough context to invoke correctly.

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

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

Schema provides 100% coverage with descriptions for all 4 parameters. Description reinforces with an example showing typical usage (locations, variables, hours), adding concrete semantics beyond schema.

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

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

Description clearly states verb 'compare' and resource 'forecast variables across multiple locations', specifies it returns a 'distilled per-location series matrix', and distinguishes from siblings by recommending it over sequential forecast calls.

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 'prefer this over N sequential forecast calls', indicating it's for multi-location comparison. Does not explicitly state when not to use, but implied that single-location tools are alternatives. Clear enough for agent 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds that it returns standard names, units, descriptions, and time range, providing useful behavioral context beyond annotations without contradicting them.

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 plus an example, no unnecessary words, front-loaded with main purpose. Example enhances clarity without adding bulk.

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?

Output schema exists, so description doesn't need to detail return format. It covers the key outputs (names, units, descriptions, time range) for a discovery tool. Simple and 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% with dataset_id well described. The description adds that valid values can be discovered via list_datasets, but this reinforces rather than adds new meaning. Baseline 3 is appropriate.

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

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

The description clearly states it returns variables with names, units, descriptions, and time range. It also distinguishes itself from query_dataset by advising to use before querying. This is specific and differentiates from siblings like list_datasets.

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 before query_dataset to discover valid variable names' and includes an example. Provides clear context for when to use, though does not explicitly state when not to use.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint as false. The description adds that it scans the forecast and returns daylight-aware periods, which is useful behavioral context beyond annotations. 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 sentences plus an example. The first sentence front-loads the core purpose. The second adds scanning and daylight detail. The example is illustrative without being verbose. 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 complexity (8 params, nested criteria, output schema exists), the description covers the main behavior. It does not explain edge cases like no matching window, but the output schema likely covers return values. Overall 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 description coverage is 100%, so baseline is 3. The description adds value with an example that illustrates parameter composition (e.g., criteria and location) and clarifies that criteria values are in the selected units system, which reinforces schema but provides cohesion.

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 that the tool finds the optimal time window for an activity based on weather criteria, specifying that it scans the forecast and returns daylight-aware periods. This distinguishes it from sibling tools like get_forecast which only retrieve raw data. The example further clarifies the purpose.

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 when needing an optimal weather window rather than raw data, but does not explicitly state when not to use or list alternatives. The example provides a concrete use case, which is helpful for selection.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds that the tool covers CONUS only and explains the AQI scale, but does not disclose potential rate limits or data refresh behavior. This is adequate given annotations.

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

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

The description is two sentences plus an example, with no wasted words. Key information (CONUS scope, AQI scale, default vs extended calls) is front-loaded, making it easy to scan.

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 an output schema exists (not shown but mentioned), the description sufficiently covers location input, pollutant options, forecast flag, and the AQI scale. The CONUS constraint is explicitly stated, and the tool's behavior as a read-only, idempotent operation is clear from annotations.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining the default pollutants as a 'cheap headline call,' clarifying when to use include_forecast, and providing an example that ties parameters together. 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?

The description clearly states the tool gets AirNow air quality (AQI and per-pollutant) for CONUS locations, with both current and forecast data. This distinguishes it from sibling tools like get_current_conditions or get_forecast, which focus on weather rather than air quality.

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 explains when to use the default pollutants=["aqi"] as a 'cheap headline call' versus adding other pollutants or include_forecast for deeper detail, plus provides an example. It does not explicitly contrast with sibling tools, but the purpose clarity compensates.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description carries a lower burden. It adds behavioral details: ‘at’ parameter omission means current snapshot, ‘alert_id’ returns detail+geometry ignoring ‘at’, empty result means all-clear or purged (~24h), and location-geocoding defaults. 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 dense but not verbose, packing key behavioral rules into a few sentences. It is front-loaded with the purpose statement. The final example is helpful but adds length. Minor deduction for over-compressed readability; still 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 high schema coverage (100%) and presence of output schema, the description adequately covers edge cases (city/state confusion, empty result meaning, at/alert_id interaction) for a tool with 7 parameters and nested objects. It does not detail output structure but defers to schema. Slight gap in not covering error scenarios or rate limits, but overall sufficient.

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. The description adds contextual meaning beyond schema, such as interpreting ‘at’ omission as current snapshot, specifying ‘alert_id’ ignores ‘at’, and clarifying location geocoding ambiguity (city vs state). However, it does not elaborate on bbox subfields or event-name filtering beyond the schema.

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

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

The description clearly states the tool retrieves NWS watches, warnings, and advisories, specifying querying via point (city/ZIP/lat+lon) with containing polygons or bbox/state/DC/CONUS with intersecting polygons. This distinguishes it from siblings like get_observations or get_forecast, though the description is dense and slightly obscure.

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 location vs bbox vs state vs city, warns against misinterpreting a city miss as statewide all-clear, and clarifies state naming (‘NY/WA’) vs city names (‘New York’). It does not explicitly exclude alternative tools but offers detailed usage rules.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, establishing the tool as safe and non-destructive. The description adds context beyond annotations: it gets data from the nearest station with a record, covers dates by day of year, and clarifies that these are long-period averages (not random access to specific years). 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 four sentences long, each sentence adds distinct value: what it does, what it returns, use cases, and pairing advice. It is front-loaded with the core purpose. Minor improvement could be structuring with bullets, but current text is efficient and clear.

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

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

Given the tool has 6 parameters (2 required) and no output schema, the description sufficiently explains the data source (NCEI 1991-2020), what fields are returned (normal high, low, mean, station, distance), and the date handling (day-of-year). It does not detail output format or error conditions, but the annotation hints (readOnly) mitigate risk. Overall complete for an agent to decide usage.

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 each parameter has a description in the schema. The description adds value by explaining the date semantics (day-of-year basis, meaning the year in start/end is ignored for climate data) and that the tool covers US locations (though lat/lon globally valid). This provides context not present in the 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 starts with a specific verb-resource pair: 'day-of-year climate normals (NCEI 1991-2020 30-year averages) for a US location'. It clearly lists what is returned (normal high, low, mean, station, distance) and explicitly distinguishes from sibling tools like get_forecast and get_climate_records by stating it is not a forecast nor observed history for a specific year.

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

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

The description provides concrete example questions that trigger its use: 'is this warm for October?', 'what is a typical high here in January?', 'how does this week compare to normal?'. It also advises pairing with get_forecast for anomaly detection. It does not explicitly list when NOT to use it, but the examples imply it is for baseline comparisons, not for specific year 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 destructiveHint=false, indicating a safe read operation. The description adds behavioral context by specifying the data sources ('CLI daily climate reports', 'RER record event reports') and the effect of filtering parameters, which goes beyond the basic annotations.

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

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

The description is two sentences that efficiently cover the tool's purpose, types, filtering options, and examples. It is front-loaded with the core behavior and well-structured, though a slight reorganization could improve readability.

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

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

With an output schema present, the description does not need to explain return values. It covers all input parameters, their roles, and usage patterns. The examples provide practical guidance, making the definition complete for its complexity.

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

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

Schema description coverage is 100%, but the description adds significant value: it explains the semantic difference between the two types, clarifies that 'station' applies only to reports and 'record_type' only to records (not in schema), and gives practical examples. This greatly aids understanding beyond the schema.

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

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

The description clearly states it returns NWS daily climate data for two specific types ('reports' and 'records'), with explicit details on content (observed high/low/precip vs record highs/lows/rainfall). This distinguishes it from sibling tools like get_observations or get_forecast, which serve different purposes.

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 explains when to use each type parameter ('type=reports' vs 'type=records') and provides example parameter combinations. It does not explicitly list when not to use the tool or mention alternatives among siblings, but it gives sufficient context for correct invocation.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds behavioral context by revealing the two data sources (RTMA updated sub-hourly, METAR ground truth) and their complementary roles. This goes beyond the annotations without contradicting them.

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

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

The description is two sentences plus a succinct example. It front-loads the main action and key differentiator (two sources), and every sentence adds value without redundancy. The example is minimal but illustrative.

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 of combining two data sources and the existence of an output schema, the description adequately covers the return values (analysis and station data). It could mention that results are from both sources, but the context is sufficient for an agent to understand the tool's behavior.

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

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

The input schema has 100% coverage of parameters. The description adds an example of the location parameter and explains the role of each source, which enriches the schema documentation. However, the schema itself already describes lat/lon ranges and location format adequately.

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

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

The description clearly states the tool provides current weather from two independent sources (RTMA and METAR) in one call, and distinguishes it from sibling tools like get_forecast. The verb 'get' combined with 'current conditions' and the explicit mention of sources makes the purpose unmistakable.

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

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

The description explicitly advises when to use each source ('analysis for point-accurate values and the station for verification') and directs to get_forecast for forecasts. This provides clear guidance on tool selection and usage context.

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

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

Annotations declare readOnlyHint, idempotentHint, non-destructive. Description adds that data is pre-aggregated and unit-converted server-side, and accepts place names directly. 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?

Single focused paragraph front-loading the core purpose and usage guidance. Each sentence adds value; no redundancy.

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

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

Given the wealth of sibling tools, the description is complete: it explains return sections, mentions hourly via sibling tool, and schema covers all parameters. Output schema further reduces need to detail return format.

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 params. Description adds examples of valid location inputs and clarifies mutual exclusivity of location vs lat/lon. Explains include default and detail_level meaningfully.

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 'Complete weather overview' and lists included data (current conditions, daily forecast, alerts, outlooks). It specifies it's the primary weather tool, distinguishing it from lower-level alternatives.

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

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

Explicitly states: 'reach for lower-level tools only when you need raw observations or a specific dataset', providing clear when-to-use and when-not-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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description need not repeat safety traits. It adds valuable behavioral context: summary_only=true returns only the LLM summary without the full body, type=two is the text TWO (not the GIS product), and WPC files ERO days 1-3 under one product. These are nuanced behaviors beyond what annotations convey, which helps the agent set expectations.

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

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

The description is long but densely packed and well-structured: it lists type codes first, then special rules, then examples. No sentence is wasted—every clause carries unique information (e.g., 'type=two is the text TWO, not GIS nhc_two'). It is appropriately sized for a tool with 18 product types and 9 parameters, though a bulleted format might slightly improve scanning.

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 18 product types and 9 parameters, the description covers all essential aspects: product taxonomy, location requirements, day behavior, summary_only flag, awips_id usage, and two representative examples spanning local and national types. An output schema is present to document return values, and annotations cover safety traits. The description is complete enough for an agent to invoke the tool correctly without additional documentation.

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 already provides full descriptions for all 9 parameters (100% coverage), so the description does not need to restate them. Instead, it enhances semantics by clarifying interactions: 'day' is ignored for other types, national types need no location, and pmd expects an awips_id (e.g., PMDSPD). The examples further illustrate valid parameter combinations (location+type and type+day+summary_only), adding value over the schema.

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

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

The description opens with 'Expert forecaster text products,' which clearly identifies the resource as human-authored discussions rather than raw model data. It then enumerates all 18 product types with specific meanings (e.g., afd=Area Forecast Discussion, mcd=SPC Mesoscale Discussion), distinguishing this tool from sibling tools like get_forecast, get_outlooks, and get_tropical. The scope is precise and unambiguous.

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

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

The description provides concrete usage guidance: it states that national types (swo/fwd/ero/tcd/tcp/tcm/twd/two/pmd/pwo) need no location, that 'day' selects the outlook day for swo and fwd, and that pmd requires an awips_id for a specific desk. It also gives two representative examples. It stops short of explicitly naming alternatives or saying 'use this instead of X,' which would earn a 5, but the context is clear enough for correct selection.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description isn't burdened with stating it's a safe read. It adds meaningful interpretive context beyond annotations: explaining how to read percentile outputs (which tail matters per hazard type) and that a single percentile is not the forecast. This is valuable behavioral/orientation guidance that annotations cannot convey.

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

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

The description is lengthy but every sentence earns its place—it packs dense, non-redundant value: purpose, when-to-use, percentile-reading guidance, aspect coverage, and examples. The function-calling example block is a strong front-loaded practical aid. It's long but not bloated; if anything the percentile-reading section could arguably be trimmed, but the density is high and justified for a complex multi-aspect tool.

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

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

This is a high-complexity tool (8 aspects, 5 parameters, but only 1 required). The description comprehensively covers aspect semantics, interpretation of output, and usage guidance, and an output schema exists so return values needn't be explained. Minor gaps: it doesn't detail the exact structure/shape of the returned distribution or how hours interact with each aspect beyond the default note, but overall it's thorough for the complexity level.

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%, fully documenting lat/lon/location/hours/aspect, so the baseline is 3. The description adds some value by naming the aspect values (precip, snow, ice, temperature, wind, severe, aviation, confidence) and listing what each returns, and clarifying that hours default varies by aspect (48-72), but most parameter detail is already in the schema. It slightly exceeds baseline but doesn't dramatically expand on schema semantics.

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

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

The description states a specific verb+resource ('get... forecast guidance from NBM'), explicitly defines the output scope (percentile ranges, exceedance probabilities, ensemble spread), and clearly differentiates itself from siblings like get_forecast and get_hourly_forecast by emphasizing the probabilistic nature that deterministic tools cannot provide. The examples and aspect breakdown further sharpen the purpose.

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?

Excellent when-to-use guidance: it explicitly gives interrogative triggers ('how much could we get', 'worst case', 'how sure is this') and states that 'a deterministic forecast value cannot answer one,' directly contrasting with the deterministic get_forecast sibling. It also provides reading guidance (p50, p90, p10 semantics) and explicit examples with location and aspect, plus a coverage list of aspects.

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 idempotent and read-only behavior. The description adds crucial behavioral details: rolling coverage window, unmatched model samples, designation of truth field, conditional regimes with fallback, and proper handling of null values (e.g., 'null means not enough persist pairs, not zero skill'). 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 extremely dense and lengthy, covering many edge cases and interpretations in a single paragraph. While information-rich, it lacks conciseness and structural breaks, making it harder to quickly scan. Every sentence is valuable, but the overall length reduces readability for an AI agent.

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 complex tool with 9 parameters, no required fields, and an existing output schema, the description covers all necessary context: output metric meanings, scope preferences, regime fallback logic, cross-model and cross-regime comparison prohibitions, and the handling of rare events and null values. It leaves no critical 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% with detailed parameter descriptions. The description adds value by explaining the regime parameter's fallback mechanism, how to interpret lead_hours approximations, and the relationship between location precision and the three output scopes. However, much of the description focuses on output interpretation rather than parameter meaning.

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 forecast accuracy metrics (bias, MAE, RMSE, skill score) measured against observed truth. It distinguishes itself from sibling tools like get_forecast (raw forecast values) and get_forecast_distribution (probability distribution) by focusing on skill assessment.

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 on when to use the tool: to qualify forecasts, answer trustworthiness, bias, and accuracy questions. Includes strong warnings against comparing models using unmatched samples, comparing entries with different truth fields, and misinterpreting null values. Also advises on regime usage and scope selection.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint. The description adds behavioral context: it computes from daily max/min temperatures, uses forecast horizon, and switches response mode based on season_start. This enhances understanding beyond annotations.

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

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

The description is well-structured, starting with a clear definition, then providing usage details. While slightly verbose, every sentence adds value and is 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 the complexity (11 parameters, no output schema), the description covers the two main modes of operation, parameter roles, and example use cases. It is thorough but could mention location constraints beyond US or data source limitations.

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 by explaining parameter interactions (e.g., crop with base_temp_c, season_start switches response), defaults, and usage patterns. It goes beyond mere parameter listing.

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 computes Growing Degree Units for US locations, with specific details about crop thresholds and cumulative totals. It distinguishes itself from sibling tools, which are generic weather tools, by focusing on GDU calculations.

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 explains when to use it (for GDU with crop or custom thresholds, with or without season_start) and provides example questions. However, it does not explicitly mention when not to use alternatives or provide exclusions, which would strengthen the 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?

Beyond the readOnly/idempotent annotations, the description discloses critical sampling behavior: hourly_coverage reports first_time/last_time, sample_interval_hours '(past the first day rows are every 2-3h, not every hour)', truncation, and the instruction to not answer from the nearest row when the hour is after last_time. It also notes timestamps are UTC ISO 8601. This is rich, non-obvious behavioral context that fully discloses the tool's quirks.

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?

Though lengthy, every sentence earns its place. The description front-loads the core output, then moves to 'now' snapping, timezone, usage guidance, edge cases, and examples. It is logically structured with no filler and avoids repeating schema details already present in the input schema.

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

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

Given the tool's complexity (8 params, no required params, output schema present), the description covers all essential operational aspects: how to request data, how to interpret coverage, how to handle truncation, timezone conversion, and example payloads. The output schema handles return-value detail, so the description is sufficiently 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%, so the baseline is 3, but the description adds meaning beyond the schema: it explains the efficiency of days (one call with days:4), the behavior of hours_from/hours_to ('it comes back hour by hour even where the full range would be sampled'), and emphasizes location flexibility. These clarifications help an agent pick and combine parameters 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 'Blended hourly forecast' and enumerates the exact fields (temperature, feels-like, humidity, wind, precipitation probability/amount, conditions, icon) and clarifies behavior like 'Snapped to the current hour so hourly[0] is now'. This clearly distinguishes it from sibling tools like get_current_conditions or get_forecast by specifying the hourly granularity and scope.

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

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

Provides strong usage guidance: 'Ask for the days you need up front -- one call with days: 4 beats four calls', 'ALWAYS check hourly_coverage before answering about a specific hour', and handling for hours beyond last_time. However, it never explicitly names alternatives or states when not to use this tool versus sibling forecast tools, so it falls short of a 5.

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

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

Annotations already indicate readOnly, idempotent, non-destructive. The description adds value by explaining that a zero flash count is not a data gap but a quiet observation, and that results are scoped to the window in `scope`. No contradictions.

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

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

The description is concise (3 sentences plus an example) and front-loaded with the essential purpose. Every sentence adds value without redundancy.

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

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

Given the presence of an output schema, the description adequately covers the tool's behavior, edge cases (zero flash count), and appropriate usage. It does not need to repeat return values.

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, so parameters are well-documented. The description does not add much beyond the schema, except for an example usage that reinforces the 'location' parameter. This meets the baseline of 3.

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 real-time lightning data (GLM satellite flash count and MRMS ground-truth density + probability) near a location. It specifies the spatial and temporal scopes (30km/10min) and includes an example, effectively distinguishing it from sibling tools like get_current_conditions or get_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?

It explicitly states when to call: 'Only call when storms may be active or the user asks about lightning.' This guides AI on appropriate context. While it doesn't list specific sibling alternatives, the distinction from other weather tools is implied.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds significant behavioral details: time handling (forecast vs. analysis), layer drawing order (bottom-to-top under basemap labels), legacy code aliases, per-site key availability, and the effect of omitting product. 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 longer than average but earns its length. It is well-structured: purpose first, then simple form, then composed form, then product details, then time, then geographic advice. Every sentence adds useful information. Minor redundancy ('Simple form' vs 'Composed form' sections could be slightly tighter, but overall it's clear and organized.

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, nested objects, multiple modes, no output schema), the description covers all necessary aspects: both usage modes, product selection, radar key syntax, alert filters, time handling, geographic coverage, default behavior, and return value. It also addresses edge cases like missing radar keys and Alaska/Hawaii. The return value is briefly described ('rendered image plus per-layer resolved valid times'), compensating for the lack of an output schema.

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

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

Despite high schema_description_coverage (80%), the description adds enormous value beyond the schema. It explains the meaning of product IDs (e.g., 'mrms_qpe_01h_pass2_conus'), radar key syntax ('nexrad_l3:{SITE}:{KEY}'), alert filter semantics, the scene document structure with an example, and the behavior of the 'time' parameter. This transforms the schema into a practical guide for correct usage.

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: 'Render a weather map image for visual analysis.' This clearly distinguishes the tool from sibling tools that return data tables or text (e.g., get_forecast, get_observations). It also explains two distinct usage modes (simple and composed), further refining the purpose.

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 extensive guidance on when to use the simple form vs. the composed scene form, how to select products (e.g., preferring local sites for Alaska/Hawaii, using future-radar products for future times), and when to retry with different radar keys. It explicitly advises 'do not claim that capability is missing' for future radar. However, it does not explicitly compare this tool to sibling tools like get_forecast or get_observations, which would clarify when not to use a map image.

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 the tool is read-only, non-destructive, and idempotent. The description adds valuable behavioral context: it explains the two operational modes, the data fields returned, and that 'n' is ignored in station mode. This goes 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?

The description is extremely concise—just two sentences. It front-loads the key data returned and efficiently explains both modes with examples. Every sentence contributes meaningful information with no redundancy.

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

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

Given the tool's complexity (6 parameters, two modes, mode-dependent parameter behavior), the description is complete. It covers all modes, provides example inputs, lists output data, and since an output schema exists, return value details are unnecessary. No gaps remain.

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 schema covers all 6 parameters with descriptions achieving 100% coverage. The description adds semantic value by explaining that 'n' is ignored in station mode, that 'location' accepts multiple formats (city, city+state, ZIP, lat,lon), and provides examples. This enriches understanding beyond the schema alone.

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

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

The description clearly specifies that the tool returns METAR surface observations (temperature, wind, etc.) and distinguishes two modes: nearest mode (returns closest stations to a location) and station mode (returns history for a specific ICAO identifier). The purpose is specific and well-differentiated 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?

The description explains when to use each mode with concrete examples, e.g., 'nearest mode (default) returns the closest N stations to a location; station mode returns history for a specific ICAO identifier.' It provides example JSON inputs. While it doesn't explicitly state when not to use the tool, the guidance is clear and 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 indicate readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable context: what each hazard family returns, that narrative is included per day, and that empty results are not failures. This goes beyond the annotations without contradicting them.

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

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

The description is slightly long (4 sentences plus examples) but well-structured: starts with a clear purpose, then details each hazard, explains include_narrative, and ends with examples. It is front-loaded with the main purpose, though some details could be condensed.

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 availability of an output schema (not shown but mentioned), the description does not need to explain return values. It covers all essential aspects: purpose, parameter semantics, behavioral notes, and examples. It is complete for an AI agent to select and invoke the tool correctly.

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

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

Schema coverage is 100% with descriptions for all parameters. The description adds significant meaning: it explains the hazard enum values in detail, provides usage context for include_narrative, and gives concrete examples. This elevates understanding beyond the schema alone.

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

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

The description clearly states the tool returns hazard outlooks affecting a location, and distinguishes four hazard families (severe, fire, rain, heat) with specific details for each. This provides a specific verb+resource and separates it from sibling tools like get_forecast or get_alerts.

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 explains when to use each hazard type and includes guidance on the include_narrative parameter. It also clarifies that an empty result means no outlook covers the point, setting proper expectations. However, it does not explicitly state when not to use this tool versus alternatives like get_forecast.

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?

Description adds important behavioral details beyond annotations: it notes that period boundaries should use user's local timezone (not UTC midnight) and that response includes converted value and unit per period. No contradiction with annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint all consistent).

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

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

Description is well-structured: starts with purpose, then behavioral notes, use cases, and an example. No unnecessary repetition. Length is appropriate for the tool's complexity (8 parameters, 2 required). Could be slightly more concise but still 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 tool's moderate complexity (8 params, 2 required, 100% schema coverage, output schema exists), the description covers key aspects: what it does, period timezone handling, aggregation types, and example usage. Meets requirements for a read-only aggregation 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%, baseline 3, but description adds meaningful context: guidance on aggregation choices (sum for precipitation, max for temperature, etc.), mentions location can be a place name directly, and includes a complete example. These add value 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?

Description clearly states it aggregates a weather variable over time periods and returns server-computed totals, maxima, minima, or averages. Specific examples like 'total rainfall today and tomorrow' and 'peak wind speed this weekend' distinguish it from siblings like get_forecast or get_current_conditions.

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

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

Explicitly provides ideal use cases with examples ('total rainfall today and tomorrow' and 'peak wind speed this weekend'). Implicitly suggests using this tool for period-based aggregation but does not explicitly state when not to use it or name alternatives, though sibling context is available.

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 valuable context: it discloses that data is refreshed every 5 minutes, describes the output content (states, incidents, advisories), and provides interpretation guidance. The 'No inputs' statement is slightly misleading due to the optional parameter, but overall it enhances transparency.

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 relatively short and front-loaded with the output description. However, the inaccurate statement 'No inputs' wastes words and could mislead, detracting from conciseness and accuracy. It could be improved by removing that phrase.

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 simplicity (one optional boolean parameter) and the presence of annotations and an output schema, the description is reasonably complete. It covers the tool's purpose, usage context, and behavioral nuances. The only gap is the minor inaccuracy about inputs, but overall it provides sufficient context for an agent.

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

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

Schema coverage is 100% and the schema adequately describes the optional 'include_ok' parameter. However, the description says 'No inputs,' which contradicts the schema and adds no value; it may confuse an agent about the optional parameter. Thus, the description does not improve 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 provides data-freshness status of the weather platform, including overall state, per-source states, incidents, and advisories. It distinguishes from sibling tools by focusing on platform health rather than weather data, and specifies when to use it.

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 tells when to use this tool: when a user asks about data freshness, when other tools return stale data, or before presenting time-critical weather. It also gives guidance on how to handle degraded sources. However, it does not explicitly mention when not to use it or list 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 indicate readOnlyHint=true and idempotentHint=true, so the description does not need to reiterate that. However, it adds behavioral context: the hazard parameter covers 'NWS HeatRisk days 1-3' and explains the level meanings. 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: two sentences plus an example JSON. It front-loads the main purpose and adds necessary context without extraneous words. Every sentence adds value.

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

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

Given the availability of an output schema (not shown) and full parameter schema coverage, the description adequately covers the tool's purpose, usage, and examples. It could have mentioned the return format but that's likely in the output schema. Sufficient for an AI 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 coverage is 100%, but the description adds value by explaining the hazard parameter's scope (HeatRisk days 1-3, levels 1-4) and providing an example usage. This goes beyond the schema's enum and default 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 provides a 'national population-exposure headline' for a risk-zone outlook product, with a concrete example ('~57M people under major heat risk tomorrow'). It distinguishes itself from sibling tools by focusing on aggregating population counts across risk bands, which is unique among the listed 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 explains when to use the tool: for risk-zone outlook products like HeatRisk, and provides guidance on using the hazard parameter vs. product_id. It does not explicitly list when not to use it or compare to siblings, but it gives enough context for an AI agent to understand the intended use case.

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 readOnlyHint=true and destructiveHint=false, but the description adds value by disclosing data staleness and detailing the output structure (profile, wind_profile, derived indices). This goes 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?

The description is front-loaded with the purpose, followed by structured details on output and usage notes. It is informative without waste, though the detailed output description might overlap with the output schema. Still, it 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?

Given the complexity of sounding data and the existence of an output schema, the description covers purpose, parameter usage, output structure, data latency, and an example. It is fully complete for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value with an example ('{"location": "Norman, OK"}') and clarifies mutual exclusivity of location vs lat/lon, which is not fully captured in 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 'Nearest RAOB (radiosonde) vertical soundings to a point' with specific verb and resource. It clearly distinguishes from sibling 'get_sounding_chart' by focusing on raw data retrieval rather than chart generation.

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 context such as 'Soundings launch at 00Z/12Z so data can be hours old', giving guidance on data staleness. However, it does not explicitly state when not to use this tool or suggest alternatives like 'get_sounding_chart'.

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 the tool is read-only, idempotent, and non-destructive. The description adds value by noting that data can be stale (hours old) and that the output is a rendered chart. No contradictions exist between description and 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 very concise: two sentences plus an example. It front-loads key information and avoids redundancy. Every sentence adds value, making it efficient and well-structured.

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 parameters, no required, no output schema), the description covers essential aspects: what the chart contains, data freshness, and how to use 'location' via an example. It is sufficient for an agent to understand usage, though it lacks details on image format or payload size limits.

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 parameters adequately. The description provides general context and an example using 'location', but does not add significant new meaning for individual parameters beyond the schema. A score of 3 is appropriate per guidelines.

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 that the tool renders the nearest RAOB sounding as a Skew-T log-P + hodograph chart, listing specific chart elements. It distinguishes itself from the sibling tool 'get_sounding' by noting that the latter provides raw profile numbers. This makes the purpose highly specific and distinct.

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 includes an explicit alternative ('Use get_sounding for the raw profile numbers') and an example. It also hints at timing constraints (data can be hours old due to 00Z/12Z launch times). However, it does not provide explicit conditions for when not to use this tool, leaving some ambiguity.

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 readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds context by stating it uses NEXRAD Level III algorithm output from the nearest radar site and explains the meaning of empty results. This goes beyond what annotations provide, though it could further detail data freshness or limitations.

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

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

The description is concise at three sentences, with the first sentence immediately stating the tool's purpose and key outputs. There is no extraneous information, and the structure is well-organized and 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?

With 4 optional parameters, full schema coverage, and an output schema, the description covers the main purpose, usage context, and expected empty result behavior. It could optionally mention that the output includes derived metrics like velocity, but the output schema likely covers that. Overall, it is sufficiently complete for an AI 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?

All four parameters are described in the schema (100% coverage). The description provides an example using the location parameter but adds no additional semantic meaning beyond the schema. Baseline 3 is appropriate as the schema already does the heavy lifting.

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

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

The description clearly states it returns radar-identified storm cells near a location, listing specific outputs like tracks, hail index, mesocyclone detections, and TVS. It includes an example, distinguishing it from sibling tools like get_storm_reports (likely spotter reports) and get_current_conditions (general weather).

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 using it during active convection and explains that an empty result means no detected cells, which is common outside storms. However, it does not explicitly state when not to use it or contrast with alternatives like get_storm_reports or get_current_conditions.

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 value by disclosing that reports are verified (not raw observations) and clarifies that valid_time is in UTC, which prevents timezone confusion. It does not mention rate limits or data freshness beyond 'Recent,' but this transparency about the data's nature is helpful given the strong annotation coverage.

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

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

The description is concise at 5 sentences, front-loading the core action and purpose, then adding context and an example. The example at the end slightly increases length but earns its place by demonstrating usage. No superfluous 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?

Given the tool has 5 optional params, 100% schema coverage, an output schema (not shown), and strong annotations, the description is nearly complete. It could add a note about typical report count or how to filter by multiple types, but the example and type list are sufficient for most use cases.

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 value by explaining the 'valid_time' field context and providing a complete example that illustrates how parameters like location, hours, and type work together. This makes the parameter relationships clearer than the schema alone.

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

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

The description clearly states the tool retrieves recent NWS Local Storm Reports (LSRs) for tornadoes, hail, damaging winds, flooding near a location. It provides specific types and examples, and this purpose and specificity differentiate it from siblings like get_current_conditions (general weather) or get_alerts (warnings), which do not focus on verified event reports.

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 tells the agent to use this tool to confirm severe weather occurrence or assess reported damage, offering clear context. It does not directly exclude alternatives or state when not to use it, but the example ('type: H') provides concrete guidance, and the sibling set lacks a similar storm-report 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 readOnlyHint, idempotentHint, and non-destructive. The description adds extra behavioral context: data comes from the 'weather pipeline's astro product' and includes sunrise/sunset/solar times and moon phase. This goes beyond the annotations by explaining the data source and scope.

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: first sentence states what it does, second provides usage guidance with examples, third gives a concrete JSON example. It is front-loaded with purpose, concise, and every sentence adds value without redundancy.

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

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

Given the tool has three optional parameters, no required parameters, and an output schema exists, the description fully covers what the tool returns by listing all temporal components (local time, timezone, 14-day calendar, solar times, moon phase). It provides sufficient context for an agent to understand the tool's output without needing to inspect the output schema.

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

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

Schema description coverage is 100%, so the description's parameter info is supplementary. It adds value by explicitly stating it 'Accepts a place name directly' and providing an example, which reinforces how to use the location parameter. This enhances usability beyond the schema's 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 provides 'complete temporal context for a location' and lists specific components (local time, timezone, 14-day calendar, solar times, moon phase). It includes example queries that show its specific use case, distinguishing it from sibling weather tools that focus on forecasts or observations.

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

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

The description explicitly says 'Use whenever you need to reason about dates, times, or daylight for a location' and provides concrete example questions. While it doesn't mention when not to use it or alternative tools, the positive guidance is strong and contextual.

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?

The description adds value beyond the annotations by noting that including geometry results in large payloads and that an empty result indicates no activity. It also details the kinds of features and their properties. 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 and front-loaded with key information. It packs details about features, properties, and parameter behavior in a single paragraph, but could be slightly more structured with bullet points.

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 output schema exists, the description adequately covers behavior (e.g., empty result), feature kinds, and parameter effect. It provides sufficient context for a read-only tool, though it omits authentication or rate limits (not required).

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

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

With 100% schema description coverage, baseline is 3. The description adds context about the 'include_geometry' parameter, noting it adds full GeoJSON geometries (large) and providing example usage, which 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 identifies the tool as retrieving active NHC tropical systems, listing specific features like forecast cones, track lines, and coastal watches/warnings. It distinguishes from sibling tools by specifying the source (NHC) and region (Atlantic + East Pacific).

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?

While the description does not explicitly state when to use this tool versus alternatives, its specificity about tropical activity from NHC provides clear context. It implies usage for active tropical systems, but lacks explicit exclusions or alternative recommendations.

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, destructiveHint=false. Description adds context about per-dataset freshness and domain variation, enhancing transparency 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?

Three sentences plus an example, front-loaded with core purpose. Every sentence adds value. Highly concise and well-structured.

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

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

Given the simple tool, rich annotations, and output schema, description is complete. Covers purpose, output features, usage context, and provides an example.

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

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

Schema coverage is 100%, so baseline is 3. Description adds minor value by summarizing location flexibility and include_freshness behavior, but does not significantly extend beyond schema.

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

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

Description clearly states it discovers datasets at a location with freshness info, and distinguishes itself by mentioning it provides dataset_id values for query_dataset and describe_dataset. Verb 'discover' combined with resource 'datasets' is specific and actionable.

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

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

Explicitly states when to use: to find dataset_id for downstream tools and to assess data currency. Does not explicitly list when not to use or alternatives, but context is clear and helpful. Example further clarifies 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?

Beyond annotations (readOnly, idempotent, non-destructive), description adds critical behavioral details: time modes (hours, window, latest), reference_time pinning, and warning about run availability after 48 hours. This provides meaningful context for correct usage.

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 clear sections: purpose, time modes, reference_time note, sibling guidance, examples. Slightly long but each sentence contributes; could be trimmed slightly without loss.

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

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

Given the complexity (10 parameters, multiple time modes, output schema), the description covers essential behavioral patterns, warnings, and usage examples. It is complete for the tool's complexity and no major 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?

Despite 100% schema coverage, description adds significant value by explaining the interplay between time-related parameters (hours, latest, time_start/end) and providing concrete examples. This clarifies usage beyond individual 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?

Description clearly states it returns raw time series from specific datasets at a point. It distinguishes itself by mentioning power-user access to gridded products and explicitly directs to use get_forecast for blended forecasts, differentiating 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?

Provides explicit alternative for blended forecasts (get_forecast) and implies use for raw data. However, does not cover exclusions for other siblings like get_observations or get_current_conditions, though the description of 'raw time series from gridded products' gives context.

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

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

Annotations already provide readOnlyHint, idempotentHint, and destructiveHint, so the description's job is lighter. It adds value by detailing the output (city, state, county, timezone) and providing an example, which enriches behavioral understanding beyond annotations.

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

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

The description is two sentences plus an example. It is front-loaded with the core function, then usage guidance, then a concrete example. No extraneous words.

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

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

Given the tool's simplicity, annotations, and existing output schema, the description sufficiently covers purpose, usage, and expected output. It could mention error handling for invalid coordinates, but overall it is complete enough for an AI 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%, so baseline is 3. The description does not add parameter-specific meaning beyond the schema; the example uses specific values but does not clarify the lat/lon schema descriptions (which mention 'location place-name string' that is irrelevant to this tool).

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 'Resolve coordinates to a human-readable place' and specifies output types (city, state, county, timezone). It distinguishes itself from siblings like search_locations, which perform forward geocoding, and get_time_context, which deals with time.

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 when you have lat/lon but need a display name or the local timezone', providing clear usage context. However, it does not explicitly mention when not to use or name alternatives like search_locations.

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=false. The description adds behavioral context beyond that, such as fuzzy matching behavior, ranking by place importance, and multiple accepted input formats. No contradictions with annotations.

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

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

The description is three sentences plus an example. Every sentence adds value: purpose, input types/fuzzy, and usage guidance. It is front-loaded and not verbose, though slightly dense with multiple ideas in one sentence.

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 lookup tool with an output schema, the description adequately covers input types, return behavior (ranked candidates with lat/lon), and when to use it. It also explains the disambiguation use case and provides a concrete example, making it complete for the agent to decide and invoke correctly.

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

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

Schema coverage is 100% so baseline is 3, but the description adds significant semantic value by giving concrete examples for query ('Denver', 'Portland, OR', '50219') and explaining fuzzy=true for partial matching. The example with 'Springfield' enriches understanding of query and limit behavior.

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

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

The description clearly states the tool's purpose: 'Resolve a place query to candidate locations with coordinates.' It provides specific input examples and explicitly distinguishes from sibling tools by noting most weather tools geocode internally and this is only for disambiguation or presenting choices.

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

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

It explicitly says 'use this tool only to disambiguate... or to present location choices to the user,' and contrasts with 'Most weather tools accept a `location` string directly.' This gives clear when-to-use and when-not-to-use guidance, plus an example.

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