Smarter Weather

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

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it is a batched call, returns a distilled per-location matrix, and accepts place names directly. No contradiction with annotations exists.

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

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

The description is compact and well-structured: main capability first, output behavior second, usage note third, and a concrete example last. Every sentence contributes useful information without filler.

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

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

Given the rich schema, output schema, and read-only/idempotent annotations, the description covers the core behavioral contract completely: batched multi-location comparison, direct place-name input, matrix output, and preference over sequential calls. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, with all parameters already documented clearly. The description's example reinforces the expected shape but adds little semantic meaning beyond what the schema already provides. 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 a specific verb and resource: compare forecast variables across multiple locations in one batched call. It also differentiates itself from sequential forecast calls by emphasizing the 'distilled per-location series matrix' return, which separates it from sibling tools like 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?

The description explicitly says to prefer this tool over N sequential forecast calls, which conveys the primary comparison use case. It does not name a specific sibling alternative or state when to use a single-location tool instead, but the guidance is otherwise clear.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering the safety profile. The description adds useful context about what information is returned (names, units, descriptions, time range) but does not disclose additional behavioral traits such as response shape nuances or potential edge cases.

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, no filler, with the core output defined first and a concrete example second. Every sentence earns its place, and the example is directly actionable for an 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?

The tool has one simple parameter, rich annotations, an output schema, and a description that explains both the returned content and the intended usage sequence. Nothing essential is missing for an agent to select and invoke it correctly.

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

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

Schema description coverage is 100%, and the single parameter dataset_id is already well documented with examples and cross-references to list_datasets and describe_dataset. The description adds an example value ('nbm_conus') but does not materially expand beyond what the schema already provides; 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 states a specific resource (dataset) and a specific purpose: listing available variables with standard names, units, descriptions, and time range. It also distinguishes itself from query_dataset by saying it is meant to discover valid variable names before querying.

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 before query_dataset to discover valid variable names,' giving clear when-to-use guidance and naming the key alternative. It does not enumerate when not to use it or contrast with list_datasets, but the core usage direction is present and unambiguous.

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 meaningful behavioral detail beyond the readOnly/idempotent annotations: it 'scans the forecast,' returns 'daylight-aware periods,' and requires periods to match 'all conditions.' This clarifies that the tool performs analysis and filtering rather than a simple lookup. It does not conflict with annotations.

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

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

The description is front-loaded with the core purpose, then the key behavioral refinement, then a compact example. The example is long but earns its place by demonstrating the nested criteria structure. There is no filler or repetition of schema details.

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

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

The description is largely complete given the output schema and rich parameter schema: it covers units, daylight-awareness, and required criteria matching. One communication gap remains: 'optimal' is not defined (e.g., earliest window? longest? best combined score?), and there is no explicit note about behavior when no window is found. These are not fatal but keep it from being fully comprehensive.

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 a baseline of 3 applies, but the description adds a concrete JSON example showing how criteria, location, hours, and activity_duration_hours fit together. This is especially helpful because criteria is a nested object with multiple optional fields. The example clarifies the intended usage pattern beyond the schema alone.

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

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

The description states a specific verb and resource: 'Find the optimal time window for an activity based on weather criteria.' It clearly distinguishes the tool from raw forecast/data-access siblings by emphasizing criteria-based window selection, daylight awareness, and matching all conditions. This makes its 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 gives clear context for when to use the tool: when an activity needs a weather-compliant time window rather than just forecast data. It does not explicitly name alternatives or exclusion conditions, but the behavioral contrast with the many raw get_* forecast tools is apparent. A small missed opportunity is not saying 'use get_forecast if you only need raw 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 establish read-only, idempotent, non-destructive behavior; the description adds genuine behavioral context: the AirNow source, the CONUS geographic limitation, the AQI band scale, and that forecast is opt-in. No statement in the description contradicts the annotations.

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

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

Each of the four sentences earns its place: resource and return scope, AQI scale, default-versus-expanded usage guidance, and a concrete example. The identifying scope is front-loaded, and there is no filler or repetition of schema descriptions.

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

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

With an output schema present, return-format details need not be repeated. The description covers data source, geography, default behavior, optional expansions, and an example, while the schema covers coordinate/location validation and constraints. An agent has what it needs to 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?

The input schema describes all five parameters at 100% coverage, so the baseline is 3. The description adds strategy on top of the schema by labeling the default call as 'cheap' and showing a complete example combining location, pm25, and include_forecast, which helps an agent compose parameter combinations rather than merely filling names.

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 concrete resource and scope: 'AirNow air quality at a location (CONUS)' and lists exactly what is returned: current overall AQI, per-pollutant detail, and forecast. It is clearly distinct from sibling weather tools because it identifies the AirNow source and AQI domain rather than generic current conditions 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 gives clear context for when to use the tool (for AirNow AQI at a location) and provides parameter-selection guidance: the default ['aqi'] is the 'cheap headline call', and additional pollutants or include_forecast should be added 'when the user digs in'. It does not explicitly name alternative sibling tools or state exclusion criteria, which keeps it from 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?

Beyond the readOnly/openWorld/idempotent annotations, the description reveals important behavioral traits: empty results mean all-clear or data purged around 24 hours, alert_id switches to detail mode and ignores at, and location parsing treats NY/WA as states while New York/Washington remain cities. It also warns against claiming regional inventory is impossible, reinforcing the open-world hint with concrete guidance.

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 efficient, packing multiple query modes, edge cases, state-name disambiguation, temporal semantics, empty-result meaning, and an example into a few telegraphic sentences. Nothing is wasted, and the most important product-level information comes first.

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 and all parameters already documented, the description covers the remaining ambiguities an agent would face: location naming pitfalls, bbox and point semantics, alert_id detail mode, at behavior, and the meaning of empty results. There is no obvious missing context needed to 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?

