Solano — marine & outdoor weather

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds rich context beyond them: cost magnitude (1728 rays, 18 topography calls), a shared public quota, per-day caps, serialisation, de-duplication, and instant free cache hits. This is exactly the behavioral disclosure an agent needs before invoking an expensive shared-resource operation.

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-loads what the tool does, then the cost/limit warning, then the cache note. Every sentence carries operational information — quota, alternatives, refusal semantics — with no filler, despite the length.

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 still enumerates the return payload (per-direction protection, swell blocking, hourly comfort, depth, seabed nature), and for a 2-parameter tool it covers cost, caching, limits, and alternatives. An agent has everything needed to decide and invoke correctly.

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

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

Schema coverage is 0% and neither latitude nor longitude is described in the schema, but the description implies the coordinate pair targets one precise anchorage. Beyond confirming single-point semantics, it adds no format, range, or precision guidance. Given only two self-evident coordinate parameters, this is adequate but not additive.

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 ('directional shelter analysis of ONE precise anchorage') and enumerates concrete outputs: per-direction wind protection, swell blockage, hourly comfort over three days, depth, seabed nature. It explicitly contrasts its single-spot scope against the coastline-sweeping behavior an agent might otherwise assume, separating it from siblings.

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

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

Explicit when-to-use ('a SINGLE spot the user has in mind'), explicit when-not-to-use ('Do NOT call it repeatedly to sweep a coastline'), and it names the correct alternative tool (`find_known_anchorages`) plus a non-tool route (the app). It even pre-explains that a refusal is a budget limit rather than an error, which prevents misdiagnosis.

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, non-destructive behavior, but the description adds substantial context beyond them: cache-only scope, the 18:00–10:00 local scoring window, the worst-hour conservative reading, the swell 0.70 / wind 0.30 weighting, and the cost profile (no topography download, two forecast calls).

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 purpose and then layered with cache scope, scoring method, empty-result handling, and cost. Mostly earns its space, though the aside 'swell is what makes a boat roll' is flavor that could be trimmed.

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 does explain the return semantics (per-night scores, empty result meaning) and the absence of a topography download. The main gap is that parameter behavior, especially radius_m, is left entirely unexplained.

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 0% and none of the three parameters (latitude, longitude, radius_m) has any schema-level documentation. The description says 'nearby' but never explains what radius_m controls, its units, or the coordinate format, so it fails to compensate for the coverage gap.

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: finds anchorages that are already analysed and re-scores them for comfort over three nights. It clearly differentiates itself from the sibling `analyze_anchorage`, which is described as the tool for adding a new spot rather than reading cached ones.

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 addresses the when and when-not: it only returns spots in the shared cache, an empty result means nobody has analysed the area yet, and it names the alternatives (`analyze_anchorage` for a precise spot, the app to sweep the area). An agent can route correctly without inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantial extra behavior: the same-ensemble comparison methodology (GFS→GEFS, IFS→ECMWF-ENS, ICON→ICON-EPS), the 60/25/15 weighting blend, and the interpretation of high vs low values.

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 one-line meaning of the metric, followed by compact rationale and usage paragraphs. The methodological middle paragraph is longer than strictly necessary but each sentence carries real interpretive value.

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

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

With no output schema present, the description usefully documents the return shape — per-day mean and minimum confidence plus a per-variable breakdown at the least confident hour — and covers interpretation, so an agent has everything needed to call and read the result.

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 0% with 3 parameters, so the description must carry the load. It explains how the models parameter is interpreted (each deterministic model vs its own reference ensemble) but adds nothing about the latitude/longitude parameters or the accepted array format, so compensation is only partial.

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 resource — hour-by-hour forecast confidence derived from ensemble spread — and explicitly frames it as 'Solano's own indicator, not a raw model output,' which distinguishes it from sibling forecast tools like get_forecast and get_storm_risk.

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

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

