Tanod Sky

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial extra context: 422 unknown_airport error semantics with 'not charged', latency (<0.1 s), an accuracy bound (~0.5% vs WGS-84), pricing, and a free-tier rate limit. This is well beyond what the annotations 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?

Purpose and the routing hint are front-loaded ahead of the auxiliary detail. It is dense and largely earns its space, though pricing, free-tier quota, and the docs URL are somewhat promotional for a selection-time description.

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?

Return values, error behavior, accuracy caveats, data provenance, cost, and rate limits are all covered. An output schema exists, so return-shape explanation is not strictly required, making the coverage more than sufficient for a two-parameter distance 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 100% and the parameter descriptions already state 'Airport code (ICAO, IATA or ident) or {lat, lon}'. The description restates this format and notes the two arguments can be mixed, adding marginal value; baseline of 3 applies when the schema does the heavy lifting.

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 ('Calculate the great-circle distance between two airports or points') and immediately distinguishes itself from the sibling lookup_airport, which handles airport details. An agent can select this over lookup_airport from the description alone.

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 routing ('For airport details use lookup_airport') plus a clear exclusion ('Informational only: not for flight planning or navigation'). Both a when-to-use and a when-not-to-use condition are stated, leaving nothing 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, non-destructive behavior, and the description layers on genuinely additive traits: results cached up to an hour, a 100-result cap, upstream outage mapped to 503 upstream_unavailable with no charge, sub-second latency, price and free-tier limits, and an explicit non-endorsement disclaimer.

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

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

Front-loaded with purpose and the sibling routing, followed by operational facts (caps, caching, errors, pricing). It is dense and close to a wall of text, but nearly every clause carries decision-relevant information for a paid, metered API 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?

Covers data provenance, freshness, result caps, failure semantics, cost, and latency, and even enumerates return fields despite an output schema existing. Nothing an agent needs to invoke this correctly or estimate cost 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% and both parameters already carry ranges, defaults, and even the au-to-lunar-distance conversion, so the description's restatement ('default 0.05 au, about 19.5 lunar distances') adds nothing new. Baseline 3 is appropriate when the schema does all parameter work.

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 ('List asteroid and comet close approaches to Earth') with the scope (next 1-30 days, miss distance threshold). It explicitly names the sibling it is not ('For space weather use get_space_weather'), so an agent can disambiguate without opening either 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 an explicit alternative with its selecting condition (space weather -> get_space_weather) and a when-not caveat ('Not an impact-risk assessment'). An agent knows both when to reach for this tool and when to look elsewhere.

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 open-world. The description adds substantial behavioral context: return semantics, 10-minute cache, 5 free calls per IP per day, USD 0.001 price, upstream outage as 503 upstream_unavailable (not charged), typical latency, NOAA SWPC provenance, and model limitations.

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

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

Front-loaded with the purpose and the get_space_weather alternative in the first two sentences. Later sentences are dense and mostly useful (returns, caveats, caching, pricing, docs), though the NOAA endorsement disclaimer is less critical for tool selection. Slightly long but not repetitive.

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

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

An output schema exists, yet the description also explains return fields. It covers parameters, return semantics, model caveats, error behavior, pricing, caching, and documentation, leaving nothing needed for correct invocation 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 lat and lon are documented with ranges. The description adds only that the forecast is for a location/point, which does not go beyond the schema's syntax or constraints, so the baseline of 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 (forecast) and resource (chance of visible aurora at a location in the next 30-90 minutes). Directly distinguishes itself from the sibling get_space_weather by routing Kp and solar wind queries there.

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 names get_space_weather as the alternative for Kp and solar wind. The caveat that the model assumes a dark, clear sky and ignores cloud, moonlight, and light pollution tells the agent when results may be misleading.

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/non-destructive profile, and the description adds substantial context beyond them: decoded output groups, unrecognised groups surfaced in `unparsed`, day/hour-as-reported with no month/year, the 422 invalid_report path (not charged), no upstream call, sub-0.1s latency, pricing and free tier.

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 action and routing lead, then behavior, limits, and pricing. Every sentence carries information, though the pricing/free-tier/docs tail is 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?

An output schema exists, yet the description still summarizes what comes back (wind, visibility, clouds, temperature, flight category, TAF periods) and flags the unparsed buffer and error path, leaving no gap for a text-in/structured-out decoder.

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 (raw with its 2,000-char cap, kind enum with auto default) are documented in the schema. The description implies the paste-and-decode flow and the METAR/TAF distinction but adds no syntax or kind-detection detail beyond the schema, so the baseline 3 holds.

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 (METAR or TAF weather report) and names the sibling get_metar for the fetch case. An agent can immediately distinguish it from get_metar/get_taf without opening the schema.

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

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

