Vigi-Sky

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

Annotations already establish that this is a read-only, idempotent, non-destructive, closed-world operation. The description adds useful context by identifying the local simulation model and citing Collins et al. 2005, and reinforces that no network call is made, though it does not discuss computational cost or 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?

The description is compact and front-loaded: it starts with the core simulation purpose, then covers expected outputs, use-case routing, and local execution. Every sentence contributes useful information without redundancy.

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?

Given the rich input schema, annotations, and existing output schema, the description provides sufficient context for an agent to select and invoke the tool correctly. It explains the tool's purpose, scope, alternative, and local behavior without needing to restate return-value details.

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

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

Schema description coverage is 100%, so all six parameters are already well documented in the input schema, including presets, ranges, defaults, and physical meanings. The description itself does not add parameter-specific guidance beyond the schema, so the baseline of 3 is appropriate.

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 ('Simulate') and resource ('asteroid impact'), then enumerates the key outputs such as energy, air burst or crater, blast/heat/earthquake radii, local effects, and impact frequency. It also distinguishes this simulator from the real-time asteroid sibling by naming neo_watch.

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 explicitly states the intended use case ('what if' questions) and names the alternative for a different use case: 'for real asteroids passing today use neo_watch.' This gives clear routing guidance between related tools.

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 readOnly/idempotent/openWorld annotations, the description discloses the data source (NOAA SWPC via Vigi-Sky), a 2-minute cache TTL, and two explicit model limits (clouds and light pollution not modelled). That is real behavioral context; only the response shape is left unstated, which the output schema covers.

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

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

Front-loaded with what is returned, then usage routing, then data provenance and caveats — a sensible order with no filler. It is a single dense paragraph whose parenthetical France example is long but genuinely illustrative rather than 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 annotations covering the safety profile, an output schema present, and full parameter documentation, the description supplies the remaining essentials: scope, alternatives, data source, cache, and known non-modelled factors. Only edge-case behavior (e.g. polar latitudes or how borderline Kp is reported) is unaddressed.

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%, including lat/lon ranges and the lon/lng alias note, so the baseline is 3. The description adds a useful interpretation of latitude via the France Kp-by-region example, but says nothing about how lng or lang affect the result beyond what the schema already documents.

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 two concrete outputs (current Kp index and aurora visibility for a latitude), plus the local Kp threshold needed. It is clearly distinguishable from sibling tools like solar, moon, or tonight_sky 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 an explicit triggering question ('can I see the aurora tonight') and names two alternatives with the conditions that select them: solar for CMEs, tonight_sky for a full night summary. Nothing 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?

Adds real context beyond annotations: it discloses that personal data is erased (the concrete meaning of destructiveHint) and that a submitted report is out of scope. 'Repeating the call is harmless' restates idempotentHint but in actionable language; nothing is said about irreversibility or error behavior for a missing draft id.

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

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

Three short sentences, front-loaded with the core action and its consequence, then usage, then idempotency. No filler.

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

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

Output schema and annotations already cover return values, destructiveness, and idempotency, and the description fills in scope and the data-erasure effect. Minor gaps remain on what happens with a stale or already-cancelled draft id.

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 (jeton, action_id) are documented as coming from draft_sighting_report, so the description adds nothing param-specific. 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 (cancel a draft) plus the key side effect (erase personal data). It immediately distinguishes itself from submit_sighting_report by noting a submitted report cannot be cancelled here.

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 trigger condition (witness declines or changes their mind after draft_sighting_report) and an explicit exclusion (submitted reports). The alternative path is implied through the named sibling, so the agent knows when to route 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 openWorld=false. The description adds useful context beyond that: it is a static description with no network call, and it clarifies that this server cannot access local files or a camera. That helps prevent incorrect invocation, though it does not add much more behavioral depth.

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, followed by routing guidance and a key behavioral note. It is efficient overall, though the second sentence is long and packs several clauses; it still earns its place by clarifying server boundaries.

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 static, zero-parameter capabilities tool with an output schema, the description is complete: it explains what the tool describes, when to use it, when not to use it, and that no network call occurs. An agent has everything needed to select and invoke 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?

