UK Data: Space weather and aurora

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

Annotations only cover the read-only/idempotent/open-world profile, and the description adds substantive behavior the agent could not otherwise know: the upstream model, the 30-90 minute validity window, the poleward 5-degree fallback result, worldwide scope, explicit physical limitations, and a 1-credit cost. That is well beyond what the annotations 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?

The question-style opener front-loads the user intent, followed by the mechanism, the secondary result, and then caveats in a logical order. Nearly every clause carries information, though the question framing and the following 'Returns the probability...' sentence slightly overlap.

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 conveys what comes back (overhead probability plus the best chance within 5 degrees poleward) and bounds the forecast's validity. For a two-parameter, read-only lookup, no essential calling information 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% and both parameters (lat, lon) are already documented with ranges, so the description adds little syntax-level meaning. It only reinforces that the output is tied to a specific point plus a poleward neighbour, which is marginal extra information.

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 — the probability of aurora overhead at a given latitude and longitude — and attributes it to the NOAA SWPC OVATION model. It is clearly distinguishable from sibling space-weather tools such as kp_index_now, kp_forecast_3day, and solar_wind_speed, which report indices rather than location-specific probability.

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 frames the use case ('right now'), gives the forecast horizon (30-90 minutes), and explicitly rules out multi-day forecasting and daylight/cloud/moonlight effects, which implicitly routes the agent to kp_forecast_3day, cloud_cover_forecast, or sunrise_sunset. No sibling is named outright, so the routing is inferred rather than stated.

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

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

The annotations already establish that this is a read-only, idempotent, open-world, non-destructive call. The description adds substantive behavior beyond that: the returned forecast fields, the uncertainty of hours and 1-2 Kp, the NOAA SWPC source, and a 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?

The description is front-loaded with the core question and then efficiently covers return fields, intended use, uncertainty, the observed-value alternative, and cost. Every sentence adds either selection guidance or behavioral context, with no redundant restatement of annotations.

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

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

With no input parameters and no output schema, the description carries the burden of explaining what comes back and does so by naming the 3-hour blocks, daily maximum, peak block, and expected G-scale storms. It also provides uncertainty and cost context, leaving no material gap for calling the tool correctly.

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

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

The tool takes no parameters, so there is no parameter semantics to explain; the baseline for a zero-parameter tool is 4. The description correctly focuses on output content and usage instead of inventing parameter guidance.

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 forecast product — NOAA SWPC predicted Kp in 3-hour blocks over the next 3 days — and explicitly distinguishes it from the observed-value sibling kp_index_now. An agent can identify the resource, horizon, and returned elements without opening the schema.

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

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

It states the use case directly: planning aurora trips and checking storm watches. It also names kp_index_now as the alternative for observed values, which gives the agent a clear routing rule between forecast and current 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?

Beyond the annotations, the description discloses the data source (NOAA SWPC), the 1-credit cost, the returned fields, and the important behavioral limit that it reports observed activity only. It does not detail update cadence or error behavior, but the annotations already cover safety and idempotency.

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 question and return values, then adds audience, the observed-only scope, the alternative tool, and cost. Every sentence contributes useful selection or invocation context without unnecessary repetition.

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

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

For a one-optional-parameter, read-only data tool with no output schema, the description explains the return contents, time window, source, cost, and scope limitation. Nothing essential for correct selection or 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 hours parameter is already well documented as an optional integer from 3-168 with a default of 24. The description reinforces the default 24-hour window and the 7-day maximum, but it does not add substantial meaning beyond the schema.

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

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

The description gives a specific verb and resource: it returns the current planetary Kp index, storm level, and recent 3-hourly history. It also explicitly contrasts this observed-activity tool with kp_forecast_3day, so an agent can distinguish it from the sibling forecast tool.

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

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

It clearly states when to use this tool: for current observed geomagnetic activity and whether a storm is under way. It also names the alternative, kp_forecast_3day, for the coming days, giving an explicit when-not/alternative 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 read-only, idempotent, open-world, non-destructive behavior, and the description adds real context on top: data source (NOAA SWPC), sort order, the derived NOAA radio blackout level, and the included largest-flare summary. It also discloses a cost of 1 credit and the analytical limits of the data, though it says nothing about freshness/latency of the GOES feed.

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 user-facing question, then the concrete payload, then the boundary/cost caveats in a single tight paragraph. No sentence repeats the title or the schema.

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 fields (class, begin/peak/end times, peak flux, blackout level, largest flare) and names the upstream source, which is enough to call it confidently. Minor gap: no note on feed latency or how sparse results appear on quiet days.

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 days, limit, and min_class are already fully documented; the description only echoes the day range implicitly ('last 1-7 days'). It adds no guidance on how min_class interacts with the 'largest flare' summary or how limit truncation affects that summary.

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 ('Lists X-ray flares detected by the GOES satellites') with concrete scope (last 1-7 days), ordering (newest first), and returned fields. It also draws the boundary against adjacent phenomena: 'covers flares only, not CMEs or whether a flare will affect Earth,' which separates it from space-weather alert or 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?