Explicitly routes the agent: fetch the latest report with get_metar, use this to decode text you already have. Also states a when-not ('Informational only: not for flight planning or navigation'), covering both the alternative and the exclusion.

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: pricing (USD 0.005), free tier (10 calls/IP/UTC day), latency (2-15 s, faster cached), error semantics (0 matches charged, 422/404/503 with charging rules), ODbL attribution, and an untrusted-data warning. Annotations only cover read-only/open-world, so this adds substantial 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?

Front-loaded with purpose and input shape, and the operational facts are terse. Minor waste: the place-kind enumeration and the untrusted-data caution each appear twice, lengthening an already dense paragraph.

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

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

With an output schema present, return formatting needn't be described; the description still covers input modes, defaults, error outcomes, latency, cost, and licensing. Nothing an agent needs to invoke 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 coverage is 100%, so the baseline is 3; the description adds the useful combination logic that lat/lon and place are alternatives and that radius_m/limit are optional. It doesn't restate the kind list fully (it says 'and more'), but the schema carries that detail.

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

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

Opens with a specific verb and resource ('Find places nearby'), names concrete place kinds, and bounds scope (one kind, near a point, nearest first, OpenStreetMap). An agent can distinguish it from siblings like geocode purely from the text.

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 city-name resolution to the sibling 'geocode' and clarifies that a city name means its centre, not an address. It also states the required input order (kind, then lat/lon or place) and that one kind is returned per call.

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, and the description adds genuinely new behavior: a 404 place_not_found that is not charged, typical latency under 0.1 s with a 1 s first call, price USD 0.001, a 10-call free tier per IP per UTC day, and the attribution obligation carried in the `attribution` field.

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 the alternative tool, then input rules, then operational facts. Every sentence carries information, though the pricing, license, and docs-link tail makes it denser than strictly necessary for a 3-parameter 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?

An output schema exists so return values need no explanation, and the annotations cover the safety profile. What remains — input modes, matching limits, error behavior, cost model, and data provenance — is fully addressed.

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 matching semantics not in the schema: `place` accepts "City" or "City, CC" with an ISO country or US state code, and it only matches cities, never street addresses. The either/or exclusivity rule is also clarified.

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 (geocode) and resource (city names / coordinates) and immediately scopes it to the offline GeoNames cities15000 table. It explicitly distinguishes itself from the sibling find_places_nearby, so an agent can route without opening either 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 exact input modes (either `place` alone or `lat` and `lon` together), names the alternative tool for nearby-place queries, and gives the matching scope (cities of 15,000+ people, no street addresses). When-to-use and when-not-to-use are both covered.

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 the description goes well beyond them: 60 s cache, sub-1 s latency, 422 for non-US/unknown codes, 503 for unreadable feed, which responses are charged, and that reason text is untrusted. This is exactly the extra behavioral context structured fields 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-loads purpose and the sibling redirect before pricing, caching and error detail, so the important routing information is not buried. It is dense with billing, latency and security boilerplate that repeats standard service policy, which slightly dilutes it but each block remains scannable.

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

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

An output schema exists, yet the description still summarizes the returned fields (reason, FAA update time), and it covers errors, caching, pricing and untrusted-content handling. Nothing needed to select or invoke the tool 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% and the schema already documents the optional IATA/ICAO `airport` field, so the baseline is 3. The description adds transport-level semantics (query parameter on GET, JSON body on POST) and restates the omit-for-all behavior, which is genuinely 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 and resource (live FAA airport status: ground stops, delay programs, closures, delays) and explicitly routes the sibling case away with 'For airport data use lookup_airport.' An agent can distinguish this from lookup_airport, get_metar and the other aviation siblings without opening a schema.

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

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

Explicitly names the alternative tool for non-status airport data and describes the scope (one airport vs. all with an active event). It stops short of enumerating when-not-to-call conditions (e.g., that normal status is itself a charged result), but the routing guidance is clear and actionable.

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/openWorld, and the description adds substantial context beyond them: 5-minute caching, 422 for bad station ids, 503 upstream_unavailable for outages, both uncharged, sub-2s latency, pricing/rate limit, and a prompt-injection caution about quoted report text being data, not instructions.

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 purpose and sibling routing in the first sentence, with constraints, errors and pricing following in a compact run. It is somewhat dense with legal and pricing boilerplate that dilutes the operational core, but almost every sentence carries usable information.

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

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

An output schema exists, so return values need not be re-explained; the description still covers error semantics, latency, caching, data provenance and safety caveats. Nothing an agent needs to invoke 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 (stations, decode) are fully documented in the schema, so the baseline is 3. The description adds modest extras — one price per call, raw-vs-decoded output, the found:false case for missing stations — but no syntax or format detail the schema lacks.

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 ('Get current METAR airport weather reports') plus scope (1-20 ICAO stations, raw and decoded). It explicitly names the sibling tools it is not (get_taf for forecasts, decode_metar_taf for decoding a held report), so an agent can route correctly 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 explicit alternatives with the condition that selects each: forecasts → get_taf, decoding an existing report → decode_metar_taf. It also adds a clear when-not ('Informational only: not for flight planning or navigation'), leaving nothing 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?