Provides concrete trigger phrases ('is this forecast reliable?', 'will it hold?') and a workflow cue ('before committing to a passage plan'), giving the agent clear context for invocation. It stops short of naming an alternative tool or stating when not to use it, so it is not a full 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 cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description's job is added context — and it delivers: exact returned fields per model per local day, why there is no hourly data, the conditional `sea_state` block and its Hs/Hmax/period/direction contents, and the regional-replaces-global model selection rule.

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 paragraphs, front-loaded with the core purpose and the most decision-relevant constraint (not hourly) before the conditional sea-state and model-selection details. Slightly verbose in enumerating every returned field, but each paragraph earns its place.

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

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

With no output schema, the description compensates well by enumerating the return payload per model per local day. The main gap is the unexplained `days` parameter and no note on defaults/max range for it, which matters for a forecasting 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 0%, so the description must carry parameter meaning and it only partially does. It explains `models` (force specific keys, list first) and `include_sea_state` (triggers the sea_state block, sea points only), but `days` — which controls how many daily summaries come back — is never mentioned, leaving a required-to-understand knob undocumented.

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 (daily weather summary for a point) and immediately scopes it: multi-model, per-local-day, not hourly. An agent can distinguish it from get_marine_bulletin, get_tide, and get_storm_risk without opening any 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 routes the agent: for hourly data follow `solano_url`, and before forcing `models`, call `list_models_for_location` to see what exists at the location. That is concrete when-to-use guidance referencing a sibling tool. It lacks an explicit 'don't use this for...' exclusion, so not a full 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, open-world, non-destructive, so the safety profile is covered. The description adds genuinely new behavioral context: results are cached 1-3 hours, it costs no third-party call when warm, the text comes back in the issuing service's language, and it should be quoted rather than translated.

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-loads the core definition, then provider details, then the language contract and cost note; every sentence carries information. It is slightly longer than strictly necessary, but no sentence is 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?

With no output schema, the description carries the return contract and does so well: bulletin text, publishing language, quoting guidance, and caching cost. It omits the failure case (what is returned when no service covers the point), which is the main remaining gap for a 3-param open-world lookup.

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 0%, so the description must compensate, and it does so for the highest-risk param: it enumerates the exact accepted `provider` values (mf, aemet, meteoam, metoffice) and explains that omitting it triggers automatic matching. Latitude/longitude semantics are only implied by 'the zone containing a point', leaving their coordinate order/format undocumented in both places.

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?

Names a specific verb and resource ('official marine forecast bulletin for the maritime zone containing a point') and explicitly distinguishes itself from model output, which is exactly the boundary against sibling get_forecast. An agent knows what this returns and how it differs from the numerical forecast tool 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?

Gives clear context: providers are auto-matched to the point, and `provider` can be passed to force one. The 'not a model output' contrast implies when to prefer it over get_forecast, but it never names the alternative or states an explicit condition, so routing is left partly to inference.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive behavior, and the description goes well beyond them: ~25 km grid snapping, the GFS baseline and modulator set, the meaning of the capped_gun flag, and the 'marked, isolated' vs severe interpretation rule. That is exactly the interpretive context annotations cannot supply.

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 scoring mechanics, then the critical basin-scale warning. Every sentence carries information, though the CAPE/lifted-index/lapse-rate detail is denser than selection alone requires — defensible since there is no output schema to explain the score.

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 does the work of explaining what comes back (a 0-10 hourly score plus a capped_gun flag) and how to phrase it. The remaining hole is parameter documentation, which leaves an otherwise complete definition slightly short.

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 0%, so the description must carry the parameter burden. It implies a point (latitude/longitude) and an hourly score that hints at a time dimension, but never documents the days parameter, its default of 3, the coordinate format, or the returned time resolution. The gap is 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?

States a specific output (thunderstorm environment at a point, scored 0-10 per hour) and a specific basis (convective ingredients, not a rain field). This cleanly separates it from get_forecast and get_zone_alerts, which an agent could otherwise confuse with it.

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

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

Explicitly bounds the tool: it describes an environment at basin scale, does NOT locate individual cells, and routes the agent to list_models_for_location for convection-resolving coverage. It also gives phrasing rules for downstream output. It stops short of stating when to prefer this over get_forecast or get_zone_alerts for the same point.

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?