Although the schema already documents all parameters at 100% coverage, the description adds real semantic value: it explains the point-versus-bbox containment distinction, clarifies that at is a snapshot selector and should be omitted for current alerts, defines alert_id behavior, and gives concrete location disambiguation rules plus a full example. This goes well beyond the baseline for fully covered schemas.

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 title "Get NWS alerts" plus the opening phrase 'NWS watches, warnings, advisories' makes the verb and resource unmistakable. It is clearly distinct from sibling forecast, observation, and climate tools because it specifically targets alert products, not general weather data.

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

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

The description gives strong operational guidance: point queries return containing polygons, bbox/state/CONUS return intersecting polygons, city misses must not be treated as statewide all-clear, and at should be omitted for current snapshots. It does not explicitly name sibling alternatives, but the tool's domain is unique enough that the routing is clear.

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

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

Annotations already mark the tool as read-only, idempotent, and non-destructive, so the description's job is to add behavioral context. It does: returns data from the nearest station with a record, includes station distance, covers any date by day of year, and explicitly states these are long-period averages, not forecasts or single-year observations. This goes well beyond the annotation metadata.

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?

Every sentence earns its place: definition, return values, usage trigger, pairing guidance, and the day-of-year caveat. The most important scoping information is front-loaded in the first sentence, and despite its length, the description remains efficient and readable.

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

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

For a read-only tool with no output schema, the description fully covers what an agent needs to select and call it correctly: what it returns, when to use it, how it relates to forecasts, and the key conceptual caveat about day-of-year averaging. No critical decision-relevant context is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds temporal semantics not present in the schema: dates are interpreted by day of year, making any past or future date valid. It also clarifies the meaning of the returned 'normal' values in terms of 30-year averages, which helps the agent reason about start/end/days parameters.

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 definition: 'Day-of-year climate normals (NCEI 1991-2020 30-year averages) for a US location, from the nearest station with a record.' It names the resource (climate normals), the scope (US location), and the return values (normal high, low, mean, station and distance). It also distinguishes itself from siblings by noting it is not a forecast and not observed history for a specific year, which differentiates it from get_forecast and get_climate_records.

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 when to use it: 'Use this whenever a question needs a baseline rather than a forecast,' with concrete examples. It also gives pairing guidance: 'Pair it with get_forecast to say how far above or below normal the coming days run.' This gives the agent clear decision criteria versus alternatives.

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

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

Annotations already establish readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior. The description adds meaningful behavioral context by explaining what each type actually returns (observed vs normals for reports; actually set records for records) and by showing example filter combinations. It does not contradict the annotations.

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

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

The description is compact and front-loaded: it starts with the core resource, immediately distinguishes the two type modes, then lists filters, and finishes with concrete JSON examples. Every sentence contributes value and the examples make invocation behavior unambiguous.

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

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

Given the rich schema with full parameter documentation, strong annotations, and an output schema, the description is complete enough for an agent to call this tool correctly. It covers the key selection logic between reports and records, available filters, and representative example calls. Nothing critical is missing.

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

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

The input schema already has 100% description coverage for all eight parameters, including formats, constraints, and type-specific applicability. The description reinforces wfo format and date format and gives examples, but it does not add substantial meaning beyond the schema. Baseline 3 is appropriate.

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

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

The description clearly states that this tool returns NWS daily climate data, and explicitly breaks out the two modes: type=reports returns CLI daily climate reports (observed values vs normals) and type=records returns RER record event reports. This makes the resource and the distinction between report types clear, and it differentiates the tool from climate-normals-focused 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 gives clear usage context by listing allowed filters (wfo, station, date, start/end range, hours lookback) and provides two concrete examples showing valid payloads. It does not explicitly name alternatives or state when not to use this tool, but the scope is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral context by disclosing that the tool combines two independent sources, that RTMA is updated sub-hourly, and that the METAR portion includes raw METAR and flight category. No contradiction with annotations.

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

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

The description is compact: three sentences and one example, with the core action front-loaded in the first sentence. Every clause contributes information—source types, update cadence, interpretation guidance, and the forecast alternative—without filler or schema repetition.

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

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

Given the rich output schema and fully documented parameters, the description covers the remaining contextual needs: what the tool returns conceptually, which source to trust for what purpose, and when to use a sibling tool instead. The example call further reduces ambiguity 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?

The input schema already documents all three parameters at 100% coverage, so the description carries little parameter burden. The example call {'location': 'Pella, IA'} reinforces that free-text location is supported, but it does not materially add meaning beyond the schema descriptions. 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 first sentence clearly identifies the operation and resource: retrieving current weather conditions at a location, using two independent sources (RTMA gridded analysis and nearest METAR station). It explicitly contrasts with a forecast need via 'For a forecast, use get_forecast,' which distinguishes it from an important sibling tool.

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 states when to use this tool ('Current weather right now at a location') and explicitly routes forecast requests to get_forecast. It also provides internal usage guidance: use the RTMA analysis for point-accurate values and the METAR station for verification, helping the agent interpret the dual-source response.

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

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

Annotations already establish read-only, non-destructive, idempotent behavior. The description adds useful behavioral context by explaining data is pre-aggregated across NBM, HRRR, GFS, RTMA, and SPC and unit-converted server-side. Minor flaw: listing CAPE and UV as part of the daily forecast slightly overstates what the default standard detail_level may include.

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 front-loads the core purpose, then adds behavioral context, routing guidance, and examples in a compact format. Every sentence contributes meaning; the JSON examples are especially efficient for showing valid parameter combinations.

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

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