The tool has zero parameters, so there is nothing parameter-level to document. The schema is empty and fully covered; the baseline for a no-parameter tool is 4, and no additional parameter semantics are needed or missing.

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: it describes what the public server offers and what the separate local VigiSky Sentinel server adds (photo/video analysis, night watch, star-field solving). It also explicitly distinguishes itself from sibling tools by directing sky questions to what_did_i_see, iss_city_passes, aurora, etc.

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 when-to-use guidance ('when a task needs local files or a camera') and explicit when-not guidance ('for sky questions this server answers directly, call the matching tool'), naming alternatives. The boundary between this server and the local server is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld=false, so the safety profile is covered. The description still adds useful mechanism: keyword match over a fixed page catalogue and no network call, which reinforces the closed-world behaviour and explains latency/consistency expectations.

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

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

Three sentences, front-loaded with the mapping action, then usage, then mechanism. No filler; each clause carries 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?

An output schema exists, so return values need no explanation. For a two-parameter, read-only lookup, the description covers scope, exclusions, sibling routing and matching mechanism completely.

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 the query example and the lang enum (fr default / en) are already documented in the schema. The description adds nothing about lang and only restates that the query can be French or English, 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?

States a specific verb and resource: map a user question to the single best Vigi-Sky page (or the official GEIPAN page) to cite, plus that alternatives are returned. It clearly distinguishes itself from the live-data siblings it names (aurora, iss_city_passes, what_did_i_see).

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 the trigger ('when you need a URL to back an answer') and an explicit exclusion ('it does not answer the question itself, so call the matching tool ... for live data'), naming the alternative tools to route to.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-obvious context: the counts are fixed at release and therefore stale by design, which is the key behavioral trait an agent must know to avoid misreporting figures. It stops short of describing the returned structure, but an output schema exists.

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?

Two sentences, zero waste: the first front-loads what is returned, the second front-loads the usage rule and the routing to status and cite. The content list is dense but every item is a distinct payload field the agent would otherwise have to discover.

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 static read-only identity tool with an output schema, the description covers purpose, the staleness caveat, and both competing siblings. There is no gap an agent would need filled before calling 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?

