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?

Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds behavioral context beyond annotations: it discloses that it scans the forecast, returns daylight-aware periods, requires all conditions to match, and specifies the units system. It doesn't describe edge cases like no matching window or the exact optimization objective, but given annotation coverage, the added detail is sufficient for a 4.

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

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

The description is concise and well-structured: a one-sentence purpose, a behavior statement, a units note, and an example. It is front-loaded with the core purpose, and every sentence contributes meaning. The example is compact yet informative, covering key parameter usage. No filler words or redundancy.

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

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

With 9 parameters and a nested object, the description covers the essential concepts (criteria, units, daylight-awareness, example) without needing to explain every field since the schema is fully documented. An output schema exists, so return-value details are not required. The description is complete enough for an agent to understand the tool's capabilities, though it could briefly clarify what 'optimal' means in terms of ranking windows.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds value by explicitly noting that criteria are expressed in the selected units system and by providing a concrete example covering multiple criteria and parameters. This helps agents understand how to structure the `criteria` object and how units apply, going beyond the schema's per-field descriptions.

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

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

The description clearly states the tool's purpose: 'Find the optimal time window for an activity based on weather criteria.' It names a specific verb ('find') and resource ('optimal time window'), and distinguishes itself from siblings by focusing on window selection rather than raw data retrieval. The additional phrase 'Scans the forecast and returns daylight-aware periods matching all conditions' further clarifies the unique functionality.

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

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

The description provides clear usage context: it is for finding time windows based on weather criteria, which implies when an agent would choose this over raw forecast tools. It doesn't explicitly mention alternatives or when-not-to-use, but the stated purpose is distinct enough that an agent can infer appropriate usage. No exclusions are given, but the clarity of the purpose earns a solid 4.

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

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

Annotations already 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 cover read-only, idempotent, non-destructive behavior, so the bar is lower. The description adds valuable context beyond annotations: sub-hourly updates, that RH is derived, that surface_pressure is station-level not sea-level, and unit conversion behavior. It doesn't mention rate limits or auth, but for a read-only weather tool that's minor.

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

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

The description is front-loaded and starts strong, but it becomes a dense wall of field names and unit details that could be streamlined since the schema already covers parameters. It's informative but verges on over-specification, and the example is helpful but placed at the end.

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

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

Given the tool's complexity (dual data sources, many fields, unit handling) and the presence of an output schema, the description provides enough context to invoke it correctly. It covers sources, fields, units, and alternatives. It doesn't explain the output schema's structure, but that's acceptable since the output schema exists.

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 lat, lon, units, and location thoroughly. The description adds a small clarification about default units (si) and the distinction from get_forecast's imperial default, but mostly repeats schema content. 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 opens with a specific verb+resource ('Current weather right now at a location') and then distinguishes itself from siblings by naming the two data sources (RTMA analysis, nearest METAR station) and explicitly routing forecasts to get_forecast. This level of specificity lets an agent select it correctly without opening the schema.

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

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

It gives clear guidance on when to use analysis vs station ('Use the analysis for point-accurate values and the station for verification') and explicitly names get_forecast as the alternative for forecasts. It doesn't mention siblings like get_observations or get_hourly_forecast, which could be ambiguous, 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 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 readOnly/openWorld/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: the NBM source, that p50/p90/p10 should be reported together rather than singly, and a genuine limitation (NBM has no tornado, hail or damaging-wind probabilities). It stops short of noting any latency, rate-limit, or update-cadence behavior, so not a 5.

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

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

Front-loaded with purpose, then interpretation rules, then the aspect catalog, then examples – a sensible order with no filler sentences. The aspect enumeration is dense and pushes the block long, but each clause carries information an agent needs to select the right aspect.

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

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

An output schema exists so return-format explanation is unnecessary, and the description still covers everything else: when to reach for it, how to read the percentiles, what each aspect yields, and where the data falls short. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, but the description goes well past the field names: every value of the required `aspect` enum is explained in terms of what it actually returns (PoP/QPF, snow-level and >1/2/4in probabilities, CWASP semantics, LIFR/IFR/MVFR, stddev). It also supplies worked call examples that clarify the location-vs-lat/lon choice.

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

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