Given the rich output schema, 100% parameter coverage, and helpful annotations, the description fully covers what the tool does, when to use it, and how to call it. It also provides enough sibling differentiation to guide tool selection.

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 seven parameters. The description adds value with concrete usage examples, clarification that location accepts a place name directly, and the note about server-side unit conversion.

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 names a specific verb and resource: it returns a complete weather overview for a location, explicitly listing current conditions, daily forecast, alerts, and outlooks. It also distinguishes itself as the primary weather tool, separating it from lower-level siblings like get_current_conditions and 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?

It explicitly positions itself as the default weather tool and tells agents to reach for lower-level tools only when raw observations or a specific dataset is needed. It also cross-references get_hourly_forecast for hourly detail, giving concrete routing 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?

The description discloses several non-obvious behaviors: type=two is the text TWO not the GIS product, pmd requires an awips_id for a specific desk, WPC files ERO days 1-3 under one product, summary_only returns the pipeline LLM summary, and national types accept no location. These details go well beyond the annotations (readOnly, idempotent, non-destructive) and materially improve correct invocation.

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 necessarily so, since it must document 18 product type codes. It is front-loaded with the core purpose and uses a compact semicolon-separated style with concrete examples at the end. A small deduction for redundancy: much of the type-by-type explanation is duplicated in the input schema's enum descriptions.

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 9 parameters, 1 required, a rich enum, and an output schema, the description covers all critical invocation aspects: type selection, location options, day semantics, summary_only, and representative examples. The presence of an output schema means the response format need not be described. No notable 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?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by giving concrete invocation examples, clarifying that national types require no location, and explaining the pmd desk-desk behavior with a sample awips_id. It partially repeats schema descriptions for the type enum, which keeps it from a 5.

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

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

The description opens with 'Expert forecaster text products' and enumerates every product type with a one-line explanation, making it clear this tool retrieves NWS/SPC/WPC/NHC text forecast discussions, not gridded forecast data. The name and title align with the described content, and the level of detail distinguishes it from sibling tools like get_forecast and 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?

The description provides clear context for when to use the tool and how to select among its many type values, including the rule that national types need no location and that `day` only applies to swo/fwd. It does not explicitly name sibling alternatives or state when not to use it, but the context is concrete enough that an agent can infer appropriate usage.

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

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

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds substantial behavioral context beyond annotations: how to interpret p50/p10/p90, that a single percentile is not the forecast, and how ensemble spread maps to forecast confidence. No contradiction with annotations.

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

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

The description is long but densely packed with necessary information: use cases, percentile interpretation, aspect families, and examples. It is front-loaded with purpose and when-to-use guidance, and every section earns its place given the tool's complexity. Slightly more structure, such as bulleted aspects, could improve scannability but the current prose is not wasteful.

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

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

Given the complexity of a probabilistic forecast tool with five parameters and eight aspects, the description is remarkably complete. It covers when to use it, how to read percentiles, what each aspect contains, interpretation caveats, and examples. Output schema handles return-value details, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters well. The description adds value beyond the schema by providing example payloads and expanding on what each aspect family includes, such as snow accumulation percentiles and severe-weather probabilities. This raises it above the baseline 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 states a specific verb and resource: probabilistic forecast guidance for one weather aspect, including percentile ranges, exceedance probabilities, and ensemble spread. It clearly distinguishes this from deterministic forecasts and enumerates the eight aspects it supports. The tool is easy to differentiate from siblings like get_forecast and get_hourly_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?

The description explicitly says to use this tool for questions about odds, ranges, potential, or confidence, and notes that a deterministic forecast value cannot answer such questions. It provides interpretation guidance for percentiles and concrete examples, which effectively routes an agent away from deterministic forecast 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 declare readOnlyHint/openWorldHint/idempotentHint and the description agrees with no contradiction. Beyond annotations it discloses exceptional behavioral depth: null means 'not enough persist pairs, not zero skill — do not compare it to skillScore'; regime queries degrade to ALL rather than erroring; metrics below minimumSamples are withheld into insufficientHistory; coverage is a rolling recent window over verified US variables, not all history; samples are not matched across models so cross-model comparison is invalid; entries under different regimes are alternative answers that must never be compared. This far exceeds 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?

Core purpose, return values, and the usage example are front-loaded before the caveat sections, and nearly every sentence carries real interpretive weight given the tool's complexity. It loses a point for sheer length — roughly 700 words, at the extreme end of what an agent can scan efficiently — where tighter bulleted structure would improve parsability. Every section earns its place, but the whole is longer than ideal.

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

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

For a 9-parameter tool with no required parameters and an output schema present, the description covers everything needed for correct invocation and result interpretation: three scopes with a preference rule ('prefer the most specific scope that has samples'), minimumSamples withholding, null semantics for multiple field types, regime fallback behavior, and three separate incomparability constraints (model, truth, regime). The output schema carries return structure, so nothing critical for correct use is missing.

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

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

Schema coverage is 100%, so baseline is 3. The description adds genuine interpretive semantics beyond the field-level text: model and truth carry comparability constraints ('never conclude that one model beats another', 'never compare numbers carrying different truth values'), regime gains cross-family overlap and within-family mutual exclusivity ('within SCN1: the labels are mutually exclusive'), and lead_hours gains the 'never approximated — a lead we have not verified returns no entries' warning. This is meaningful added value, though not organized parameter-by-parameter.

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

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

The opening sentence states a specific verb+resource — measuring forecast accuracy near a location against observed analysis truth — and enumerates the concrete outputs (bias, MAE, RMSE, skill score). The phrase 'qualify a forecast rather than assert it' plus the worked example ('NBM has been running 1.8F warm at 3-day leads') sharply separates this from forecast-content siblings like get_forecast or get_hourly_forecast. An agent can identify what this tool is for without inspecting sibling schemas.

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

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