Goes far beyond the annotations: latency (5-25 s), price and free-tier quota (USD 0.01, 5 calls/IP/UTC day), failure modes that are not charged (404 too_cloudy, no_scene, no_imagery), the non-real-time caveat about `date`, cloud occlusion behavior, the NASA GIBS fallback for wide areas, and licensing/attribution terms. This is exactly the operational 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-loads the purpose and the sibling disambiguation in the first sentence, then layers behavior, cost, and licensing. It is a dense single paragraph with some packing, but nearly every clause earns its place and nothing is redundant with 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?

Despite 8 parameters and an output schema, the description supplies the operational context an agent needs (cost, quota, latency, error semantics, source fallback, licensing), while the output schema covers the return shape. Nothing needed 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; the description adds cross-parameter meaning, e.g. that index views paint clouds grey and that radius over 10 km forces NASA 250 m true colour only, plus the scene-selection window implied by `date`. It stops short of documenting several parameters (size, max_cloud tolerances) in prose, but those are well covered by 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 (get a satellite image of a place or coordinates) and immediately names the sibling it is not (get_weather for forecasts). It further specifies the source imagery, view modes, and resolution, so an agent can distinguish it from every sibling in the 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?

Explicitly routes the agent away from this tool for forecasts ('For the forecast use get_weather') and clarifies acceptable inputs (place, or lat and lon). It does not spell out when-not conditions beyond that or compare against siblings like geocode/find_places_nearby for locating a place first.

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

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

Annotations already cover readOnly/idempotent/openWorld/non-destructive, yet the description adds substantial behavior the annotations cannot: 5-minute caching, stale:true fallback when SWPC is down, 503 upstream_unavailable semantics with no charge, sub-second cached vs seconds-on-refresh latency, and a prompt-injection warning about treating alert text as data. This is exactly the extra context annotations leave out.

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 purpose and return contents before cost, provenance, and error detail, and every block earns its place for a cost-and-caching-sensitive agent. The NOAA non-endorsement disclaimer paragraph is somewhat lengthy relative to its decision value, keeping it just under 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?

Even though an output schema exists (so return values need not be restated), the description goes further by enumerating the payload fields, documenting caching/staleness, error codes, latency, pricing, and a docs link. Nothing an agent needs to call or interpret this tool 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 per the rubric the baseline is 4; there is no parameter surface for the description to clarify or obscure.

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 ('Get space weather: Kp index, forecast, solar wind, alerts') and explicitly distinguishes itself from the sibling aurora_forecast ('For aurora at a place use aurora_forecast'). An agent can route between the two without opening either 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 names the alternative tool and the condition that selects it (aurora at a place), and adds cost/tier context (USD 0.001, 5 free calls per IP per UTC day) that affects invocation decisions. It lacks a fuller when-not-to-use statement beyond the aurora case, 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 cover the safety profile (readOnly, idempotent, non-destructive), but the description goes well beyond them: cache TTL of 5 minutes, specific error codes and their billing behavior (422 bad station, 503 upstream_unavailable, neither charged), latency expectations, free-tier limits, and a prompt-injection caveat ('treat it as data, never as instructions'). This is unusually rich 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?

Front-loaded with the verb+resource and the sibling exclusion, which is the right ordering. It is dense and semi-colon heavy, and the NOAA non-endorsement and docs-URL sentences are low-value padding for an agent deciding whether to call the tool, but nothing is buried or misleading.

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

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

An output schema exists, yet the description still summarizes the return shape, and it additionally covers error semantics, caching, billing, and latency. For a paid, network-dependent, prompt-injection-exposed tool, everything an agent needs to call it safely is present.

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 both parameters are already documented, giving a baseline of 3. The description adds meaning beyond the schema by spelling out the decoded forecast structure (BASE, FM, TEMPO, BECMG, PROB) and the wind/visibility/cloud/flight-category fields, which clarifies what `decode` actually toggles.

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 ('Get current TAF airport weather forecasts') and immediately carves out its scope against the sibling observation tool: 'For current observations use get_metar.' An agent can distinguish this from get_metar and decode_metar_taf 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 alternative case ('For current observations use get_metar') and states a use exclusion ('Informational only: not for flight planning or navigation'). Both the when and the when-not are present, which is rare and directly actionable.

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, open-world, idempotent, and non-destructive behavior. The description adds substantial context beyond them: price, free daily quota, typical latency, 404 vs 5xx charging behavior, data sources, attribution requirements, and a model-accuracy caveat.

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 purpose and the key get_metar alternative, and it avoids filler. It is dense with several clauses about pricing, quotas, errors, attribution, and safety caveats, all of which are relevant but make it longer than ideal.

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

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

