Tanod Sky

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

Beyond the readOnly/idempotent annotations, the description discloses accuracy (haversine within ~0.5% of WGS-84), data provenance (OurAirports, error-prone, no endorsement), error semantics (422 unknown_airport, not charged), latency (<0.1s), price, and free-tier rate limits. This is unusually rich 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?

Front-loaded with the core purpose and output, then scales to accuracy, sourcing, errors, latency and cost. It is dense but well ordered; the pricing/attribution sentences are borderline but still earn their place for an agent deciding whether to call.

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 fully carries the return-value burden by enumerating units, bearings and midpoint, and it covers accuracy, errors and cost. Nothing an agent needs 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 the baseline is 3, but the description adds a real constraint not in the schema: airport codes are '2-8 characters'. It otherwise restates the code-or-{lat,lon} form already documented.

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 computation (great-circle distance) over specific resources (two airports by code or coordinates), plus the exact output set (km/nautical/statute miles, bearings, midpoint). This clearly distinguishes it from siblings like lookup_airport or geocode.

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 a clear negative constraint ('Informational only: not for flight planning or navigation') that bounds when to use it, but it never names an alternative sibling to route the agent elsewhere. Clear context, no explicit 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?

Goes well beyond the annotations: caching (up to an hour), the 100-result cap, latency (~1 s), pricing ($0.001), the shared free-tier pool across skypeek routes, and the exact failure mode (503 upstream_unavailable, not charged, retry later). For a read-only open-world call these operational traits are exactly what an agent needs and the 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-loads purpose, then inputs, then data provenance, limits, caching, errors, latency and price — a sensible ordering. It is dense and some material (NASA endorsement disclaimer) reads as boilerplate, but nearly every sentence carries actionable information.

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

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

With no output schema, the description enumerates the return fields (designation, approach time, distance with 3-sigma range, velocity, magnitude, diameter), plus caps, caching and error semantics. Nothing an agent needs 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?

Schema description coverage is 100% and both parameters already document their ranges and defaults in the schema, so the description's restatement of `days` and `dist_max_au` adds little. Baseline 3 is appropriate since the schema carries the semantic load.

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 ('near-Earth object close approaches to Earth in the next 1-30 days within a miss distance') and enumerates the returned fields. An agent can distinguish this from nearby siblings like satellite_passes and aurora_forecast purely from the description.

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

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

Gives clear scope (1-30 day look-ahead, default miss distance) and an explicit exclusion ('Not an impact-risk assessment'), which steers the agent away from a plausible misuse. It does not name a sibling alternative or spell out when this is preferred over other astronomy routes, so it falls short of a 5.

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

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

Annotations already declare read-only/idempotent, but the description goes well beyond them: 10-minute caching, 503 upstream_unavailable on outage and that it is not charged, sub-second cached vs seconds-on-refresh latency, and the dark/clear-sky assumption where cloud, moonlight and light pollution are unmodelled. That is exactly the kind of behavioral context structured fields 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?

A single dense, front-loaded paragraph that leads with the meaning of the returned value before logistics. It is somewhat long and repeats the lat/lon ranges already in the schema, but every remaining sentence (cost, cache, outage) earns its place for an agent deciding whether to call 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?

With no output schema, the description carries the return contract itself (chance 0-100 plus Kp, solar altitude, dark-enough flag), and also covers the cost, free-tier limit, caching and error mode. An agent has everything needed to decide to call it and interpret 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 coverage is 100% and both parameters carry their own range descriptions, so the schema does the heavy lifting. The description only restates the lat/lon ranges and frames them as a 'point', adding no real meaning 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: the percent chance of visible aurora overhead at a point, sourced from NOAA SWPC's OVATION model with a 30-90 minute horizon. This is clearly distinguishable from the sibling get_space_weather, which is a general space-weather lookup.

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 sets context (point-based, 30-90 min forecast, dark-sky assumption) but never states when to prefer this over the sibling get_space_weather or any alternative. Usage is implied rather than explicit, with no when-not guidance.

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

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

Goes well beyond the read-only/idempotent annotations: local decoding with no upstream call, UTC day/hour with no month or year, unparsed groups surfaced in the response, 422 invalid_report on unreadable input (not charged), typical latency under 0.1s, price and free-tier quota. This is unusually rich operational context.

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

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