The description gives explicit when-to-use signals: qualify a forecast rather than assert it, and answer 'how much should I trust this forecast', 'is the model biased here', or 'how accurate were you last month'. It also provides an example of how the answer should be phrased. However, it never names alternatives or states when-not-to-use conditions (e.g., nothing says 'for the actual forecast values, use get_forecast'), so routing relies on clear context rather than explicit exclusions.

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

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

Beyond the readOnly/idempotent annotations, the description discloses lead-time bucket selection, hex-center inclusion rules, dateline restrictions, cell shape [h3, samples, skill_score], the n ≥ 30 gating, withheld hexes, and the warning not to compare slices across models or truths. This is substantial behavioral context that annotations alone do not 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 dense but front-loaded with the core purpose and spatial-vs-point routing. Nearly every sentence carries behavioral or usage value; only the line "Requires model, variable, lead_hours, and bbox" is somewhat redundant with the required fields in the schema, and "CELL#" is slightly cryptic.

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 nested bbox parameter, output schema, and nuanced slicing behavior, the description covers all the important call-time concerns: spatial interpretation, lead bucketing, inclusion rules, dateline restriction, return cell format, and gating. Nothing critical is missing for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful semantics: lead_hours "selects the containing published bucket (20 → NBM 24)", no-slice behavior for unpublished leads, and bbox interpretation via hex center. These details go beyond the schema's property 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 opens with a specific verb and object: "Measured forecast skill as a map of res-4 hexes inside a bounding box," which clearly distinguishes it from the point-based sibling. It also explicitly contrasts itself with get_forecast_skill, so an agent can disambiguate without inspecting schemas.

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

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

It states exactly when to use this tool: "Use this when the question is spatial ... not 'how good is the forecast at this point' — that is get_forecast_skill." It also gives exclusionary edge cases, such as "returns no slices rather than a nearby one" and "The box cannot wrap the dateline," which tell an agent when the tool will not behave as expected.

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?

Even though annotations already mark this as read-only, idempotent, and non-destructive, the description adds substantial behavioral context: the response differs based on season_start, the cumulative mode includes observed history plus today plus forecast, and the tool supports calibrated crop thresholds. This goes well beyond what annotations convey and is particularly valuable with no output schema.

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

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

The description is a single dense paragraph with no wasted words. It front-loads the tool's core function and geographic scope, then explains the two modes and ends with concrete example questions. Every sentence contributes useful decision-making 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?

With no output schema, the description compensates by describing both response shapes: per-day GDU across the forecast horizon versus cumulative season-to-date totals with a per-day cumulative series. It also covers default crop behavior, custom thresholds, optional milestones, and the USA-only geographic limitation. For an 11-parameter tool, this is complete enough to guide correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaning beyond the schema by explaining the crop='custom' plus base_temp_c flow, the behavior switch triggered by season_start, and the effect of upper_temp_c on method selection. Not every parameter is elaborated in the description, but the most semantically complex ones are clarified.

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

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

The description opens with a specific verb and resource: 'Growing Degree Units (GDU / GDD) for a US location (CONUS, Alaska, Hawaii), computed from daily max/min temperatures.' It also gives two concrete representative questions, 'how many growing degree days has my corn accumulated since May 1?' and 'what's the GDU forecast this week?', making the tool's purpose unmistakable and distinct from siblings like get_forecast or get_climate_normals.

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 clearly explains when to use each mode: without season_start you get per-day GDU, with season_start you get cumulative season-to-date totals, and it explains when to use a predefined crop id versus crop='custom'. It does not explicitly name sibling tools or when-not-to-use cases, but the mode-based guidance is strong enough that an agent can decide how to invoke it correctly.

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

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

Beyond the readOnly/idempotent annotations, the description discloses important behaviors: rows are snapped to the current hour, timestamps are UTC ISO 8601, hourly_coverage reports the actual window, sampling drops to every 2-3 hours after the first day, and truncated signals upstream shortfalls. This is exactly the kind of context an agent needs to avoid answering incorrectly from a sparse or partial result.

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

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

The description is dense but every sentence earns its place: the first sentence defines the payload, the second defines temporal snapping and timezone handling, and the remaining sentences cover the coverage/truncation pitfalls and parameter combinations. It is front-loaded with the most important facts and contains no filler or redundant restatement of the title.

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

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

Given the output schema exists and annotations cover safety/idempotency, the description covers the remaining gaps: timezone conversion expectations, sampling intervals, truncated responses, how to interpret hourly_coverage, and how to request either a full multi-day range or a specific hour window. An agent calling this tool has the information needed to interpret results correctly and choose sensible parameter combinations.

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 already documents all parameters at 100% coverage, so the baseline is 3. The description adds meaningful beyond-schema semantics: the relationship between days and hours_from/hours_to, the 'one call with days: 4 beats four calls' guidance, the sampling behavior difference when using a window, and concrete JSON examples showing locations and hour ranges. This elevates it above baseline.

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

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

The description names the resource precisely: 'Blended hourly forecast: temperature, feels-like, humidity, wind, precipitation probability/amount, conditions, and icon per hour.' This is a specific, informative statement of what the tool returns. It does not explicitly contrast with sibling tools like get_forecast or get_current_conditions, but the emphasis on hourly rows and 'Snapped to the current hour' makes the tool's role clear.

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

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

The description gives concrete usage advice: ask for days up front to avoid multiple calls, check hourly_coverage before answering about a specific hour, use hours_from/hours_to for a contiguous stretch, and treat truncation explicitly. It lacks explicit when-not-to-use guidance against sibling tools, but the usage context is strong and actionable.

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

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

With annotations already providing readOnly, idempotent, and non-destructive hints, the description adds valuable interpretation context: a zero flash count means a quiet observation within the window, not a data gap, and the `summary` field is ready to use. It also explains the temporal/spatial window of the data, which is not in the annotations.

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

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

