UK Data: Weather forecasts worldwide

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

Annotations already cover readOnly, idempotent, openWorld and non-destructive, so the bar is lower; the description still adds real context: the upstream source (MET Norway Locationforecast 2.0), that values are model forecast percentages of sky covered, that fog is only available for the first few days, and that a call costs 1 credit. It does not mention rate limits or forecast-update cadence, which keeps it below 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 what the tool returns, then use cases, then source and constraints; every sentence carries information. The parenthetical cost note and the mixed prose list make it slightly dense, but nothing is truly 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?

With no output schema, the description carries the return-value burden and does so: it names the cloud layers returned, the fog extra, the clearest-hour pick, and the units (percent of sky covered). Combined with the prerequisite routing and the fog time limitation, an agent has everything needed to call and interpret 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 description coverage is 100%, so all three parameters (lat, lon, hours) are already documented with types and ranges. The description restates the lat/lon requirement and the 1-48 hour window but adds no new syntax, format, or edge-case guidance beyond the schema, which is the baseline-3 case.

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: hourly cloud cover forecast for the next 1-48 hours at a point, broken into total/low/medium/high cloud plus fog, with the clearest hour identified. That level of specificity makes it distinguishable from generic siblings like weather, rain_forecast_next_hours, or aurora_chance_at_location 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?

Gives concrete use cases (stargazing, astrophotography, aurora, sunset photography, solar panel output) and an explicit prerequisite chain: get coordinates from geocode or postcode_lookup for UK place names or postcodes. It does not explicitly say when to prefer this over the sibling `weather` tool or how it complements aurora_chance_at_location, so it stops short of full alternative routing.

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, openWorld, and non-destructive, so the safety profile is covered. The description adds genuinely new behavior: the MET Norway Oceanforecast 2.0 source, nearest-model-sea-point resolution, empty results for land or out-of-area points, and a 1-credit cost. It does not describe pagination or row shape, but with no output schema that is a minor gap.

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 definition is front-loaded with the resource and variables, then layers scope, use cases, source, caveats, and prerequisites. It is dense but nearly every clause carries information; the parenthetical cost note is slightly tacked on but still 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?

With no output schema, the description carries the burden of describing returns, and it does so by listing the hourly variables and the source model. Combined with the geographic bounds and the empty-result caveat, an agent has enough to call it correctly; only the exact response shape and timezone of the hourly series are unstated.

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 hours are already documented with types and ranges. The description adds only the constraint that the coordinates must be a sea point and that coordinates may need to be obtained elsewhere first. That is useful but marginal beyond the schema, so the 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 names a specific resource (sea-state forecast) and enumerates the exact variables returned: significant wave height and direction, surface current speed and direction, and sea temperature. It also bounds the geography (Norwegian Sea, North Sea, Skagerrak, Barents Sea, NE Atlantic, UK coastal waters), so an agent can distinguish it from generic weather or wind_forecast 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?

It gives concrete use cases (sailing, kayaking, fishing trips, coastal swims), an explicit exclusion (not a navigational or safety product), and a failure condition (land points or out-of-area return no rows). It also routes the agent to geocode or postcode_lookup for coordinates. It stops short of naming sibling alternatives such as weather, wind_forecast, or sea_temperature, 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?

Goes well past the annotations (which only declare read-only/idempotent/open-world) by disclosing data provenance (MET Norway Sunrise 3.0 for rise/set and phase angle; Meeus formulas for full/new moon times), an accuracy caveat (a few minutes, illumination approximate), and the 1-credit cost. Those are exactly the traits an agent needs to decide whether the answer is trustworthy for the question asked.

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 resource and its outputs, then usage, then provenance and cost. Dense and mostly waste-free, though the long output enumeration in the first sentence is heavy and could be trimmed since the schema and call site carry part of that load.

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 correctly compensates by listing the returned fields, and it covers the coordinate prerequisite and accuracy limits. It does not specify the format of bearings or rise/set times (aside from utc_offset handling), leaving a small gap for an agent reasoning about the response.

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, date and utc_offset are already fully documented with ranges and defaults. The description reinforces that lat/lon are mandatory and routes the agent to geocode/postcode_lookup for UK place names, but adds no new meaning about utc_offset or the date semantics beyond the schema. 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?

