Smarter Weather

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), so the description's job is context — and it delivers by disclosing the full inventory of metadata fields returned, plus an example payload, which lets an agent judge whether the call is worth making. It doesn't discuss failure behavior for unknown dataset_ids or response size, keeping it short of 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 the highest-value information (what variables/fields you get), followed by a compact concrete example. The content list is dense but every item is informative; the only flaw is the missing verb that would make the opening sentence grammatical.

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 structure needn't be explained, and the description nonetheless summarizes the payload's contents; annotations cover the safety profile and the single parameter is fully documented in schema. Nothing an agent needs in order to call this 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?

With 100% schema description coverage and a single required dataset_id that already carries examples ('nbm_conus', 'mrms_reflectivity_conus') and a pointer to list_datasets, the schema does the work. The description repeats the example value but adds no new semantics such as identifier stability or lookup behavior, so baseline 3 applies.

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 enumerates precisely what metadata is returned (variables with standard names/units/display units/categories/bands, horizon, step, cadence, freshness, cost class, plus an example_query), which is specific and distinguishable from the sibling query_dataset. It loses a point because it is written as a noun-phrase fragment with no leading verb ('Returns…'/'Describes…'), leaving the exact action slightly implicit.

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?

Usage is only implied: by naming 'example_query for query_dataset' it hints at the describe-then-query workflow, and the example call shows the shape of a correct invocation. There is no explicit statement of when to call this instead of list_datasets or query_dataset, and no exclusions or prerequisites are given in the description itself.

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 read-only, idempotent annotations, it discloses important behavioral semantics: point queries use containment, bbox/state queries use intersection, empty results may mean all-clear or purged data (~24h), and `alert_id` mode returns detail plus geometry while ignoring `at`. This is substantive context an agent needs to interpret results correctly.

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 front-loaded, with every clause carrying useful information. However, the fragmentary, telegraphic style makes some mode distinctions harder to parse than necessary, and a short structured list would improve scanability.

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 7-parameter tool with multiple query modes, nested bbox, and no required parameters, the description covers the critical routing logic, spatial semantics, time behavior, alert-detail behavior, and empty-result interpretation. Since an output schema exists, it need not explain return fields.

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 non-obvious parameter meaning: spatial containment vs intersection by mode, state-code/full-name handling for NY/WA versus city names, `at` as a snapshot time that should be omitted for current results, and `alert_id` ignoring `at`. It also gives a concrete `events` filter example.

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 makes clear that this returns NWS watches, warnings, and advisories, and it distinguishes point, bbox/state, and alert-detail query modes. It is specific about the resource but relies on a noun phrase rather than an explicit verb, and the telegraphic style slightly obscures the core action.

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 explains when to use point queries (containing polygons) versus bbox or state queries (intersecting polygons), warns that a city miss is not a statewide all-clear, and tells the agent to query the state or bbox instead. It also gives clear guidance on omitting `at` and on `alert_id` detail mode.

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 read-only, idempotent, open-world, and non-destructive; the description adds meaningful provenance and semantics beyond that — sub-hourly update cadence, that relative_humidity_2m is derived rather than observed, that surface_pressure is station pressure not sea-level, and that nearest_station is unconverted by units. It does not disclose behavior when a source is unavailable (e.g., no nearby METAR station, RTMA coverage limits), which is the remaining gap for a dual-source tool.

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 opening sentence and the get_forecast redirect are well front-loaded, but the long enumeration of analysis fields (temperature_2m, dew_point_2m, wind_speed_10m, etc.) duplicates the output schema and does not earn its space. The description is roughly twice the length needed given that a return schema exists.

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 field list is redundant rather than necessary, and the core need — what the tool returns conceptually (two sources, one derived field, unit handling) and when to prefer it — is covered. The gap is failure/coverage behavior: nothing tells the agent what happens when no METAR station is nearby or when RTMA is out of coverage.

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 including formats, ranges, and the default. The description's parameter-relevant additions are marginal — the example shows the location form and it notes units labels live in analysis.unit_labels, but most of its detail is about output fields rather than inputs.

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 ('Current weather right now at a location') plus the scope differentiator that defines it: two independent sources (RTMA gridded analysis and nearest METAR station) in one call. The sibling get_forecast is explicitly carved out, so an agent can distinguish it from adjacent tools without opening a 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?