The description is tight and front-loaded, leading with the core function and data types before adding interpretive guidance and usage conditions. Every sentence earns its place, and the example is compact and useful.

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 rich annotations, a fully described input schema, and an output schema, the description covers the remaining context an agent needs: what the data represents, how to interpret zero values, the appropriate invocation window, and an example. Nothing critical is missing.

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

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

The input schema already has 100% coverage with clear descriptions for lat, lon, and location. The description adds a practical example ({"location": "Tampa"}) and reinforces that the tool is location-oriented, helping agents choose between coordinate and place-name inputs, though it does not introduce deep semantic detail beyond the schema.

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

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

Description clearly identifies the tool as retrieving real-time lightning activity near a location, with specific data sources (GLM satellite flash count, MRMS lightning density) and a 30-minute probability. It distinguishes itself from sibling weather-data tools by naming the exact resource 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?

States an explicit trigger condition: 'Only call when storms may be active or the user asks about lightning.' This tells an agent when the tool is appropriate, but it does not name alternative sibling tools for non-lightning weather queries, so it stops short of full alternatives 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, and the description adds substantial behavior beyond that: forecast products honor future times while analysis products clamp to the latest past, the return includes per-layer resolved valid times, layers draw bottom-to-top under basemap labels, and NEXRAD site-key availability may require retrying. No contradiction with annotations.

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

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

The description is long, but every sentence earns its place given 10 parameters and no output schema. It is front-loaded with the purpose and the simplest form, then moves to composed scenes, then edge cases and region-specific guidance. The structure makes the dense detail navigable.

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 complex 10-parameter tool with nested scene objects and no output schema, the description is exceptionally complete: it documents the return value ('rendered image plus per-layer resolved valid times'), parameter interactions, product-id validity requirements, time semantics, and regional caveats. Nothing an agent needs to call it correctly is missing.

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

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

Even though schema coverage is 80%, the description greatly expands meaning: it gives concrete product_id examples, explains the entire NEXRAD key format (tilt, measurement, and legacy aliases), defines alert filter fields and AND-combination semantics, provides a full scene example, and clarifies interactions like `scene` overriding product/location/zoom. The schema descriptions alone would not enable correct invocation nearly as well.

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 pair: 'Render a weather map image for visual analysis.' It clearly distinguishes the simple form (single `product` plus location and zoom) from the composed form (`scene` document), which separates it from all sibling data/forecast 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 gives explicit when-to guidance: use the composed scene form for layering multiple products/alerts, pass `time` for future-radar asks, prefer local sites or Alaska-specific products over CONUS mosaics, and omit `product` for the default hybrid precip. It even warns against claiming future-radar capability is missing. While it doesn't name sibling tools, the map-rendering purpose is unambiguous among the listed siblings.

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

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

Annotations already establish readOnly/idempotent/destructive hints, so the bar is lower. The description adds behavioral detail beyond annotations by explaining the default nearest mode, the switch to station-history mode when an ICAO is provided, and what fields the observations contain. 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 compact, information-dense, and front-loaded with the core resource before moving to modes and examples. Every sentence earns its place and the two short examples make the schema concrete without bloat.

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

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

With a 100%-covered schema, an output schema, and safety-relevant annotations, the description fills the remaining gap by explaining mode semantics and typical use cases. It is complete enough for an agent to invoke the tool correctly in either mode.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining how the parameters interact (nearest mode vs station mode) and by giving working examples for each mode, which helps an agent choose between location/station and n/hours. This goes beyond the 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?

The description opens with a precise definition: METAR surface observations from weather stations, listing the data fields (temperature, wind, visibility, ceiling, flight category, raw METAR). It clearly distinguishes the tool's two modes and differentiates it from the many forecast/alerts siblings by anchoring on surface 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 gives clear mode-selection guidance: nearest mode for closest N stations and station mode with hours for ICAO history, along with concrete JSON examples. It does not explicitly contrast the tool with sibling tools such as get_current_conditions, but the mode guidance is enough for correct usage.

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

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

Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description goes beyond them by disclosing that an empty result means no outlook covers the point, not an error, and by clarifying narrative behavior for severe/fire/rain. This is meaningful behavioral context without contradicting annotations.

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

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

The description is dense but every sentence earns its place: purpose first, then hazard-specific behavior, then the empty-result caveat, then examples. There is no filler and no restating of what the schema already provides.

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

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

With a full input schema and an output schema present, the description adds what remains necessary: per-hazard return semantics, narrative behavior, empty-result semantics, and representative usage examples. An agent has enough 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?

Although schema coverage is 100%, the description adds substantial meaning: severe returns Day 1-8 categorical risk plus tornado/wind/hail probabilities, rain returns Day 1-3 polygons, heat returns a 0-4 index, and narrative returns specific PILs. The examples also make valid parameter combinations concrete.

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 "Hazard outlooks affecting a location" and then precisely maps each hazard value to a concrete product family (SPC convective, SPC fire weather, WPC Excessive Rainfall, NWS HeatRisk). This is specific enough to distinguish the tool from the forecast, alerts, and observation 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 gives clear context for when to call the tool: when a user needs hazard outlooks at a point, and it explains how the hazard parameter selects among severe/fire/rain/heat. It does not explicitly name alternatives or when-not conditions, so it misses the top tier, but the context is unambiguous.

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, so the safety profile is covered. The description adds meaningful behavioral context beyond those annotations: values are server-computed, period boundaries should use the user's local timezone rather than UTC midnight, and the response includes the converted value and unit per period. This is valuable, non-redundant information.

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 composed of four focused sentences plus a concrete JSON example. The core action and the important timezone caveat are front-loaded, and the example earns its place by showing how parameters combine. It is slightly long due to the example but contains no fluff or redundant restatement.

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

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