States a specific verb+resource (moon phase for a place and date) and then enumerates exactly what comes back: phase name, waxing state, illuminated fraction, distance from full moon, next full/new moon dates, moonrise/moonset with bearings, and culmination. No sibling tool covers lunar data, and the enumeration makes the tool unmistakable.

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

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

Gives concrete question-shaped use cases ("is it a full moon tonight", "when is the next full moon") plus the audience (stargazers, anglers, photographers), and crucially states the prerequisite chain: get coordinates from geocode or postcode_lookup before calling. It stops short of naming an explicit when-not or contrasting with sunrise_sunset, so it falls just 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 cover read-only, idempotent, open-world and non-destructive behavior, yet the description still adds real value: data source (MET Norway Locationforecast 2.0 hourly precipitation), that it is a model forecast rather than radar nowcast, UTC timestamps, and a 1-credit cost. These are behaviors an agent could not infer from the annotations, though it says nothing about handling missing data or out-of-range hours.

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 answer to "what does it return" is front-loaded, followed by use case, data source, prerequisites and cost in a logical order with no wasted clauses. The "walk, run, school run" list is slightly padded but earns its place as usage framing.

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 three-parameter, no-output-schema tool, the description covers everything needed: what is returned (wet/dry, first wet hour, total, hourly amounts), the horizon limit, units/timezone, data provenance and the coordinate prerequisite. Nothing essential 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 defines lat, lon and hours. The description still adds meaning by framing the time horizon as 1-12 hours and by directing the agent to geocode/postcode_lookup to fabricate valid coordinates for UK place names, which is genuine guidance not 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 question ("will it rain?"), a specific resource (hourly precipitation forecast), and a bounded scope (next 1-12 hours, hourly amounts plus first wet hour). It also distinguishes itself from adjacent concepts by calling out model forecast vs. radar nowcast, separating it from nowcast/historical siblings like rainfall_last_24h.

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 concrete usage contexts (walk, run, school run, outdoor job) and an explicit prerequisite chain: for a UK place name or postcode, resolve coordinates via geocode or postcode_lookup first. It lacks an explicit "do not use this for X" statement pointing at the generic weather or cloud_cover_forecast siblings, so it falls short of the top band.

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 and open-world behavior, and the description adds substantial context on top: the upstream source (MET Norway Oceanforecast 2.0), that values are model output at the nearest model sea point rather than a buoy measurement, and that land or out-of-area points return empty results. It even discloses a cost of 1 credit, which is not captured anywhere in the structured fields.

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?

Information is front-loaded: purpose and coverage first, then data source and caveats, then coordinate prerequisites and cost. It is a single dense paragraph with parenthetical asides, which is efficient but slightly cluttered; the cost note and source note could be trimmed or split without losing meaning.

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?

There is no output schema, and the description compensates by describing what comes back (current value, 24-hour range, hourly series). For a two-parameter read-only lookup, the source, coverage limits, prerequisite tooling and cost disclosure leave nothing material an agent needs before calling 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 two parameters are already documented as decimal-degree lat/lon, making 3 the baseline. The description earns above baseline by explaining how to obtain those coordinates (geocode or postcode_lookup) and by reinforcing that the point must actually be sea, which is the main way a caller gets a useless result.

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 ('Sea surface temperature forecast') plus scope: a coastal or offshore point in northern European waters, including UK coasts. It also enumerates the returned quantities (temperature now, 24-hour range, hourly values), so an agent knows exactly what this tool produces versus generic weather or marine 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?

Gives clear when-to-use framing via the intended audience (open-water swimmers, surfers, divers, anglers) and explicit prerequisites: obtain lat/lon from geocode or postcode_lookup first for UK place names or postcodes. It also states a failure condition (land points or outside the model area return no rows). The only gap is that it does not name marine_forecast or weather as the alternatives for wave or general conditions.

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

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

Annotations already declare readOnly/idempotent/openWorld/non-destructive, and the description adds substantial context on top: the MET Norway 3.0 source for core times versus NOAA-derived twilight and golden hour flagged as derived, explicit polar day/night handling, and the important caveat that daylight saving is not applied automatically (pass +01:00 for BST). It also discloses the 1-credit cost.

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, then progressively adds sourcing, timezone caveat, and prerequisite. Dense but every sentence carries operational information; the trailing parenthetical cost is the only near-redundant element.

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 what comes back (rise/set/noon/day length, bearings, noon altitude, twilight and golden-hour windows) and covers edge cases (polar day/night) plus the timezone trap. 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 baseline is 3, but the description adds real meaning: utc_offset governs the returned times, defaults to +00:00, and DST must be supplied manually; lat/lon must come from geocoding for place names. Only 'date' semantics are left entirely to 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?