One optional parameter (lang) with 100% schema description coverage including the enum and the fr default, so the schema fully carries parameter meaning. The description says nothing about language selection, so it adds no value beyond the schema — 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 (Return) and a precisely scoped resource (Vigi-Sky's identity card and method rules), then enumerates the exact contents: founder, launch date, the book, the 'never UFO detected' rule, and the archive-vs-own-cases distinction. This is unmistakably different from siblings like hatch_stats, status, or cite.

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 an explicit trigger ('Use it before describing Vigi-Sky or explaining its method') and names two alternatives with the conditions that select them: status for current numbers and API health, cite for a page to cite. Nothing 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 already say non-readOnly, non-destructive, non-idempotent; the description adds what actually happens: nothing is published, a summary/draft id/secret token are returned, and the immediate explanation appears when place and time are supplied. Expiry and rate limits are disclosed, which annotations cannot convey.

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

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

One tight paragraph, front-loaded with 'Step 1 of 2' and the no-publish guarantee, followed by outputs, then the branching next step and limits. Every sentence carries 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, yet the description still names the key returned artifacts (summary, draft id, secret token) briefly. The consent/approval workflow, alternatives, and rate limits are all present, so an agent can complete the two-step flow without guessing.

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 a real behavioral link by noting that place and time parameters trigger the immediate explanation in the response. It does not re-explain individual fields, which is appropriate given 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 ('prepare a draft report of something seen in the sky') and immediately scopes it as non-publishing. The 'step 1 of 2' framing distinguishes it from submit_sighting_report and cancel_sighting_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?

Explicit sequencing: draft now, then call submit_sighting_report only after the witness explicitly agrees, otherwise cancel_sighting_report. Adds operational limits (10-minute expiry, 5 drafts per client per hour) that tell the agent when to reuse vs. redraft.

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 closed-world behavior, so the bar is lower. The description adds useful behavioral context beyond annotations: it is a local calculation with no network call, it cites the underlying model (Sandberg, Drexler & Ord 2018), and it explains that unset factors fall back to preset or default values.

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

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

The description is front-loaded with the core computation, then immediately handles usage and alternatives, then closes with fallback and execution details. Every sentence adds distinct information with no filler.

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

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

An output schema exists, so return values do not need full explanation. Given that, the description covers purpose, when to use it, what not to use it for, the alternative sibling tool, default-filling behavior, and local/no-network execution. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already defines each factor's meaning and bounds. The description adds value by explaining the relationship between factors, presets, and defaults: 'from your factors or a preset' and 'Unset factors take the preset or default values.' This clarifies optional-parameter behavior 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 states a specific verb and resource: 'Compute the Drake equation N (detectable civilisations in the Milky Way)... and the probability that we are alone.' It also explicitly distinguishes itself from the sibling what_did_i_see, so an agent can tell it apart without inspecting 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 gives explicit usage guidance: 'Use it for 'are we alone' and Fermi-paradox questions; it says nothing about UFO sightings (for a light in the sky use what_did_i_see).' This names both the appropriate use case and the alternative tool for adjacent questions.

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 closed-world, so the safety profile is covered. The description adds genuinely useful context beyond that: 'Computed locally, no network call' (latency/offline behavior) and the fact that contact times are returned in local time and include Sun height, which affects how the agent should interpret results. It does not cover failure behavior for unknown cities or out-of-path coordinates.

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

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

Three dense sentences, front-loaded with the verb and resource, then scope, then input forms and the offline-compute note. No sentence is redundant and nothing important is buried.

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?

The tool has rich annotations, full schema coverage and an output schema, so the description only needs to cover scope and input framing, which it does completely. Geographic coverage, eclipse-specific scope, input alternatives and local computation are all stated; return values are handled by the output schema.

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 still adds meaning by framing the input choice ('Give a city (830 known) or coordinates') and disclosing the finite 830-city gazetteer, a real constraint not visible in the schema. The remaining alias and enum details are already fully 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 and resource ('Compute the total solar eclipse of 2 August 2027 at a place') and enumerates the outputs (totality/partial, magnitude, contact times, duration, Sun height), so the agent knows exactly what it gets. It scopes itself to one eclipse ('Use it for that eclipse only') but never names a sibling such as solar or sky_events, so the differentiation is implicit rather than 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?

'Use it for that eclipse only' plus the geographic description (total from Spain/Morocco to Egypt, Saudi Arabia, Yemen; partial over Europe) tells the agent when this tool is relevant versus a general sun/sky tool. 'Give a city (830 known) or coordinates' gives clear input-selection guidance. It does not explicitly state when NOT to use it or name a fallback tool for other eclipses.

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?

Adds context beyond the annotations: 'local curated data, no network call' reinforces openWorldHint=false, and 'attested versus interpreted or kept private' discloses data-provenance and privacy semantics the agent cannot infer from structured fields. It stops short of describing result volume or pagination, but with an output schema present that is a minor gap.

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

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

Front-loaded with the resource and content, then filtering, then sibling routing — no filler sentences. The semicolon-chained second sentence is dense and slightly run-on, but every clause carries 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 8 optional parameters, full schema coverage, annotations, and an output schema, the description supplies exactly the missing layer: what the dataset contains, what the filters mean, and which sibling to use instead. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3; the description goes further by naming the filtering intents (nation, western constellation for cross-cultural comparison, theme, free text) and clarifying that lat answers 'which objects never rise there'. That adds interpretive meaning beyond the field descriptions, especially for lat and western.

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 ('Query Ciel des peuples') and enumerates the content returned: asterisms, coordinates, sources, and attestation status across 9 named nations. It explicitly contrasts itself with tonight_sky, so an agent can distinguish it from siblings 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?

Gives explicit when-to-use ('cultural astronomy') and when-not ('for what is in the sky tonight use tonight_sky'), plus the four filtering axes and the special purpose of lat. The routing decision is fully determined.

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

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

Annotations already declare readOnly, idempotent, non-destructive and openWorld, so the safety profile is covered. The description still adds meaningful context beyond them: the data provenance (archival 1900-2002 corpus, not live 2026 sightings) and that it is a live read of the Vigi-Sky API, which implies availability/latency dependence. It stops short of stating rate limits or failure behavior, so not a 5.

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

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

Three short clauses, front-loaded with what is returned and its scope, followed by the routing hint and the data-provenance caveat. Every sentence carries information an agent needs; nothing is repeated from the schema or 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?

An output schema exists, so return shape needn't be described, and the description already names the two aggregate dimensions (by decade, top countries). Combined with the corpus size, date range, provenance caveat and sibling routing, nothing material is missing for a zero-parameter read 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?

The tool takes no parameters, so the baseline is 4 and there is nothing for the description to disambiguate. It does not, and need not, explain inputs.

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

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

States a specific verb and resource plus exact scope: aggregate statistics of the Hatch UFO archive, 18,116 cases from 1900-2002, broken down by decade and top countries. It explicitly separates itself from the sibling nearby_cases, so an agent can choose 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?

"Use it for the big picture of historical reports; for cases near a place use nearby_cases" gives an explicit when-to-use plus the named alternative and its selection condition. "Archive data, not 2026 sightings" adds a clear exclusion so the agent does not mistake it for current sighting data.

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 closed-world; the description reinforces the last point with 'computed locally, no network call' and 'exact formulas', which sets the expectation of deterministic, precise numeric output. It does not describe error behavior when zero or multiple mass inputs are supplied, which is the one genuinely useful disclosure missing.

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?

Two sentences: outputs first, then usage and the one-of constraint. Zero filler and nothing important is buried.

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, the description need not explain return values, and it already names the four computed quantities at a summary level. Combined with full schema coverage and annotation-backed safety profile, an agent has everything needed 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 baseline is 3, but the description adds a real constraint the schema does not express: the schema marks nothing as required, yet the tool needs exactly one mass input. That one-of rule is genuinely new information for correct invocation.

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 ('compute') and resource ('black hole of any mass') and enumerates exactly what is returned: event-horizon radius, Hawking temperature, entropy, evaporation time. It is clearly distinguishable from astronomy siblings like asteroid_impact or drake_equation.

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?

'Use it for physics questions about black holes' gives clear usage context, and the selection rule ('give exactly one of mass_kg, mass_solar or preset') covers the main invocation ambiguity. No explicit when-not or named alternative, but no sibling plausibly competes for this task, so the gap is minor.

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 adds real behavioral context beyond them: the insufficient_data failure mode when orbital elements exceed 72 hours, the epistemic caveat that a match is 'compatible with the observation, not proven', and the explicit note that it never claims 'UFO detected'. These are non-obvious traits 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?

Three sentences, front-loaded with the core matching behavior, then usage routing, then caveats. No filler; every clause carries information an agent would otherwise have to guess.

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?

Output schema exists so return values needn't be explained, and the description still covers the key interpretive point (match = compatible, not proof) and the degraded-data failure case. Nothing essential for correct invocation is missing.

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

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

Schema coverage is 100%, so az, el, lat, lon/lng, time and lang are all documented in the schema itself. The description restates 'azimuth, elevation and exact time' but adds no format or constraint 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 and resource ('check whether a precisely measured point in the sky ... matches one of about 160 bright satellites and rocket bodies') with concrete scope (2 degrees for satellites, 5 degrees for planets/Moon/stars). This is clearly distinguishable from which_star and what_did_i_see, which are named.

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 when to use it ('when the witness measured the direction (compass, phone app)') and routes two alternatives: what_did_i_see for vague memory, which_star for a fixed star or planet. Both the positive condition and the exclusions are 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?

Goes well beyond the readOnly/idempotent annotations by disclosing data freshness (precomputed every few hours by Vigi-Sky), the degraded-precision path for lat/lon, and the side artifact produced (calendar feed with a 10-minute alarm). Missing only a note on latency/staleness bounds for the precomputed passes, which keeps it from a 5.

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

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

Three sentences, each carrying distinct load: capability, routing rule, and data provenance. The A-to-B contrast with iss_passes is placed early where it matters most for routing.

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?

Output schema exists, so return values need no explanation; annotations cover the safety profile. With zero required parameters, the remaining risk — the agent assuming worldwide coverage or fresh computation — is exactly what the description preempts.

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 earns above that by adding meaning the schema cannot express — that lat/lon is a fallback snapping to the nearest covered city, and that city must be one of a bounded, enumerated set. It does not mention the lang parameter, but the schema already handles 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 and resource ('Give the next naked-eye passes of the ISS (and Tiangong)') plus a precise scope (41 cities across five countries). It explicitly contrasts itself with the sibling iss_passes, 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?

Gives explicit selection criteria: use when the user names a city or wants an alert; use iss_passes for other coordinates. It also covers the in-between case (arbitrary lat/lon snaps to the nearest covered city), eliminating the main ambiguity an agent would face.

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/openWorld/idempotent/non-destructive, and the description adds real context on top: the default filters to naked-eye-visible passes (dark sky, satellite sunlit), ISS is ordered first, elements are cached 10 minutes from the Vigi-Sky API. It stops short of covering edge behavior such as an empty result when no pass qualifies.

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?

Four sentences, front-loaded with the capability and routing before implementation detail. Slight redundancy between 'computed with SGP4 from current orbital elements' and the closing 'Orbital elements come from the Vigi-Sky API (cached 10 minutes)' 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 an output schema present, return values need no explanation, and all seven parameters are fully documented. The description covers what it does, defaults, data provenance and freshness, and sibling alternatives — nothing an agent needs in order to call 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% and each parameter is already documented including defaults and aliases. The description only reinforces the night_only default ('by default only passes visible to the naked eye') and result ordering, adding no syntax or format detail 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 and resource ('List the next passes of the ISS and other bright satellites') plus the required inputs (latitude/longitude) and the computation method (SGP4). It explicitly distinguishes itself from the two nearest siblings, so an agent can pick it 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?

Gives an explicit use case ('arbitrary coordinates') and names both alternatives with the conditions that select them: iss_city_passes for a named European city with a calendar feed, what_did_i_see for explaining an already-seen object. Exclusion and routing are unambiguous.

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 establish read-only, closed-world, idempotent behavior, so the bar is lower. The description still adds genuinely new context: computed locally via Meeus, accurate to about 0.5 hour of JPL ephemerides, and no network call — useful for judging trustworthiness and latency instead of repeating safety hints.

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

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

Three tight clauses: what it returns, when to use it versus the sibling, and how it is computed. Capability and routing come first, with provenance last — no filler.

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

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

With an output schema present, the description needn't explain return shape, and it covers scope, alternative routing, and computation fidelity. Only minor gaps remain, such as whether the "what it means for observing faint objects" narrative text is localized by `lang`.

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%, with both `time` (ISO-8601, default now, years 1900-2200) and `lang` (fr/en, fr default) fully documented. The description only restates the "default now" behavior and adds nothing about the language switch or accepted date range, 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?

Uses a specific verb and resource ("Return the Moon's phase and illuminated percentage") and enumerates the extra outputs — next full/new Moon and its impact on observing faint objects. This is clearly distinct from siblings like solar, sky_events or observation_conditions.

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 states the trigger ("Use it for Moon questions") and routes the agent elsewhere when the question is broader: "for an overall observing score use observation_conditions." The named alternative makes the boundary unambiguous.

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 beyond the annotations (readOnly, openWorld, idempotent) by disclosing the failure mode: it returns available=false rather than fabricating a picture when NASA hasn't answered, which tells the agent how to handle an empty response. It also notes the live-API dependency and the fixed one-per-day cadence, though it says nothing about latency, caching, or rate limits.

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

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

Three tight sentences ordered by importance: what it returns, scope, routing to alternatives, then the failure behavior. No filler and nothing repeated from the title beyond what's needed for field enumeration.

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 zero-parameter, read-only lookup with an output schema and full annotation coverage, the description supplies everything else an agent needs: scope, sibling routing, and the degraded-response contract. 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?

The tool takes zero parameters, so the baseline is 4. The description still adds value by pre-empting the obvious wrong assumption — that a date could be supplied — with "today only, no past dates."

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 ("Return today's NASA Astronomy Picture of the Day") and immediately bounds scope with "today only, no past dates," plus enumerates the returned fields. An agent can distinguish it from solar or neo_watch without opening the schema.

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

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

Gives an affirmative use case ("Use it to share today's picture") and explicitly routes two adjacent needs to named siblings: "for the Sun's activity use solar, for asteroids near Earth use neo_watch." The today-only constraint also acts as an implicit when-not rule for historical queries.

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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds genuine context beyond that: the archive's provenance and date range, approximate geocoding, and the non-obvious radius defaults (50 km, 200 km when filtering). It doesn't mention pagination or result limits, which keeps it short of a 5.

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

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

Three compact sentences with the core purpose front-loaded and the exclusion plus radius caveat trailing. 'Read-only query of the Vigi-Sky API' slightly duplicates the readOnlyHint annotation, a minor redundancy in an otherwise tight 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?

With a full output schema, rich annotations, and 100% parameter coverage, the description only needs to supply scope, alternative routing, and data-quality caveats — and it does all three. Nothing required to call this 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 description coverage is 100%, so the schema already documents lat/lng/lon aliasing, the lang enum, country format, and the radius_km default logic. The description restates the default-radius behaviour rather than adding new semantics, so the baseline 3 is appropriate.

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 historical UFO/UAP reports from the Hatch UDB archive (1900-2002)' — plus the spatial scoping ('near a point') and optional filters. It is immediately distinguishable from sibling tools like sky_events and hatch_stats.

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: 'Use it for the history of a region' and 'it is not a live feed of recent sightings (use sky_events)'. It also warns that geocoding is approximate, which is a real usage caveat an agent needs before trusting radius results.

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 provenance: live NASA NeoWs data via Vigi-Sky, and the fact that results are scoped to 'today'. It does not mention behavior when no approaches occur or any rate/latency characteristics, which keeps it below a 5.

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

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

Three short sentences, front-loaded with the verb and scope, then usage/routing, then domain disambiguation. The parenthetical field list is mildly redundant with the output schema but is short enough to earn its place as a preview.

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?

A zero-parameter read tool with a full output schema and comprehensive annotations needs only scope, source, and routing guidance — all present. Nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline applies. The description correctly implies there is nothing to supply, matching 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?

Specific verb ('List') plus a precisely scoped resource ('today's near-Earth asteroid close approaches') and named data source (NASA NeoWs), with the returned fields enumerated. It also pre-emptively separates itself from the sibling asteroid_impact, 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?

Gives an explicit trigger phrase ('which asteroids pass near Earth today') and names the alternative tool with the condition that selects it ('to simulate an impact use asteroid_impact'). It further excludes an adjacent domain ('Astronomy, not UAP'), steering the agent away from the sighting/identify siblings.

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, openWorld), yet the description adds real context: the data source is the live Vigi-Sky API and clouds are excluded from the score. The exclusion is the key behavioral caveat an agent needs. It stops short of describing latency, error behavior, or how the score is scaled, which keeps it from a 5.

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

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

Front-loaded with purpose and decision guidance, then alternatives, then caveats, in four short clauses. The UFO remark is slightly jokey but does disambiguation work against the sighting-report siblings, so it is not pure waste. A touch of personality costs it the top score.

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

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

An output schema exists, so return-value detail is unnecessary. With full parameter coverage in the schema, the description supplies the remaining essentials: what drives the score, the external API source, the cloud exclusion, and which siblings to prefer.

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%, including the lat/lng/lon alias rule and enum values for lang, so the schema does the heavy lifting. The description only implies the latitude input ('at a latitude right now') and adds nothing about the optional longitude or language parameters. 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 and resource ('return a score of how good the sky is for observing') plus the temporal scope ('right now') and the scoring inputs (night, Moon, quiet Sun). It also names the sibling tools it is not (moon, aurora), so an agent can separate it from nearby tools 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 an explicit decision context ('use it to decide whether to go out') and routes to alternatives by condition: 'For the Moon alone use moon, for aurora use aurora.' It also sets a negative expectation ('not a probability of seeing a UFO'), steering agents away from sighting-report tools.

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, closed-world, non-destructive), so the description's job is to add context. It adds two useful traits: the response carries no personal data, and the counters break down by status alongside per-client and overall limits — behavior an agent would not infer from the annotations alone.

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?