For an 8-parameter tool with a fully documented input schema and an output schema present, the description is largely complete: it explains the aggregation behavior, the timezone handling, response contents, and use cases. Details like maxItems and dataset_id are already covered by the schema, so nothing critical is missing. It could mention more explicit limitations, but overall it is self-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?

Since schema description coverage is 100%, every parameter is already documented at a baseline level. The description adds a concrete example payload and clarifies the timezone semantics of period boundaries, but it does not introduce new parameter-level guidance beyond what the schema provides. 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 uses a specific verb ('Aggregate'), a clear resource (weather variable), and a well-defined scope (one or more time periods). It distinguishes itself from siblings by emphasizing server-computed totals/maxima/minima/averages and giving concrete example questions like 'total rainfall today and tomorrow' and 'peak wind speed this weekend', making its unique role immediately clear.

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

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

The description provides clear context for when to use this tool: when aggregating a variable over time periods, when local timezone boundaries matter, and when the user wants a single place name as input. It includes ideal-use examples but does not explicitly name alternatives or state when not to use it, so it falls short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds useful behavioral context beyond that: the status refreshes every ~5 minutes, incidents are categorized by cause, and the agent should warn users about potentially stale data. The phrase 'No inputs' is slightly misleading given the optional include_ok parameter, but this is more of a parameter-semantics issue than a behavioral one.

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: it front-loads the purpose, then gives usage guidance and an important staleness caveat, and ends with refresh cadence. The 'No inputs' sentence is inaccurate and unnecessary, but the rest is tight and efficient.

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

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

With an output schema present and annotations covering safety, the description does not need to explain return values in depth. It covers when to use the tool, what the status categories mean, and how to handle degraded/outage states. The only notable gap is the misleading 'No inputs' statement, which is offset by the fully described input 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?

The input schema fully documents include_ok with a clear description and default, so schema coverage is 100%. The description's 'No inputs' line is imprecise because the tool does accept an optional boolean, though it may be intended to mean 'no required inputs.' Overall, the description adds no real parameter meaning beyond the schema.

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

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

The description clearly states it returns 'current data-freshness status of the weather platform' and lists the specific contents: overall state, per-source states, open incidents, and provider advisories. This distinguishes it from sibling tools like get_current_conditions or get_observations, which return weather data rather than platform freshness.

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

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

It gives explicit use cases: when a user asks whether data is current, when other tools return surprisingly stale data, or before presenting time-critical weather. It does not name alternatives or state when not to use the tool, so it stops short of a 5.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds valuable behavioral context beyond that: it counts people at or above a minimum risk level, covers only NWS HeatRisk days 1-3, and explains that product_id overrides hazard. No contradiction with annotations exists.

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

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

Two compact sentences plus a JSON example. The core behavior is front-loaded, the hazard scope is defined, and the product_id path is stated 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 an output schema exists, all parameters are documented with 100% schema coverage, and annotations cover safety traits, the description completes the picture: it explains the product context, level semantics, hazard coverage, and how to handle other risk-zone products. Nothing essential is missing.

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

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

Schema coverage is 100%, so the schema already documents hazard, min_level, and product_id with clear semantics. The description adds a worked example and reinforces the override relationship, but it does not materially expand on the schema descriptions.

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

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

The description states a specific verb and resource: get a national population-exposure headline counting people inside risk bands at or above min_level. It also grounds the purpose with a concrete example headline and separates it from generic forecasting tools by calling out risk-zone outlook products.

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

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

The description gives clear usage context: hazard=heat covers NWS HeatRisk days 1-3, and product_id should be passed for other risk-zone products. It does not explicitly name sibling alternatives or state when not to use this tool, so it stops short of full exclusion 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 cover readOnly, openWorld, idempotent, and non-destructive behavior, so the bar is lower. The description adds useful behavioral context beyond annotations: soundings launch only at 00Z/12Z and can be hours old, and the result is the nearest sounding rather than an exact point measurement. No contradiction with annotations.

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

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

The description is front-loaded with the core operation and then gives a dense but useful breakdown of the returned data, followed by a compact example. The long data-fields sentence is somewhat verbose but earns its place by showing the tool's output shape and capabilities.

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 full schema coverage and an output schema present, the description is nearly complete: it explains what the tool returns, gives an example, and warns about data freshness. The main gap is the lack of explicit routing between get_sounding and get_sounding_chart, and the n parameter is left entirely to the schema.

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

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

Schema description coverage is 100%, with n, lat, lon, and location all described, so the baseline is 3. The description adds a concrete locator example ("Norman, OK") but does not independently clarify parameter semantics beyond what the schema already provides.

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

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

The description clearly states the tool returns the nearest RAOB vertical soundings to a point and enumerates the contained data, so the core purpose is unambiguous. It does not explicitly contrast itself with sibling get_sounding_chart, so it falls just short of full sibling differentiation.

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: call this when you need the nearest radiosonde profile data for a point, and it warns about data being hours old. However, it does not explicitly say when to prefer this over get_sounding_chart or mention any alternative tools or exclusions.

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

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

The annotations already indicate this is a read-only, idempotent, non-destructive operation. The description adds useful behavioral context beyond annotations by warning that 'Soundings launch at 00Z/12Z so data can be hours old,' which is critical for interpreting the chart's freshness. It also discloses what the rendered chart contains, giving agents realistic expectations about the output.

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 and efficient: the first sentence defines the tool and output contents, the second provides a critical staleness caveat, and the third routes to the sibling tool. Every sentence contributes actionable information without repetition or filler.

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

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

The description covers what the tool returns, the data source, the staleness caveat, and the relationship to get_sounding. With no output schema present, the listing of chart elements (temperature/dewpoint traces, wind barbs, hodograph, indices table) gives the agent a solid mental model of the result. Minor details like image format or error behavior are absent but not critical for invoking the tool correctly.

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

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