Dense but front-loaded: the decode purpose and outputs come first, followed by input, caveats, and cost. Every sentence carries information, though the pricing/quota clause makes the block longer than strictly needed for tool selection.

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

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

With no output schema, the description compensates by enumerating the decoded fields (wind, visibility, weather, clouds, temperature/dew point, altimeter, flight category, TAF periods, `unparsed`). Combined with the error and cost notes, 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% and both parameters are documented there (including the enum and the 2,000-character limit). The description mostly restates raw/kind and its 'auto detects it' behavior, adding the useful note that unrecognised groups land in `unparsed` but little parameter-specific 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?

States a specific verb (decode) and resource (one pasted METAR or TAF report) and enumerates the decoded outputs, which clearly separates it from the fetch-oriented siblings get_metar/get_taf. An agent can tell it decodes supplied text rather than retrieving a report.

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: one pasted report, max 2,000 characters, and an explicit 'informational only: not for flight planning or navigation' exclusion. It does not name the alternative siblings (get_metar/get_taf) for retrieving reports, so routing is implied 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?

Annotations cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial extra context: typical latency under 0.1 s with a 1 s cold-start, per-call price, the shared 10-call/day free pool per IP, and the 404-not-charged behavior. The data source and attribution obligation are also disclosed.

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?

Dense but well front-loaded: the core mechanism leads, then input shape, then matching, error, latency, pricing, free tier, and licensing in short labeled fragments. Slightly list-heavy and the price/licensing tail could be tightened, but nothing is redundant.

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

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

With no output schema, the description takes on the burden of explaining return values and does so (candidate fields, distance_km on reverse, attribution field). Combined with error behavior, latency, and rate limits, an agent has everything needed to call and interpret this 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 coverage is 100% and the schema descriptions already state the lat/lon ranges and the either/or rule, so the baseline is 3. The description goes further by explaining the match semantics (only cities 15,000+, 'City, CC' parsing) and enumerating returned fields (lat, lon, country_code, admin1_code, population, timezone, distance_km), which meaningfully enriches parameter understanding.

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 the specific verb+resource (offline geocoding over GeoNames cities15000) and immediately distinguishes the two modes, forward (place) and reverse (lat/lon), with the exact result shape of each. No sibling tool in the list does city-level geocoding, so the agent can select it unambiguously.

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 mode-selection rules ('place alone' vs 'lat and lon together'), the accepted input formats ('City' or 'City, CC' with ISO country or US state code), and a clear exclusion: cities only, no street addresses. It also names the failure condition (404 place_not_found, not charged), which is when-not guidance.

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

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

Goes well past the readOnly/idempotent/openWorld annotations: discloses the NOAA source, up-to-5-minute caching, found:false for stations with no report, the 422 invalid_station and 503 upstream_unavailable error semantics with 'not charged' billing behavior, latency expectations, and a prompt-injection advisory to treat report text as data. This is unusually complete behavioral disclosure.

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?

Purpose is front-loaded and virtually every clause carries operational value (pricing, errors, caching, safety). The cost is a single dense semicolon-chained block with no paragraphing, which is heavier to parse than it needs to be for the amount of distinct 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?

There is no output schema, so the description carries the return-value burden and does so fully — raw plus decoded fields, per-station found flag, station metadata. Combined with documented error codes and latency, an agent has everything needed to call and interpret this 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 coverage is already 100%, so the baseline is 3, but the description adds real meaning: one price covers 1-20 stations, ICAO ids must be 4 characters, and a malformed id yields 422 invalid_station rather than a partial result. The decode default of true is restated rather than extended, 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 verb and resource — 'the latest METAR observation for 1-20 ICAO stations' — and enumerates exactly what comes back (wind, visibility, weather, clouds, temperature/dew point, altimeter, flight category, station name/position/time). The 'latest observation' scope inherently separates it from forecast-oriented siblings like get_taf.

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 for use (current station weather) plus an explicit exclusion: 'Informational only: not for flight planning or navigation.' However, it never names an alternative such as get_taf for forecasts or decode_metar_taf for decoding a raw METAR string the caller already has, so routing between near-siblings is left 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 cover readOnly/idempotent/openWorld, yet the description adds much more: 5-minute caching, `stale: true` fallback on SWPC outage, 503 upstream_unavailable semantics (uncharged, retry later), latency expectations, price, and the free-tier pool shared across all skypeek routes. It also warns that quoted report/alert text must be treated as data, not instructions — a real prompt-injection safeguard.

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?