Two sentences, zero filler. The output shape is front-loaded and the usage trigger follows immediately, so an agent scanning the first clause knows what it gets.

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 zero-parameter, read-only counter tool with an output schema already present, nothing is missing: purpose, scope exclusion, and the failure condition that motivates a call are all stated. Return-value details are correctly left to the output schema.

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 there is nothing for the description to disambiguate; the baseline of 4 applies. The description correctly does not waste words describing absent inputs.

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

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

States a specific verb+resource ('return the number of sighting-report drafts by status and the limits that apply') with grouping (per client and overall) and an explicit exclusion ('no personal data'). This is unambiguous and clearly distinct from the sibling draft_sighting_report and submit_sighting_report, which mutate state.

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 an explicit trigger for use — 'when draft_sighting_report or submit_sighting_report refused because of a limit' — naming the exact sibling tools that route here. It does not state when not to call it, but the trigger is narrow enough that misuse is unlikely.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, and the description adds real context beyond them: a 48-hour prediction horizon, the verdict taxonomy (compatible / contradicted / untestable / under review), and a privacy guarantee ('public data only, no personal information'). It stops short of describing result volume or ordering, but the output schema covers return shape.

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?

Two dense sentences followed by a short privacy clause; the scope and time window are front-loaded and the sibling routing follows immediately. Nothing is repeated from the title and no sentence is filler.

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

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