States a specific verb+resource (probabilistic NBM forecast distribution) and immediately scopes it to percentile ranges, exceedance probabilities and ensemble spread. It explicitly distinguishes itself from the deterministic sibling by saying a deterministic forecast value cannot answer these questions, and it carves out the severe-hazard case to get_outlooks.

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

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

Gives explicit triggering conditions ('any question about odds, ranges, potential or confidence') with quoted user phrasings, and names the alternative for one sub-case ('use get_outlooks hazard=severe for SPC's'). When-to-use, when-not, and alternatives are all present.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial operational context beyond them: data source (MRMS QPE Pass2), coverage limits (CONUS; 1 h only in AK/HI), ~2 mm resolution with the meaning of zero, ~1 h data latency, and the 33 h `at` limit.

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

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

Front-loaded with the plain-language purpose before any caveats, and each sentence carries distinct information (source, windows, resolution, latency, `at` behavior, nowcast, alternatives). It is dense and slightly long, but no sentence is redundant.

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

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

An output schema exists, so return values need not be described, and the remaining gaps an agent would care about - spatial/temporal coverage, data latency, measurement resolution, and where to go for adjacent needs - are all addressed.

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 earns extra by explaining semantics the schema cannot: that `at` selects totals ending at a past time with the newest frame up to 3 h before it, and that include_nowcast returns intensity/type/start time rather than an amount.

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?

Opening clause states a concrete verb+resource ('observed precipitation totals at a location') and immediately frames it with example questions. It distinguishes itself from named siblings get_period_totals (forecast) and get_observations (station reports) within the same description.

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

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

Explicit when-to-use hedges ('did it rain', 'how much rain fell', 'rain in the last 24 hours') plus explicit routing to alternatives for the adjacent cases. An agent can pick this tool over the 30+ siblings without reading any schema.

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 disclose readOnlyHint, openWorldHint, idempotentHint, and destructiveHint, so the description doesn't need to repeat those. It adds valuable behavioral context: the tool expects pre-clipped geometry and fails or misbehaves if given a CONUS HeatRisk dissolve, plus it notes that classes filter a civic allowlist. This goes beyond the structured annotations with practical constraints.

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: one purpose sentence, one warning/alternative sentence, one classes sentence, and an example. Every sentence adds distinct value—purpose, exclusion, parameter behavior, and a concrete illustration—without repeating schema content or padding. The example is long but earns its place as a callable template.

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 an output schema, so return values need no explanation. Annotations cover safety traits, the schema documents both parameters, and the description adds the prerequisite, an alternative, and an example. Given the modest complexity (two params, one nested object), nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds extra meaning by warning against a specific problematic input ('do not pass a CONUS HeatRisk dissolve') and by providing a full JSON example that demonstrates the geometry and classes structure. The example hands an agent a concrete usage template beyond the schema's field 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 'Civic POIs (schools, hospitals, airports, …) inside a caller-supplied GeoJSON Polygon or MultiPolygon', which names the resource (civic POIs), the operation (find inside a polygon), and the input type. It also distinguishes itself from get_alerts by stating that get_alerts is for NWS alerts and already includes POIs, giving agents a clear basis to choose this tool over a sibling.

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

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

The description provides explicit when-to-use and when-not-to-use guidance: 'For an NWS alert use get_alerts({alert_id}) (already includes pois)' is a direct alternative, and 'Clip first — do not pass a CONUS HeatRisk dissolve' gives a concrete prerequisite with a negative example. This tells an agent exactly when to pick this tool versus another and how to prepare input.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured behavior: periods must use the user's local timezone boundaries rather than UTC midnight, and the response includes a converted value and unit per period. It stops short of covering failure modes or rate limits, so it earns a 4 rather than 5.

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

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

Front-loaded with purpose, then routing guidance, then the timezone caveat, then the example. Every sentence carries information, though the inline JSON example makes the block longer than strictly needed since the schema already defines the shape.

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

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

With an output schema present, return values need no further explanation, and the description still notes the per-period value/unit response. Combined with the timezone convention, the sibling routing, and the input example, an agent has everything needed to call this correctly for an 8-parameter tool.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: the local-timezone boundary rule for period start/end (the schema only says 'ISO 8601'), a worked example payload, and the note that a place name is accepted directly. These reduce the chance of malformed period timestamps, which the schema alone would not prevent.

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 ('Aggregate a weather variable over one or more time periods') and immediately clarifies the computed outputs (totals, maxima, minima, averages) plus the per-period response shape. It explicitly names a sibling it must not be confused with ('For rain that already fell, use get_observed_precipitation'), so an agent can select it without opening 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?

Gives concrete usage contexts ('total rainfall today and tomorrow', 'peak wind speed this weekend') and an explicit exclusion routing to get_observed_precipitation for past rainfall. The distinction between this tool (aggregation over periods) and the observational alternative is stated rather than inferred.

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?

Annotations already convey read-only, idempotent, non-destructive behavior. The description adds valuable context beyond those annotations: include_geometry=true triggers large payloads, empty results mean no active activity, and features carry kind/name/intensity/timing properties. This enriches the agent's mental model of what the tool will do and return.

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 packs the resource, content taxonomy, behavior caveats, empty-result semantics, sibling pointer, and an example into four dense sentences with no fluff. Every sentence earns its place and the most important information is front-loaded.

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

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

For a tool with one optional parameter and an existing output schema, the description covers all essential decision points: what is returned, how to enlarge geometries, what an empty result means, and where to find a specific related type of data. Nothing needed for correct invocation 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% for the single boolean parameter, so the baseline is 3. The description adds a performance caveat (large geometries) and a concrete example invocation, which slightly exceeds what the schema alone provides. The schema already explains the parameter, so the extra value is modest but real.

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

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

The description uses a specific verb ('Get') and resource ('Active NHC tropical systems') and clearly enumerates the returned content: forecast cones, track lines, forecast points, watches/warnings, and outlook areas. It also names the sibling tool for reconnaissance data, distinguishing itself without needing to inspect other 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 explicitly defines its scope (Atlantic + East Pacific, active systems) and gives an exclusion: 'Aircraft reconnaissance fixes and flight-level observations are in get_tropical_observations.' This tells the agent when to choose this tool and when to prefer a sibling. The empty-result interpretation further clarifies the expected output in 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 mark the tool as read-only, idempotent, and non-destructivecars. The description adds genuinely useful behavioral context beyond the schema: kind=hdob returns only the newest 200 records, 'truncated' indicates missing data, and the response is empty when no aircraft flew in the window. No contradiction 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 every sentence earns its place: it explains what the tool returns, redirects to two siblings, and discloses a key result-limiting behavior before the schema details. No filler or 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?

For a read-only tool with three optional, fully documented parameters and an output schema, the description covers the important operational details: data source, sibling tool boundaries, HDOB limits/truncation, and empty-response behavior. Nothing critical for correct invocation 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 all three parameters. The description adds valuable runtime semantics for kind=hdob (200-record limit, roughly 1–2 hours of data, truncated indicator), which goes beyond the bare enum definition. It does not add much for hours or storm, but the schema handles those adequately.

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

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

The description states a specific resource ('Hurricane Hunter aircraft reconnaissance'), names the data products (VDM and HDOB), and explicitly distinguishes itself from get_observations and get_tropical. An agent can immediately tell what this tool returns and what it is not.

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 routing guidance: use get_observations for METAR/surface stations)Skip and get_tropical for NHC cones/tracks/watches. It also clarifies that this tool returns aircraft measurements. This is clear when-to-use and when-not-to-use guidance.

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

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

Annotations already 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.