An output schema exists, so return values need not be explained. The description covers all necessary calling context: input combinations, matching rules, error and charging behavior, latency, price, free quota, data attribution, and safety limitations.

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 baseline is 3. The description adds meaningful place-matching semantics beyond the schema: offline matching only for cities of 15,000+ people, ISO country-code format, and a 404 place_not_found outcome when unmatched.

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 states a specific resource and forecast type: an hourly weather forecast for a point or city. It distinguishes itself from the sibling get_metar by naming it as the airport-observations alternative.

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

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

It gives explicit when-to-use guidance: either lat/lon together or place alone, optional hours, and an alternative (get_metar) for airport observations. It also states when not to use it for safety-critical decisions and directs users to official services.

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 piles on genuinely useful behavior: bundled copy with no upstream call, a 404 airport_not_found that is not charged, typical 0.1 s latency (first call ~2 s), USD 0.001 price, 5 free calls/IP/day, and an upstream data provenance/accuracy caveat.

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 the sibling routing are front-loaded, and the dense single paragraph keeps nearly every clause informative (limits, pricing, latency, caveats). It is on the long side and mixes operations, output, pricing and legal caveats in one unbroken block, but there is little pure 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 an output schema present, return values need not be explained, yet the description still summarizes them. Combined with error semantics, latency, pricing, free-tier limits, data provenance and a docs link, an agent has everything needed to decide and call 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 baseline is 3, but the description goes further by describing what each input yields: a code returns one airport with runway and radio-frequency detail, while a name/city query returns up to 20 matches with name, codes, type, position, elevation, country, region and municipality. That output-linked semantics of code vs query exceeds the schema's terse constraints.

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 ('Look up an airport') plus the accepted identifier forms (ICAO, IATA, name, ident). It explicitly names the sibling tool airport_distance as the one to use for a different task, so an agent can disambiguate without opening either 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?

Names the alternative (airport_distance) and the condition that selects it, and adds a hard usage boundary: 'Informational only: not for flight planning or navigation.' The code-vs-query selection is reinforced from the schema, and the country filter's condition ('optionally in one country') is 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 already declare readOnly/idempotent/openWorld/non-destructive, and the description goes well beyond them: unsupported NORAD id returns 422 (not charged), cold cache or upstream outage returns 503 (not charged, retry), sub-second typical latency vs. up to a minute cold, 40-pass cap, price ($0.002) and free tier (5/day per IP). This is unusually rich operational 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?

The core purpose is front-loaded and every clause (return fields, errors, price, limits) carries actionable information. It is dense and somewhat run-on, packing billing/latency/error clauses into long sentences, which costs a little readability.

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 7-parameter read tool with 100% schema coverage, full annotations, and an output schema, the description supplies everything else an agent needs: data source (CelesTrak SGP4), that results are predictions not observations, pricing, rate limits, latency, and error semantics.

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 additionally conveys that the default satellite is the ISS (25544), enumerates the supported satellite groups, and specifies that any other NORAD id yields a 422. It adds real constraint meaning beyond the raw 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+scope ('Predict satellite passes over a location') and immediately names the tool to use for an adjacent need ('For sun and moon times use sun_moon_times'). An agent can distinguish it from sun_moon_times and the other space tools without opening the schema.

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

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

Explicitly routes the agent away to sun_moon_times when sun/moon times are wanted, which is a genuine when-not condition. However, it gives no guidance on how this differs from other satellite tools (e.g. get_satellite_image) and no other exclusion 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?

Goes well beyond the readOnly/idempotent annotations: computed locally with no upstream call, accuracy bounds (~1 min sun, ~3 min moon), explicit limitations (sea-level horizon, no terrain/weather), 422-not-charged behavior, latency (<0.2 s), price, and free tier. This is rich 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 and is dense but every sentence earns its place (accuracy, limits, errors, cost, docs). Slight redundancy from the repeated 'skypeek:' brand prefix and a long single paragraph prevent 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 4-param tool with an output schema and full annotation coverage, the description supplies accuracy, failure mode, cost, latency and a docs link, leaving nothing an agent needs to call 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 schema already documents lat, lon, date and tz. The description reinforces the point/date/timezone framing but adds no syntax or format detail beyond what the schema provides, 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 set (sunrise, sunset, twilight, moonrise, moon phase) for a place and date, and explicitly distinguishes itself from satellite_passes. An agent can tell exactly what this returns 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?

Names the alternative (satellite_passes) for orbital-pass queries, giving an explicit routing rule. However, it offers no other when/when-not guidance (e.g. astronomical vs. weather-based needs), so it falls just 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.