Far exceeds the annotations: it discloses the two datum regimes, the semantic meaning of height_m under each, a quantified systematic underestimation bias (-6% Halifax, -20% Bay of Fundy) that is flagged rather than silently corrected, and the fact that almanac attachment is resolved asynchronously so a fresh location may change its answer between calls. This is exactly the context annotations cannot carry.

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 cleanly bulleted into the two reference kinds and the caveats. It is longer than average but nearly every line carries distinct operational value; the three-paragraph caveat block could be tightened slightly.

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 does the heavy lifting on return semantics and does it well, explaining what height_m means in each mode and what must never be done with it. The gap is input-side: days and coordinate conventions are unexplained anywhere.

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 0%, so the description carries the full burden, yet it says nothing about latitude/longitude format (decimal degrees? sign convention?) and never mentions the `days` parameter or its default of 3. Only the vague phrase 'any point on the globe' hints at the coordinate 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 ('High and low water times and tidal range at any point on the globe') plus the two possible result modes (chart_datum vs lowest_low_water). An agent can tell instantly this is the tide-height tool and not a forecast, bulletin or anchorage tool, even 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?

The description is rich in how to interpret and how NOT to use the output (never add height_m to a sounding), but it never says when to call this versus siblings like get_forecast or analyze_anchorage, nor prerequisite conditions. Usage is implied by the tool's domain rather than stated as a routing 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 cover the safety profile (readOnly, idempotent, openWorld), and the description adds substantial behavior beyond them: the sources queried, region-level resolution, the shape of each warning (issuing service, validity window, level, official text in the publishing language), the meaning of an empty list, and the 15-minute cache with no third-party call when warm.

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-loads what the tool returns and which sources feed it, and the trailing sentences on empty-list semantics and caching earn their place. Slightly verbose with a stray fragment structure, but 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?

With no output schema, the description usefully enumerates the returned warning fields, explains the empty-list case, and discloses the cache behavior. It is nearly complete, missing only guidance on the coordinate inputs, which it cannot afford to omit at 0% schema 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 0% for the two required coordinates, so the description carries the full burden. 'For a point' only loosely implies latitude/longitude and gives no format, ordering, or coordinate-system detail to compensate for the undocumented 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?

States a specific verb and resource ('Marine and weather warnings in force for a point') and specifies the aggregation scope ('from every official source at once') with named sources. It also differentiates itself from sibling warning/forecast tools by resolving MeteoAlarm warnings to the actual region rather than the whole country.

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?

'Check this before any passage or coastal activity' gives clear situational guidance for when to reach for the tool. However, it never names or contrasts with siblings like get_marine_bulletin or get_storm_risk, so there are no explicit exclusions or 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 declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description adds value beyond that by disclosing the cost profile ('read from the registry, no network call') and by explaining what `near_domain_edge` and the regional/global parent masking actually mean, which is 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?

Every sentence carries information — masked parent models, convection semantics, edge-relaxation warning, and zero cost — and the cost fact is sensibly front-loaded as a closing note. It is slightly prose-heavy and the parenthetical model list is longer than strictly necessary, but nothing is 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?

With no output schema, the description does the work of naming the meaningful return fields (`resolves_convection`, `near_domain_edge`) and explaining how to interpret them, which is what an agent needs to use the result. The remaining gap is input formatting rather than output meaning.

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 0%, so the description must carry the burden. It conveys that the two coordinates define 'a point' and that position determines domain-edge exposure, but never states coordinate format, datum, or accepted ranges, leaving genuine ambiguity for the only two required 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?

The description clearly identifies the resource (weather models) and the scope (those covering a given point), and the rhetorical framing 'Which weather models actually cover a point' resolves to a list operation. It does not name a sibling because none of the listed siblings compete for this job, so explicit differentiation isn't needed.

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 one concrete usage cue — cite `resolves_convection` models 'when asked where a storm will actually break' — which implies the decision context. But there is no statement of when to call this versus alternatives such as `get_forecast` or `get_storm_risk`, so routing guidance is only partial.

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