For a zero-required-parameter list tool with a full output schema and complete annotations, the description supplies everything an agent needs to pick it: scope, time window, content taxonomy, privacy posture, and explicit alternatives. Return values are correctly left to the output schema.

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% with clear enum descriptions for kind and lang, so the schema does the heavy lifting. The description's framing of the two event families implies what 'prevu' vs 'signale' return, but it adds no syntax, defaults, or guidance for lang/limit — 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 and resource ('List Vigi-Sky's sky events') plus the two concrete content types — predicted ISS/Starlink passes for the next 48 hours and clustered witness reports with verdict classifications. It immediately distinguishes itself from the adjacent pass-lookup and sighting-identification siblings.

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

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

Gives an explicit selection rule ('Use it for what happened or will happen in the sky') and names both alternatives with the condition that routes to each: iss_city_passes for one city's passes, what_did_i_see for one past sighting. No inference required.

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, non-destructive behavior. The description adds useful operational context beyond annotations: live data via Vigi-Sky API, 5-minute caching, and explicit 'unavailable' degradation when NASA does not answer.

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

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

Three sentences, each serving a distinct purpose: what it returns, when to use it versus a sibling, and how it behaves under caching/failure. Front-loaded and zero waste.

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 and full annotations present, the description provides the remaining context an agent needs: data source, cache duration, and failure mode. Nothing essential for selecting or invoking this no-argument 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?