Gives explicit routing: 'Use the analysis for point-accurate values and the station for verification' and 'For a forecast, use get_forecast.' It also provides a concrete invocation example, leaving nothing to inference about when this tool is the right choice.

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, so the description's job is to add operational context — and it does: server-side aggregation across NBM/HRRR/GFS/RTMA/SPC, server-side unit conversion, response size bands (~5-10KB vs ~12-20KB), and the timezone_resolved=false fallback requiring UTC-only phrasing. These are non-obvious behaviors an agent cannot infer from the 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?

Front-loaded with purpose and the sibling routing rule, then constraints, then examples — a sensible order with no filler sentences. It is dense and on the long side, but nearly every clause carries usable 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 an output schema present the description needn't document return fields, yet it still flags the one output-derived hazard (timezone_resolved) and the per-day astro.local convention. Combined with the 8-param schema and rich annotations, an agent has everything needed to call this 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 genuine meaning: it clarifies that a place name is accepted directly, shows three concrete invocation shapes, and notes the UTC/local quoting rule tied to the returned astro field. It stops short of deep per-parameter guidance beyond what the schema already documents.

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 ("Complete weather overview for a location") and enumerates exactly what comes back: current conditions, daily forecast with SPC threats, alerts, outlooks. It also positions itself against siblings explicitly as the "Primary weather tool" versus lower-level tools for raw 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?

Gives a clear when-to-use rule (primary tool; reach for lower-level tools only for raw observations or a specific dataset) and names the concrete alternative for hourly detail (get_hourly_forecast, repeated in the include param). The view="detailed" tradeoff is spelled out so the agent can pick a mode.

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 read-only, idempotent, non-destructive, open-world behavior. The description adds substantial interpretation guidance beyond that, explaining how to read p10/p50/p90, that a single percentile is not the forecast, and what confidence spread means.

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 purpose and usage guidance are front-loaded, and most sentences earn their place by explaining interpretation or aspect coverage. It is dense and the aspect enumeration is somewhat run-on, but it is not padded with generic 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?

An output schema exists, so the description is not obligated to explain return structure. It still completes the agent's context by explaining how to interpret probabilistic outputs, which aspects exist, and how to report percentile guidance 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 schema already documents parameter names, ranges, and enums. The description adds useful meaning beyond that, especially by unpacking each aspect value (precip, snow, ice, temperature, wind, severe, aviation, confidence) and noting that output labels appear in unit_labels.

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

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

The description opens with a specific resource and output type: 'NBM probabilistic guidance for one weather aspect: percentiles (p10-p90), exceedance probabilities and ensemble spread.' It explicitly distinguishes itself from deterministic forecast siblings by saying a deterministic forecast value cannot answer odds/range/confidence questions.

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

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

It gives explicit when-to-use criteria: 'Use this for any question about odds, ranges, potential or confidence' and rules out deterministic forecasts. It also names the alternative for severe-weather hazard odds with 'SPC's: get_outlooks (guidance) hazard=severe.'

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?

Goes well past the readOnly/idempotent annotations: it discloses that rows beyond the first day are sampled every 2-3h, that hourly_coverage exposes first_time/last_time/sample_interval_hours/truncated, that timestamps are UTC, and that out-of-window hours should be refused rather than substituted. This is the kind of behavior an agent could not learn from the schema alone.

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

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

Front-loaded with the payload summary, then escalating operational rules, ending with examples. Fairly long at roughly 180 words, and the coverage/truncation guidance repeats the same idea across two sentences, but nearly every clause is actionable rather than filler.

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

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

For a 9-parameter, fully-annotated, output-schema-backed read tool, nothing an agent needs is missing: coverage semantics, sampling caveats, timezone handling, and call-shaping advice are all present, and return-value shape is left to the output schema.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning on top by explaining that hours_from/hours_to returns a dense hour-by-hour window even where the full range would be sampled, and by showing worked examples for both location and lat/lon invocation styles.

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?