The leading question 'Was there a big solar flare today?' frames the use case, and the closing sentence gives an explicit exclusion (no CMEs, no Earth-impact assessment). It stops short of naming which sibling to use instead for CME or impact questions, so routing is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered. The description adds the upstream source (NOAA SWPC), the credit cost, and the caveat that this is one daily value that does not by itself determine propagation — useful context beyond the annotations, though it says nothing about staleness or update cadence.

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 question and answer scope, then adds source, caveat and cost. Slightly redundant between the opening question and 'Returns the latest daily...', but every remaining sentence adds information an agent would otherwise lack.

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 parameters and no output schema, the description carries the return-value burden and does: the F10.7 value in solar flux units plus a rough HF conditions guide, a named source, and a caveat on interpretation. Nothing an agent needs to call or interpret it is missing.

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

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

The tool takes zero parameters, so the schema leaves nothing to explain — baseline 4 applies. The description correctly implies no input is required.

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

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

States a specific verb and resource — returns the latest daily 10.7 cm solar radio flux (F10.7) in solar flux units from NOAA SWPC. The unit, source and 'single daily value' scope let an agent distinguish it from siblings like kp_index_now or solar_wind_speed 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 question framing ('What is the solar flux index today?') and the note that propagation 'also depends on Kp, time of day and season' implicitly route the agent to the Kp tools as complements. There is no explicit when-not-to-use statement, so it stops short of 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, but the description adds substantive behavior: data source and provenance, a stale flag when the reading is over 30 minutes old, disclosure that the NOAA summary feed can lag by hours, and a 1-credit cost. That is real operational context an agent could not infer from 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?

Front-loaded with the question it answers, then return shape, use case, staleness caveat, exclusion, and cost. Every sentence carries information, though the aurora-chaser sentence is slightly narrative and could be tightened.

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?

No output schema exists, so the description must describe the return value, and it does: speed in km/s, a plain-language level, the age of the reading, and a stale flag. Source, caveats, and cost are all covered, leaving nothing an agent needs missing.

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

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

The tool takes no parameters, so the baseline is 4 and there is no parameter meaning to add. The description correctly implies a parameterless 'current reading' call.

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 and measurement: latest solar wind speed in km/s measured upstream of Earth, sourced from NOAA SWPC, plus a derived plain-language level. That is clearly distinct from siblings like kp_index_now, solar_flux_10cm, and aurora_chance_at_location.

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 concrete use case (aurora chasers judging whether a CME or high-speed stream has arrived) and an explicit exclusion: it does not include Bz, which also matters for aurora. It stops short of naming the sibling that does supply Bz, so routing is implied rather than spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so safety is covered; the description adds real value on top with the freshness window ('roughly the last few days only') and the cost disclosure (1 credit). It also notes the payload preserves verbatim official wording, which tells the agent what kind of data to expect. It stops short of stating ordering or pagination behavior.

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?

It opens with a usable framing question and immediately answers it with the concrete resource, then layers source, fields, audience and limits. Sentences are short and each carries information, though the audience clause ('newsrooms and enthusiasts') is the weakest earner and the cost note could be appended more tersely.

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 two-optional-parameter read-only feed with no output schema, the definition is close to self-sufficient: source, contents, field names, time coverage and credit cost are all stated. The remaining minor gap is that it does not describe ordering or what an empty result means, but nothing essential to 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 description coverage is 100% — both limit (1-50, default 10) and since_hours (1-720) are documented in the schema itself. The description adds no meaning about how those parameters interact with the stated recency window (e.g. whether since_hours can exceed the feed depth), 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 names the specific resource and source: 'latest official NOAA SWPC alerts, watches and warnings', enumerating the subtypes (geomagnetic storm watches, K-index warnings, flare and proton alerts) and the returned fields (type, headline, issue time, verbatim message). It clearly differs from measurement-style siblings such as kp_index_now or solar_wind_speed, though it never names a sibling explicitly, which keeps it from a 5.

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 audience cue ('useful for newsrooms and enthusiasts who need the official wording') and the recency constraint ('covers roughly the last few days only') imply when this tool fits. However, there is no explicit when-to-use / when-not-to-use guidance and no routing to alternatives like kp_index_now, kp_forecast_3day, space_weather_scales or solar_flares_recent, which an agent would reasonably need to choose among.

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), so the description's added value is the credit cost, the 24h retrospective window and 3-day forward window, and the explicit statement that no per-system impact interpretation is provided. It does not say how frequently the scales refresh, which would matter for a 'right now' 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?

Content is front-loaded: a framing question, then the exact payload, then audience, then scope limit, then cost. Every sentence carries information, though the opening question is rhetorical padding and the audience list is longer than strictly necessary.

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 zero parameters and no output schema, the description carries the full burden of describing the return value, and it does so precisely: R/S/G scales, 24h max, 3-day probabilities. An agent knows what it will get and what it will not get.

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

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

The tool takes no parameters, so there is no parameter semantics to explain and the baseline applies. Nothing in the description conflicts with the empty 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 the exact resource and payload: NOAA R/S/G space weather scales, the 24-hour maximum, and 3-day SWPC probabilities. That is specific enough to separate it from siblings like kp_index_now or solar_flares_recent, though it never names those alternatives to make the distinction 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?

It gives concrete applicability (HF radio, pilots, drones/GPS, satellite and grid operators, journalists) and one clear exclusion: it returns levels and probabilities, not impact assessments for a specific system. It stops short of pointing to a sibling when the agent actually needs alert-level or impact detail.

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