There are zero parameters, so the baseline is 4. The description does not need to explain parameter semantics and appropriately focuses on purpose and behavior instead.

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 resources: returns recent CMEs and current Kp index. It clearly distinguishes this tool from the aurora sibling by explaining that aurora applies the latitude threshold.

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 use cases: explaining an aurora alert or space weather. It also names the alternative tool and the exact condition for choosing it: 'can I see the aurora from here' should use aurora.

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 declare read-only, idempotent, open-world, non-destructive behavior, so the safety profile is covered. The description's genuinely additive detail is the caching window ('cached 30 seconds to 2 minutes'), which tells the agent figures may be stale — useful, but no mention of which values live vs. cached, rate limits, or error 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?

Two sentences, front-loaded with what is returned, then when to use it. No filler, and the caching note is appended compactly rather than as a separate 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?

A zero-argument status tool with an output schema, so return-shape explanation is unnecessary, and the freshness caveat plus error-recovery guidance covers what an agent needs. Nothing required for correct invocation is missing.

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

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

The tool takes no parameters, so the baseline is 4; there is nothing for the description to disambiguate. The enumeration of what comes back is helpful orientation even though the output schema already defines 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 ('Return') and enumerates the exact resources returned: API health, Hatch archive size, public observation count. It is clearly distinct from most siblings, though it never distinguishes itself from hatch_stats, which likely overlaps on archive figures.

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 two concrete triggering conditions ('before quoting live counts' and 'when another tool returned an error') and routes a different need (identity and method) to the named sibling doctrine. An agent knows both when to call this and where to go instead.

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 annotations by disclosing rate limits (3 per client per day, 30 overall), the one-submission-per-draft rule, and exactly which fields get published plus the privacy guarantee that email is never published. Missing only what an error or a rejected submission returns, though the output schema covers return shape.

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 step label and action, then consent precondition, then publication/limit facts. Three dense sentences with no filler; each clause carries operational meaning.

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

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