Opens with a specific verb+resource+field list: "Blended hourly forecast: temperature, feels-like, humidity, wind, precipitation..." and clarifies row zero semantics ("hourly[0] is the current or next hour"). The hourly granularity and 'blended' framing distinguish it from sibling daily/current 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?

Gives concrete when-to-use rules: batch days up front ("one call with days: 4 beats four calls"), and use hours_from/hours_to for a contiguous stretch. It does not explicitly name sibling tools such as get_forecast or get_current_conditions, so the agent must infer the boundary itself.

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/idempotent/non-destructive, yet the description still adds substantial behavior: data source (MRMS QPE Pass2, gauge bias-corrected), ~2 mm quantization meaning "0 means under about 1 mm", ~1 hour latency, the 33 h `at` bound and the 3 h staleness of the frame used for past times, and that include_nowcast is ignored when `at` is set.

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, then escalating detail (source, resolution, latency, parameter caveats, alternatives). Every sentence carries actionable information; nothing is boilerplate padding.

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-value enumeration is unnecessary, and the description instead covers what the output schema can't (what a 0 value means, that nowcast is not an amount, spatial/temporal validity limits). For a 7-parameter, multi-region tool this leaves no meaningful gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the temporal semantics of `at` (totals ending at a past time, newest frame up to 3 h before it) and clarifying that the nowcast is an intensity/type/start-time signal rather than an accumulation. Some of this restates schema text (e.g., "ignored with `at`"), keeping it short of a 5.

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

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

States a specific quantity (observed precipitation totals at a location) with plain-language verb framing ("How much rain fell") and concrete query intents ("did it rain", "rain in the last 24 hours"). It explicitly distinguishes itself from get_period_totals (forecast past next hour) and get_observations (station reports), so an agent can route 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 explicit when-to-use phrasing plus named alternatives with the condition that selects them ("Forecast totals past the next hour: get_period_totals (planning); station reports: get_observations"). It also states coverage boundaries (CONUS; 1 h only in Alaska and Hawaii), which acts as a de facto when-not rule.

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, idempotent, non-destructive, so the safety profile is covered. The description adds genuinely useful context the annotations cannot carry: the ~5-minute refresh cadence and the meaning of the four source states. However, it doesn't state whether incidents/advisories are always present, how far back incidents are reported, or the response's size/shape despite the include_ok toggle doing exactly that.

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 payload is front-loaded (what it returns, then when to call it, then how to interpret it, then cadence), and each sentence adds a distinct fact. No filler or restatement of the tool name.

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 and annotations cover the safety profile, so the description doesn't need to explain return values. What remains — the freshness semantics, the state vocabulary, the degradation message, and the refresh interval — is all present, which is exactly enough for an agent to call and interpret this 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% and the single include_ok parameter is fully documented in the schema, so the baseline applies. The description's 'No inputs' is slightly at odds with the existence of an optional parameter and could cause an agent to overlook the include_ok toggle when it wants a full source list, which is a minor loss of value rather than a gain.

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 specific resource and enumerates the four things it returns: overall state, per-source states, incidents with cause attribution, and provider advisories. That distinguishes it clearly from the data-fetching siblings (get_forecast, get_current_conditions), which return weather rather than platform health.

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 three explicit triggers (user asks whether data is current, other tools return surprisingly stale data, before presenting time-critical weather) and adds a behavioral instruction for the degraded case: tell the user data may be stale rather than presenting it as live. That is when-to-use plus how-to-act, not just context.

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

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

Annotations already declare readOnly, idempotent, non-destructive, open-world behavior, so the safety profile is covered. The description adds genuinely non-obvious behavior: the fallback rule when current_time.timezone_resolved is false (report as UTC, never local) and the provenance of solar data via the weather pipeline's astro product.

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 sentences are front-loaded with the returned content and then the usage triggers, so the key information lands early. It is dense but nearly every clause carries useful detail, with only slight redundancy in the example after the schema already explains the location parameter.

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-value structure need not be explained. Given that, the description is complete for a 3-param, zero-required, open-world lookup tool: it covers contents, invocation triggers, the timezone-unknown edge case, and accepted input forms.

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 lat, lon, and location are already fully documented, including the 'use this OR lat+lon' rule. The description only restates that a place name is accepted and adds a small example payload, which is marginal value over the schema.

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

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