Long but dense: purpose is front-loaded, then input, provenance/licensing, caching, error behavior, latency, and pricing. Almost every sentence carries operational value; the licensing/endorsement clause is the one mild padding item for an agent audience.

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 return values and does so thoroughly (fields, freshness, stale flag, alert count). Combined with the error/rate-limit/pricing context, an agent has everything needed to call and interpret this 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?

Zero parameters, so the baseline is 4. The description reinforces this by stating an empty object is expected, leaving no ambiguity about how to invoke it.

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 and enumerates exactly what is returned: Kp index with G-scale, 3-hour-step Kp forecast, solar wind speed and Bz/Bt, and up to 10 recent SWPC alerts. This clearly distinguishes it from siblings like aurora_forecast, get_weather, and sun_moon_times.

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 'Input: nothing (send an empty object)', giving the agent a clear calling context, and the data scope implies when this is the right tool. It does not, however, name alternatives (e.g. aurora_forecast for visibility rather than raw indices) or state when NOT to use it.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: discloses 5-minute cache TTL, latency (~2 s, <0.1 s cached), pricing (USD 0.001, free 5 calls/IP/UTC day shared pool), error semantics (422 invalid_station and 503 upstream_unavailable, both uncharged), and a prompt-injection warning that quoted report/alert text must be treated as data. This is rich behavioral context an agent needs to call and interpret the tool safely.

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?

Purpose and inputs are front-loaded in the first sentences, and most sentences earn their place (errors, pricing, latency, safety). There is mild redundancy, e.g. pricing is stated twice ('One price for 1-20 stations' and 'Price: USD 0.001'), which keeps it from a 5.

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, but the description fully enumerates the returned content (raw + decoded per period, wind, visibility, weather, clouds, flight category, issue/validity times, temperature extremes), plus cost, latency, and failure modes. Nothing an agent needs in order to invoke and 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?

Schema description coverage is 100%, so both parameters (stations, decode) are already documented in the schema, including the decode default and the array bounds. The description restates the ranged station input and one-price-per-call semantics but adds no format or syntax detail 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?

States a specific verb+resource (current TAF forecasts for 1-20 ICAO stations) with the decoding granularity (BASE, FM, TEMPO, BECMG, PROB) and the returned fields, so it is clearly distinguishable from siblings like get_metar and decode_metar_taf. An agent knows exactly what it fetches 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?

Provides a clear when-not ('Informational only: not for flight planning or navigation') and states the 1-20 station batching use case plus the free-tier/informational context. It stops short of explicitly routing to the closest alternatives (get_metar for METAR, decode_metar_taf for decoding), so it falls short of a 5.

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

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

Goes well beyond the readOnly/idempotent/openWorld annotations: documents error semantics (404 place_not_found not charged, 5xx upstream errors not charged), pricing (USD 0.002), free-tier rate limit (5 per IP per UTC day), latency (0.1-2 s), data provenance/licensing, and accuracy caveats. This is exactly the behavioral context an agent needs.

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 purpose, then input contract, return shape, errors, pricing, and caveats in a tight sequence. It is dense but every clause earns its place; only mild risk of being read as a wall of text.

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 enumerates the return fields (location, updated_at, units, hourly rows, cached, attribution), covers input constraints, error paths, cost, and licensing obligations. Nothing an agent needs to invoke or interpret the call is missing.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning: the lat+lon-vs-place exclusivity, the place matching rule ('City, CC' ISO codes, 15,000+ population), the default of 24 hours, and the not-charged 404 on no match. It reinforces and extends rather than merely repeats 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 weather forecast for a point or a city') and specifies both accepted input modes. An agent immediately knows this retrieves forecast data and can tell it apart from the rest of the (non-weather) sibling set.

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?