Schema description coverage is 100%, so the schema already documents every parameter in detail. The description adds only the concrete example '{"location": "Norman, OK"}', which demonstrates valid usage but does not materially enhance parameter understanding beyond the schema. A baseline of 3 is appropriate because the description does not need to compensate for missing schema documentation.

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 action and object: 'Render the nearest RAOB (radiosonde) sounding as a Skew-T log-P + hodograph chart image.' It enumerates the visual contents and explicitly separates itself from get_sounding by saying 'Use get_sounding for the raw profile numbers.' This makes the tool's purpose unmistakable and distinct among the sibling 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 clearly frames the intended use case ('for visual analysis') and provides an explicit alternative ('Use get_sounding for the raw profile numbers'). It does not fully spell out when not to use this tool, but the visual-vs-raw distinction is enough to guide an agent's 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?

Beyond the readOnly/openWorld/idempotent annotations, the description discloses that output is merged from the nearest NEXRAD site and that empty results are normal outside storms. This prevents misinterpretation and adds real behavioral context.

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

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

Three sentences, each earning its place: result contents, usage condition, and empty-result interpretation. The product list is formatted with clear parenthetical details and the example is inline rather than an extra paragraph.

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 doesn't need to restate return fields. It covers what the tool does, when to use it, and how to read an empty response, leaving no essential gap for an agent invoking it.

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 applies. The description's mention of product families mirrors the `include` enum and adds an example, but it doesn't materially extend the parameter explanations already present in 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 names a specific resource (radar-identified storm cells) and enumerates the algorithm outputs it returns (storm tracks, hail index, mesocyclone detections, TVS). This clearly distinguishes it from weather siblings like get_storm_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 gives an explicit use condition ('Use during active convection') and explains what an empty result means, which is essential for interpreting the tool. It doesn't name alternatives or exclusion criteria, but the context is sufficient for an agent to decide when to call it.

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

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

Annotations cover safety (readOnlyHint=true, idempotentHint=true, non-destructive), so the bar is lower. The description adds value beyond annotations by flagging that valid_time is event occurrence in UTC and should be cited locally, and by characterizing reports as 'verified' — a meaningful data-quality trait. No contradiction with annotations.

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

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

Four sentences, each earning its place: definition, use case, time-zone caveat, and a concrete example. The core definition is front-loaded and the example is compact and illustrative without bloat.

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

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

With a rich output schema and strong annotations, the description correctly focuses on what structure cannot convey: the UTC time semantics and the tool's evidentiary role for confirming severe weather. The only gap is the lack of explicit routing versus siblings such as get_alerts or get_storm_cells, which slightly weakens completeness.

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

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

Schema description coverage is 100%, so all five parameters (lat, lon, type, hours, location) are already documented in structure. The description's example ('location: Wichita, hours: 12, type: H') shows composition of the params but adds no new meaning beyond the schema; baseline 3 is appropriate.

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

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

The description names a precise resource ('NWS Local Storm Reports (LSRs)') with a specific verb ('get' implied by the name but the description defines the subject matter) and enumerates the content: verified reports of tornadoes, hail, damaging winds, flooding near a location. This clearly distinguishes it from siblings like get_storm_cells (radar storm features) and get_alerts (warnings/advisories), since LSRs are a distinct NWS post-event product.

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 states an explicit use case: 'Use to confirm severe weather occurrence or assess reported damage.' This tells an agent when this tool is the right choice. It does not name alternative tools or explicit exclusions, so agents might not know to prefer get_alerts for impending warnings or get_storm_cells for active tracking.

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

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

Annotations already declare read-only, idempotent, open-world, and non-destructive behavior. The description adds context beyond that: solar times come from the weather pipeline's astro product, it returns a 14-day calendar with Today/Tomorrow offsets, and it accepts a place name directly. No contradiction with annotations.

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

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

Compact and front-loaded: the first sentence states the resource and full contents, the second gives usage guidance with examples, and the third demonstrates the input format. Every sentence earns its place with no filler.

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

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

Given the read-only/idempotent annotations, 100% schema coverage, and presence of an output schema, the description fully supports tool selection and invocation. It covers what the tool returns, when to use it, and how to pass a location; structured fields handle the remaining return-format details.

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

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

Schema description coverage is 100%, so the baseline is 3 even without additional parameter detail. The description's 'Accepts a place name directly' and example add marginal nuance, but the schema already documents lat/lon and location semantics thoroughly.

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

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

States a specific verb and resource: returns complete temporal context for a location, enumerating local time, timezone, 14-day calendar, solar times, and moon phase. The rich content list and concrete example queries distinguish it clearly from sibling tools about forecasts, observations, alerts, and climate data.

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

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

Explicitly says 'Use whenever you need to reason about dates, times, or daylight for a location' and gives natural-language trigger examples like 'what time is sunset?' or 'is it dark there now?'. It does not name alternative tools or when-not-to-use conditions, so it stops 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?

Beyond the annotations (readOnly, idempotent, non-destructive), the description adds useful behavioral detail: an empty result means no active tropical activity, and include_geometry=true returns large GeoJSON geometries. This warns the agent about payload size and result interpretation without contradicting any annotation.

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?

Every sentence in the description adds value: scope, feature structure, parameter behavior, empty-result semantics, and a usage example. It is front-loaded with the resource identity and avoids any unnecessary elaboration.

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

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

With one optional parameter, rich annotations, and an output schema available, the description covers the essential call semantics completely: what data is returned, what each feature contains, how the geometry flag changes the response, and how to interpret a nempty result. Nothing critical is missing for an agent to call this tool correctly.

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

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