Given an output schema exists, the description need not explain returns, and it fills the remaining gaps: consent workflow, draft provenance, published vs. private fields, and quota limits. That is everything an agent needs before invoking a non-idempotent, open-world publish action.

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 are documented there as items returned by draft_sighting_report. The description mentions the token/draft dependency only indirectly ("draft prepared by draft_sighting_report"), so it adds little 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 (send/submit a draft) and resource (a drafted sighting report to the Vigi-Sky Witness station), and positions itself explicitly as "step 2 of 2" relative to draft_sighting_report. An agent can immediately separate this from drafting or cancelling siblings.

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

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

Explicit precondition: call only after showing the summary and obtaining the witness's explicit agreement, and only for a draft produced by draft_sighting_report. The presence of sibling tools like cancel_sighting_report and sighting_report_limits is implicitly handled by naming the draft dependency and the limits inline.

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, open-world, non-destructive, so the safety bar is low; the description adds that results combine live Vigi-Sky API data and that daylight passes are excluded by default, plus a scope boundary ('Not a UFO forecast'). Slight redundancy with the night_only default documented in the schema keeps it from a 5, and it doesn't mention latency or data freshness.

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

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

Three compact sentences, front-loaded with what it returns, followed by routing guidance, then a scope caveat. Every clause earns its place, including the closing 'Not a UFO forecast' which steers agents away from the sighting-report siblings.

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 needn't be spelled out, and the description covers content, data source, defaults, and alternative tools. For an aggregate read-only overview tool, nothing an agent needs in order to call it correctly is missing.

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

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