The description names a specific resource and enumerates its contents: local time, timezone, 14-day calendar with Today/Tomorrow offsets, sunrise/sunset/solar times, and moon phase. This clearly separates it from siblings like get_current_conditions or get_forecast, which cover weather rather than temporal context.

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 triggering conditions ('Use whenever you need to reason about dates, times, or daylight') plus three concrete example questions that map to the tool. It lacks an explicit exclusion or named alternative for overlapping cases, but the usage context is strong.

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 that this is read-only, idempotent, non-destructive, and open-world. The description adds meaningful behavioral context beyond those hints: behavior with versus without a location, inclusion of domain-specific and global grids, and freshness fields such as latest_run and data_age_seconds. It does not discuss auth or rate limits, but its behavioral disclosure is still strong.

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

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

The description is front-loaded with the core purpose and scope, then adds freshness behavior, routing guidance, and a compact example. The density is appropriate for the amount of routing and freshness information an agent needs, with no filler sentences.

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

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

Although this is a relatively complex discovery tool with freshness tracking, an output schema is present and annotations cover the safety profile. The description supplies the remaining decision-critical context: how location affects results, what freshness information appears, and which sibling tools consume the output.

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 the four parameters. The description nevertheless adds semantic meaning about what the absence of a location means (every public dataset) and how a point query scopes results to a domain plus global grids, which goes beyond the parameter descriptions alone.

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

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

The description uses a specific verb ('Discover') with a precise resource ('gridded datasets'), and it defines the tool's scope as location-scoped or all-public when no location is supplied. It also names the sibling tools it feeds into (query_dataset) and where variable metadata lives (describe_dataset), so an agent can distinguish it from siblings without opening 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 states when to use this tool: to find dataset_id values for query_dataset or to check whether data is current. It also routes variable/unit discovery to describe_dataset, giving a clear alternative and avoiding misuse.

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 the safety profile (readOnly, idempotent, openWorld, non-destructive), and the description adds real operational behavior beyond them: a 168-frame truncation limit with cursor reuse under the same arguments, run pinning via reference_time, and a retention caveat that runs older than ~48 h may be gone. It also discloses that each series carries reference_time (or reference_times when runs mix), which an agent must know to interpret mixed 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?

Front-loaded with the core capability, then time modes, then pagination and retention, then two worked examples. Dense but every line carries operational information; the two full JSON examples are the only slightly expensive element, and they earn their space by showing location-vs-lat/lon usage.

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 12-parameter read tool with an output schema (so return shape need not be explained) and full annotation coverage, the description supplies exactly what is missing: time-mode selection, pagination recovery, run pinning and retention. Nothing needed to invoke it correctly is absent, aside from the minor hours-default ambiguity.

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 92%, so the baseline is 3; the description still adds cross-parameter meaning the schema lacks, notably that cursor must be re-sent with the identical arguments and how reference_time shifts the meaning of hours to run-relative. Minor friction: it states 'hours (default 24)' and 'up to 168 frames' while the schema says hours defaults to 'newest 166 frames' with a max of 264, and the units parameter is never mentioned in the description.

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

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

Opens with a specific noun phrase: raw time-series of one dataset's variables at a point, with unit labels, and enumerates the product families covered (NBM, HRRR, RTMA, MRMS, etc.). It explicitly contrasts itself with get_forecast for blended forecasts, so an agent can separate it from that sibling without reading 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 selection conditions: three time modes (hours, time_start+time_end, latest) and the rule to use get_forecast for blended output. It does not distinguish itself from other near siblings such as get_hourly_forecast or get_current_conditions, so the routing guidance is strong but incomplete.

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, idempotent, open-world, non-destructive, so the safety profile is covered. The description adds useful behavioural detail beyond that: the concrete output example shows what a lookup actually yields, including the timezone string format, which tells the agent what to expect to consume. Auth, rate limits, and ambiguity handling are not mentioned.

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 tight sentences: what it does, when to use it, then a worked example. Purpose and trigger are front-loaded and nothing is wasted.

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 structure need not be documented, yet the description still previews the returned fields and gives an example mapping. For a two-parameter readonly lookup, nothing an agent needs in order 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 description coverage is 100%, so both lat and lon are already documented with ranges and sign conventions. The description only restates the pairing via the example call, adding little meaning beyond the schema; a 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?