Clearly explains the two mutually exclusive input modes (lat+lon together vs place alone) and gives an explicit when-not: not for safety-critical decisions, use official services instead. It lacks formal 'alternatives' routing, but no sibling weather tool exists to route to, so the guidance is essentially complete.

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 safety (readOnly/idempotent/non-destructive), and the description adds substantial extra context: a missing code yields 404 airport_not_found and is not charged, answers come from a bundled copy with no upstream call, latency (~2 s first call, then <0.1 s), price, and a shared 5-call free pool per IP per UTC day.

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-dense and largely front-loaded with purpose, inputs, returns and caveats in order. The opening 'skypeek: an airport by ICAO...' is grammatically truncated, and the parenthetical-heavy single block is long, but almost every clause (data source, caching, price, error behavior) 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 by enumerating return fields (runway ends, length, width, surface, lighting, headings; radio frequencies; match fields such as codes, type, position, elevation, country). Error behavior, latency and pricing are also covered, leaving nothing essential for a correct call 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 the schema already documents code, query, limit and country with ranges and defaults. The description only restates those semantics (including the 'send code or query' choice), adding little that isn't already in 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 and both lookup modes ('an airport by ICAO, IATA or ident code ... or up to 20 matches of a name or city search'), listing exactly what it returns. Clearly separable from siblings like airport_distance, geocode and get_metar.

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 for each input mode (code for a single airport, query for name/city matching, country to narrow) and a domain exclusion ('Informational only: not for flight planning or navigation'). It does not, however, route the agent to a sibling tool for adjacent needs, so no explicit 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 cover the read-only/idempotent profile, and the description adds substantial extra context beyond them: SGP4 predictions rather than observations, upstream cache refreshed at most every 2 hours (never per call), a 40-pass cap, 422/503 error semantics with 'not charged' notes, latency expectations, pricing, and the shared per-IP free pool.

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?

Dense and front-loaded: the core purpose and inputs come first, then operational caveats. It is long, but nearly every clause (caps, error codes, cache behavior, pricing) carries distinct value; a minor amount of repetition of schema defaults keeps it from a 5.

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

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

With no output schema, the description compensates by enumerating the returned fields (start/highest/end times, azimuth, compass point, elevation, duration, naked-eye visibility). Combined with error, cost, cache, and latency disclosure, 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 coverage is 100%, so baseline is 3, but the description adds value beyond the schema by naming the default satellite (25544 ISS), confirming days=1-3/default 2, min_elevation default 10, and explaining that unsupported NORAD ids yield a 422 unknown_satellite. It largely restates schema detail but contributes the validation and supported-set context.

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

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

States a specific verb and resource (computes satellite passes over a lat/lon point) with scope (next 1-3 days, default ISS) and enumerates the returned fields. It is clearly distinguishable from siblings like sun_moon_times or aurora_forecast.

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

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

Gives clear context: defaults (ISS, 2 days, 10° elevation), which satellites are supported (CelesTrak stations/visual groups plus NOAA 15/18/19), and what an unsupported NORAD id produces. It stops short of naming an explicit alternative tool or when not to use this one.

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/destructive flags, but the description goes much further: local Meeus computation, no upstream call, accuracy tolerances, modeled limitations, error behavior, runtime, price, and shared free-tier limits. This is unusually rich 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?

The description is a single dense paragraph, but it is front-loaded with outputs and inputs and nearly every sentence carries operational value. The redundant 'skypeek:' prefix and pricing/rate-limit tail keep it from a 5.

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

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

For a tool with no output schema, the description explicitly lists returned values and adds accuracy, limitations, errors, latency, and cost, so an agent has enough to call it correctly. Nothing material 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 the description's parameter notes (lat, lon, optional YYYY-MM-DD date 1900–2100, IANA tz default UTC) largely duplicate the schema's own descriptions. It adds little semantic meaning beyond the schema baseline.

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

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

The description names the resource and enumerates exactly what is computed (sunrise/sunset, solar noon, day length, three twilight bands, moonrise/moonset, phase, illumination, distance), plus the input domain (point + local date + chosen time zone). It leaves no ambiguity about the tool's function, and no sibling tool computes the same quantities, even without an explicit sibling callout.

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 establishes the context for use (you have coordinates, a local date, and a time zone) and gives defaults, but it does not tell the agent when to prefer it over alternatives or state exclusions. No sibling-tool routing is provided.

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