Schema description coverage is 100%, including the lon/lng alias note and the night_only default, so the schema carries parameter meaning. The description only restates the daylight-pass default and implies a location ('at a place') without adding format, alias, or fallback guidance beyond the schema — baseline 3.

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 ('One-call summary of tonight at a place') and enumerates the exact contents returned: aurora Kp chances, next naked-eye satellite pass, cultural asterisms. This makes it immediately distinguishable from siblings like aurora, iss_passes, or observation_conditions, which each cover only one slice.

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 selection condition explicitly ('Use it for an overview') and names three alternatives for detail (aurora, iss_passes, first_skies) plus a fourth for a different need (observation_conditions for observing scores). An agent has a complete routing decision without inference.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, but the description still adds real context: the computation is local geometry with no network call, the range accounts for typical compass errors, and the output is explicitly "a candidate, never a proof." That uncertainty framing is the kind of disclosure annotations cannot carry; only the error/edge-case behavior for bad sightings is left unstated.

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?

Two dense sentences: capability and witness constraint first, routing to alternatives second, caveats last. No filler, no restatement of the title.

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 and annotations carrying the safety profile, the description supplies exactly the missing pieces: when to call it, the witness-count requirement, the local-computation fact, and the epistemic caveat on results.

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 conceptual meaning by mapping the parameters to "each witness's position and line of sight," clarifying that lat/lon are standpoints and az/el are measurements, and it explains why 2-6 items (compass error tolerance).

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 output ("Estimate the height and distance of one object") plus the hard constraint of 2 to 6 witnesses, then names the sibling tools (identify, what_did_i_see) it is not. An agent can separate it from the other sighting-related tools 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 an explicit inclusion rule ("only when several people measured the same object at the same time") and an explicit exclusion routing to alternatives for the single-witness case. The minimum-witness condition is stated twice, so there is nothing left to infer.

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 readOnly/idempotent/openWorld annotations, it discloses the ±12 minute matching window, the temporal limits, the excluded object families, and the crucial epistemic caveat that a match means 'compatible with the observation, not proven' and that the tool never asserts 'UFO detected'. That caveat directly shapes how an agent should relay results.

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 in the opening clause, followed by routing, scope limits, and the caveat in descending priority. It is dense but every clause carries distinct information — no restatement of the name or title.

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, open-world candidate-ranking tool with an output schema already covering return values, the description supplies everything an agent needs: what it compares, when to prefer it, its temporal window, its blind spots, and how to interpret a match.

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 parameters like lat/lng/time/az/moving are already fully documented, establishing a baseline of 3. The description adds only mild framing — that az/elevation precision is what separates this tool from identify — and does not add format or alias guidance beyond the schema (e.g. lon/lng aliasing is schema-only).

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 ('Explain a light someone saw') and immediately enumerates the comparison set — ISS, Tiangong, ~160 bright satellites, planets, Moon, bright stars — plus the ranking behavior. It explicitly names the siblings it is not (identify, which_star), so an agent can route 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 an explicit selection rule: 'Use it for an imprecise memory; with a measured azimuth and elevation use identify, for a steady point use which_star.' It also bounds the applicable regime (up to 10 days back, 2 days ahead) and lists what is out of scope (aircraft, drones, lanterns, meteors).

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 this is a read-only, idempotent, non-destructive, open-world lookup. The description adds meaningful behavioral limits beyond the schema: the 15-degree match radius, the brightness threshold, and that refraction near the horizon is not modelled.

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 action and scope, then immediately gives alternatives and limitations. Every sentence carries useful selection or behavior information with no filler.

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

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

With an output schema available and rich annotations, the description does not need to explain return values or safety. It covers the key operational constraints: 15-degree matching, bright-object limitation, and unmodelled horizon refraction.

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 azimuth, elevation, latitude, longitude aliases, language, and time are already well documented in the input schema. The description mentions direction and place/time but adds no parameter-level detail 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 states a specific verb ("Name") and resource ("bright star, planet or Moon") plus scope (closest to a direction, within 15 degrees). It clearly distinguishes this tool from siblings by naming what_did_i_see for moved objects and identify for precise satellite matches.

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 explicitly says when to use this tool (steady point of light) and when to use alternatives (what_did_i_see for movement, identify for precise satellite matching). It also gives a key exclusion: bright objects only, about magnitude 1.5 or brighter.

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