States a specific verb and resource — resolve coordinates to a human-readable place — and enumerates the returned fields (city, state, county, timezone). It does not name the sibling search_locations, which is the obvious forward-geocoding counterpart, so the differentiation is implicit rather than explicit.

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?

"Use when you have lat/lon but need a display name or the local timezone" gives a clear selecting condition and cleanly implies this is for coordinate input rather than name input. There is no explicit when-not statement or named alternative tool, which keeps it 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?

Goes well beyond the annotations (readOnly/idempotent/non-destructive) by disclosing the ranking basis (question's words), the result payload (variable, units, cadence, why, exact follow-up `call`), a genuine behavioral quirk (Alaska/Hawaii twins fold into CONUS when no location filter is passed), and cost ("Free; no network call"). The AK/HI folding rule is non-obvious and would otherwise surprise an agent.

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 purpose and the routing condition, and each sentence carries real information. The closing sentence about past times is the weakest — it mixes guidance about the follow-up call into a description of this tool and creates mild ambiguity rather than removing it.

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, yet the description still usefully previews the shape of a hit and its ready-to-run `call`, covering the full search-then-execute loop. For a 7-parameter, free, offline ranking tool, nothing an agent needs in order 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%, so baseline is 3; the description earns above that by explaining the lat/lon-vs-domain interplay ("Pass lat/lon, or `domain`... not with lat/lon") and the consequence of omitting both. Slight deduction: the mention of `time_start`/`time_end`/`at` is ambiguous — those are arguments to the returned call, not parameters of this tool, and could be misread as search_catalog inputs.

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 ("ranks the data catalog") plus the exact problem it solves ("find which dataset answers a weather question when no dedicated tool fits"), and enumerates what the catalog contains (model grids, radar, satellite, outlooks, observations). This clearly separates it from siblings like list_datasets, describe_dataset, and query_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?

Gives an explicit when-to-use condition ("when no dedicated tool fits") and describes the workflow: search, then run the returned `call`. However, it never names the concrete alternatives (describe_dataset, query_dataset, search_locations) an agent should prefer instead, so the routing decision still requires inference from sibling names.

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, non-destructive behavior; the description adds meaningful fallback semantics: `matched_via: "autosuggest"` marks rows found after an exact miss, and `partial` means a section timed out. It also explains fuzzy/autosuggest mode without contradicting 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 core purpose is front-loaded, and the sentences carry useful query formats, output flags, and weather-tool guidance without obvious filler. It is dense and semicolon-heavy, but still efficient for the amount of context it conveys.

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 annotations and an output schema, the description supplies enough context for correct invocation: purpose, accepted inputs, fallback flags, and how to use results with weather tools. The only remaining gap is minor `near_lon` detail, which is partly covered by the schema's `near_lat` pairing.

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 80% and the schema already documents `fuzzy`, `limit`, `query`, and `near_lat`, while `near_lon` lacks a description. The description reinforces query formats and fuzzy usage but does not add much beyond the schema or clarify the missing `near_lon` semantics, so the high-coverage baseline of 3 is appropriate.

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

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

States a specific verb and resource: 'Resolve a place to ranked candidates with lat/lon,' lists accepted query forms, and names the row types returned. It clearly establishes forward place search and its relation to weather tools, so an agent can distinguish it from reverse_geocode 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?

Explicitly says weather tools take `location` directly and that this tool should be used to disambiguate or present choices, which gives a clear when-to-use vs. alternative condition. It also explains `fuzzy=true` for partial input, making the usage context concrete.

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