States a specific verb+resource with full scope: 'Sunrise, sunset, solar noon and day length for any place on Earth and any date', then enumerates the derived outputs (compass bearing at rise/set, noon height, civil twilight, golden hour). No sibling tool covers this, and the agent can tell instantly what it returns.

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 use contexts (photographers, walkers, anglers, prayer and event timing) and an explicit prerequisite workflow: for UK place names or postcodes, call geocode or postcode_lookup first to get lat/lon. It does not explicitly exclude or compare against any sibling beyond that prerequisite routing, so it falls short of a full when/when-not statement.

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

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

Beyond the annotations (readOnly, idempotent, openWorld, non-destructive), the description discloses the data source (MET Norway Locationforecast 2.0), the important caveat that values assume a cloudless sky with real UV lower under cloud, that cloud cover is supplied alongside, the forecast horizon limit, and a 1-credit cost. These are exactly the behavioral traits annotations cannot convey.

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

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

The output contents and use cases are front-loaded, and each sentence carries real information (source, caveat, dependency, cost). It is a single dense paragraph with stacked parentheticals, which slightly hurts scanability but contains 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?

There is no output schema, so the description must describe return values, and it does (hourly series, daily peak, peak time, WHO band, advice). Combined with the clear-sky caveat, horizon limit and coordinate prerequisite, an agent has everything needed to call and interpret 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; the description goes further by telling the agent that lat/lon are mandatory in practice and where to obtain them from place names, and by tying utc_offset to how 'today' is defined. It adds workflow meaning rather than parameter syntax, which is already 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 verb and resource ('Hourly clear-sky UV index for one day at any point') and enumerates the returned components (peak UV, peak time, WHO exposure band, protection advice). It is clearly distinguishable from siblings like weather, cloud_cover_forecast and sunrise_sunset because it states the clear-sky UV framing and the single-day 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?

It gives concrete use cases ('sun-safety, outdoor work and holiday planning'), a hard limitation ('UV is only given for the first few days of the forecast'), and an explicit prerequisite route naming alternatives: 'for a UK place name or postcode, get coordinates from geocode or postcode_lookup first'. That covers when to use it and how to satisfy its inputs 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, openWorld), and the description adds substantial behavior beyond them: the upstream source (MET Norway Locationforecast 2.0), that speeds are 10-minute means at 10 m height, that gusts appear only where MET Norway supplies them, and a 1-credit cost. These caveats materially affect how an agent should interpret and budget the call.

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 what the tool returns before drifting into use-case examples, prerequisites, source and cost. Dense and mostly waste-free, though the activity list ('cycling, sailing, drone flying, kite flying or securing garden furniture') is slightly padded relative to the rest.

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 3-parameter read-only tool with no output schema, the description covers units, measurement basis, data source, coverage window, caveats, cost and the coordinate prerequisite. An agent has everything needed to call it correctly and interpret the results without further clarification.

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

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

Schema coverage is 100%, so a baseline of 3 applies, but the description adds real meaning: coordinates refer to 'any point' globally, and the note about fetching coordinates from geocode/postcode_lookup explains why lat/lon accept strings and heads off passing a place name directly. The hours window meaning is mostly duplicated from 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?

States a specific verb and resource ('Hourly wind forecast for the next 1-48 hours at any point') and enumerates exactly what is returned: speed in four units, compass direction, and Beaufort force with name. That scope cleanly separates it from sibling forecast tools such as weather, marine_forecast, cloud_cover_forecast and rain_forecast_next_hours without requiring the agent to open 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?

Gives concrete use contexts (cycling, sailing, drone/kite flying, securing garden furniture) and an explicit prerequisite chain: for a UK place name or postcode, obtain coordinates from geocode or postcode_lookup first. It does not explicitly say when to prefer the general 'weather' or 'marine_forecast' sibling instead, so the exclusion half of the guidance is missing.

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