The input schema already documents include_geometry with a default and description, so baseline is 3. The description adds extra meaning by warning that geometry is large and by providing concrete example invocations ({} vs. {include_geometry: true}), which helps the agent choose the safe default.

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 identifies a specific resource—active NHC tropical systems—and enumerates the exact content types returned (forecast cones, track lines, points, watches/warnings, outlook areas) and basins covered. This clearly distinguishes it from the many sibling weather tools even without naming one explicitly.

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

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

The description implies when to use the tool by defining its scope (active NHC tropical activity) and explains the empty-result semantics. However, it does not explicitly state when not to use it or mention alternative tools such as get_storm_cells or get_outlooks for non-tropical severe weather.

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

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

Annotations already establish safety and idempotence (readOnlyHint, openWorldHint, idempotentHint, destructiveHint: false). The description adds useful behavioral context beyond annotations, including per-dataset freshness, latest model run, and the fact that datasets vary by CONUS/Alaska/Hawaii domain, without contradicting any annotation.

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 front-load the core behavior, then provide practical usage guidance and a concrete example. Every sentence earns its place and there is no redundant restatement of schema or annotations.

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

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

With a full input schema, an output schema, and annotations covering safety and idempotence, the description adds the remaining needed context: what datasets are listed, why the freshness matters, how to use it with related tools, and a concrete invocation example. This is complete for correct tool selection and invocation.

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

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

The input schema already provides 100% coverage with detailed descriptions of lat, lon, location, and include_freshness, so the description is not required to repeat parameter details. The description adds no substantive parameter meaning beyond the example location, which is sufficient given the schema coverage.

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

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

The description uses a specific verb ('Discover') and a specific resource ('datasets available at a location'), naming the dataset categories (model grids, analyses, observations) and the freshness information returned. It is clearly distinct from siblings like get_forecast or query_dataset, and it also explains its downstream relationship to query_dataset and describe_dataset.

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

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

The description explicitly states when to use this tool: to find dataset_id values for query_dataset/describe_dataset and to assess data currency. It does not explicitly describe when not to use it, but the intended use cases are clear enough to guide selection among a large sibling set.

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 no safety concerns need repeating. The description adds valuable behavioral context: run availability (a run older than about 48 hours may no longer be available), returned series reports reference_time or reference_times, and that results may mix runs. This goes beyond the annotations' safety profile.

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

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

The description is compact and front-loaded: it opens with the core purpose, then covers time modes, run-pinning caveat, sibling routing, and examples. Every sentence earns its place. Slightly dense, but effective for a power-user 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?

The description covers the key usage patterns (hours, window, latest), the reference_time caveat, and sibling differentiation. The output schema exists, so return format details are not the description's job. The only minor gap is that it doesn't explain what happens if no time mode is specified beyond hours defaulting to 24, but the schema covers hours default. Overall nearly complete for a tool of this 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%, so the schema already documents all 10 parameters. The description adds context by explaining time modes and reference_time semantics, but doesn't need to repeat parameter definitions. Baseline 3 is appropriate since the schema carries the heavy lifting and the description supplements with usage context.

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

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

The description states a specific verb and resource: query raw time series from a specific dataset for specific variables at a point, and explicitly names the power-user scope (NBM, HRRR, RRFS, GFS, RTMA, MRMS, air quality). It distinguishes itself from get_forecast by saying blended forecasts should use get_forecast instead.

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 when to use this tool vs alternatives: 'For blended forecasts use get_forecast instead.' It also explains the three time modes (hours, time_start+time_end, latest=true) and reference_time behavior, which tells an agent exactly which parameters to set for a given scenario. The examples further illustrate valid usage.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds concrete behavioral output (including timezone) and an example, with 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?

Three front-loaded sentences: purpose, usage condition, example. Every sentence earns its place; no fluff.

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 simple, read-only tool with an output schema, the description conveys purpose, usage, and a worked example. It does not explicitly correct the misleading 'location' note in the schema or address edge cases, so it falls just short of full completeness.

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 already covers both parameters with ranges and descriptions (100% coverage), so baseline is 3. The description adds a concrete example mapping lat/lon to a result, though the schema's lat description misleadingly mentions a 'location' string that additionalProperties=false contradicts.

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

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

States a specific verb ('Resolve') and resource ('coordinates') and enumerates the output categories (city, state, county, timezone). The example concretely differentiates it from forward geocoding (search_locations) and weather-focused 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 instruction 'Use when you have lat/lon but need a display name or the local timezone' provides an explicit condition for selection. It does not name sibling alternatives or exclusions, but the condition is sufficiently clear.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral detail beyond that: accepted query formats, fuzzy matching behavior, ranked candidates, and lat/lon output. It does not contradict annotations and gives useful operational context.

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

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

The description is compact and front-loaded with the core purpose. Every sentence adds useful information: accepted formats, fuzzy behavior, output type, usage boundaries, and a concrete example. There is no filler or repetition.

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

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

Given the rich input schema, output schema, and annotations, the description covers the remaining context an agent needs: when to invoke it, what inputs are accepted, what output shape to expect, and how it relates to sibling tools. Nothing critical is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra semantic value by giving concrete examples such as 'Portland, OR' via query, '50219', and 'bost' -> Boston with fuzzy=true, plus an example explaining that Springfields are ranked by importance. This goes beyond the schema's parameter descriptions.

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

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

The description opens with a specific verb and resource: 'Resolve a place query to candidate locations with coordinates.' It clearly states what the tool does and distinguishes it from siblings by noting that most weather tools geocode internally and this tool 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?

The description explicitly says 'use this tool only to disambiguate' or 'to present location choices to the user,' and contrasts with most weather tools that accept a location string directly. This gives an agent clear routing guidance and prevents unnecessary calls.

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