Perigee-mcp

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

Annotations already declare readOnlyHint and openWorldHint, and the description adds real content: it enumerates exactly what the response will contain, including fetch timestamps, typical accuracy, catalogue sizes, reference frame, attribution and an educational-use disclaimer. Since there is no output schema, this enumeration is the main disclosure of return content and it does that job well, though it says nothing about format or size.

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

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

A single front-loaded sentence with no filler; the colon-list packs in all the relevant content categories efficiently. It is slightly dense/listy, but nothing is wasted.

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-argument, read-only reference tool with no output schema, the description covers what an agent needs: what information is returned and why it matters (provenance, accuracy, attribution, disclaimer). Only minor gaps remain around response shape and whether the content is static or timestamp-dependent.

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 correctly implies no input is needed to retrieve this static reference information.

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

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

The description makes clear this is a metadata/provenance endpoint: 'data sources and when they were fetched, the models and their typical accuracy, catalogue sizes, frame, attribution...'. That distinguishes it from the computational siblings (perigee_orbit, perigee_passes, etc.) which return derived results rather than source documentation. It is framed as content ('what every answer rests on') rather than as a verb like 'returns', which keeps it just short of a 5.

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

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

Use is only implied: an agent can infer it should call this when it needs to cite provenance, accuracy caveats, or attribution. There is no explicit 'call this when...' or 'do not use for X' guidance, and no alternative is named, which is acceptable given no sibling overlaps in scope.

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 and open-world behavior, so the description's added value is in the precision and output-shape disclosure: timing 'to a fraction of a second', relative velocity only for two Earth satellites, and a hard warning that public orbits are unsuitable for collision avoidance with the response itself carrying that disclaimer. That is meaningful context beyond the annotations, though it says nothing about failure modes for non-satellite or non-Earth object pairs.

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

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

A compact two-sentence definition that front-loads what is computed and what is returned before the caveat. The trailing 'and the answer says so' is slightly awkward but does convey a real behavioral fact rather than padding.

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 six parameters, no output schema, and a numerically sensitive computation, the description does the important work: it names the three returned quantities, bounds the time window, and flags the accuracy limitation. What is missing is only the treatment of edge cases (e.g., objects that never approach, non-Earth objects), which is minor given full schema coverage.

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 (from, to, days, start, time_zone, lang) are already documented structurally. The description's '(default 1 day, at most 1)' merely restates the days parameter's schema default and maximum, adding no new syntax or interpretation guidance.

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

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

The description uses a specific verb+resource framing — the minimum distance between two objects over a time window — and lists the returned quantities (time of closest approach, distance, relative velocity). It is clearly a closest-approach computation rather than an instantaneous distance, but it never names the sibling tools (perigee_distance, perigee_distance_series) it is distinguished from.

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?

Usage context is implied by 'over a period (default 1 day, at most 1)' and by the education-only caveat, which tells the agent the precision regime this tool operates in. However, there is no explicit 'use this instead of X when Y' guidance against the many distance/orbit siblings, so selection still requires 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 readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds only the list-all fallback behavior; it says nothing about return format (a list vs. a single definition) or size 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?

One compact sentence with a parenthetical qualifier; the audience level and term list are front-loaded and the fallback behavior closes it out. Slightly dense but nothing is wasted.

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

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

For a two-parameter read-only lookup with no output schema, the description covers purpose, audience, and the zero-arg case. Only the return shape and language handling remain unstated, and the latter is in the 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 50%: 'lang' is documented in the schema but 'term' carries no schema description and is only implicitly explained by the description's list-all behavior. The description never mentions language selection, leaving the enum to the schema alone.

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

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

States a specific resource (student-level definitions of orbital terms) and enumerates representative entries, so an agent can immediately tell this glossary lookup apart from the calculation tools in the sibling list (perigee_orbit, perigee_distance, 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?

Explicitly states the no-argument behavior: 'Without a term, lists them all,' which gives a clear call pattern. It does not name alternatives, but no sibling offers definitions, so that 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so the description does not need to repeat safety basics. It adds useful behavioral context by enumerating what the generated description includes and by disclosing the limitation that 'The camera framing is not in the link.'

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 transformation and has only two sentences. The long parenthetical list of encoded details is somewhat dense, but it earns its place because there is no output schema to document the return contents.

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

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

With no output schema, the description usefully explains the two returned text forms and enumerates the details included in the lesson-note description. It also notes a key limitation. Parameter details are covered by the schema, so the definition is largely complete for a read-only description 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%, so the schema already documents all three parameters, setting the baseline at 3. The description adds meaning about what the URL encodes and what it does not encode, but it does not expand on lang or time_zone beyond what the schema provides.

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 uses a specific transformation verb, 'Turns a Perigee link or embed URL ... into words,' and states the concrete outputs: one-sentence alternative text and lesson-note description. It references perigee_view as a source, which helps distinguish it from view-creation tools, though it does not explicitly distinguish itself from all 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?

Usage is implied by the stated outputs: generating alt text for an image or iframe and descriptions for lesson notes. The description mentions links from perigee_view or shared links, but gives no explicit when-to-use/when-not-to-use guidance or named alternative 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 declare readOnlyHint=true and openWorldHint=true, so the safety profile is covered. The description adds useful return-payload context (km, AU, light travel time, provenance), but does not discuss data-source behavior, rate limits, or error handling.

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, with the core operation and output units stated first and a short example appended. There is no wasted language.

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

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

With no output schema, the description usefully explains the return values and provenance. However, it leaves gaps around accepted from/to values and when to choose this tool over distance_series, so it is adequate but not fully complete.

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 only 33%: date is documented in the schema, but from and to have no schema descriptions. The example clarifies that from and to are object names like 'earth' and 'mars', but it does not define accepted identifier formats or the full range of valid values.

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 clearly states it computes centre-to-centre distance between two objects at a date, with units and light travel time. It is specific, but does not explicitly distinguish itself from the sibling perigee_distance_series, which is implied only by the single-date framing.

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?

Usage is implied by the example and the 'at a date' phrasing, but the description gives no explicit when-to-use guidance, exclusions, or alternatives such as perigee_distance_series for time-series distances.

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 and openWorldHint, so safety is covered. The description adds real behavioral content — output includes closest and farthest samples, and step count trades off precision — but says nothing about output shape, timestamp granularity, or how many samples are returned.

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 tight sentences with the core purpose front-loaded and the precision caveat second. Nothing is wasted, though the parenthetical '(for a table or a chart)' is slightly weaker than the rest.

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

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

For a five-parameter tool with no output schema and partial schema coverage, the description covers what the series contains but not the sample count (steps vs steps+1), the format of from/to, or whether the closest/farthest samples are separate fields or derived. Adequate but with clear gaps.

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 60%: start/end and steps are documented in the schema, from/to are not. The description usefully implies from/to are the two objects and explains the precision effect of steps, but leaves the format of the object identifiers (name, NORAD ID, etc.) entirely unstated.

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

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

States a specific computation: distances between two objects sampled evenly over a period, with closest and farthest samples, and notes the table/chart use case. This implicitly distinguishes it from a single-shot perigee_distance or perigee_close_approach, but never names the sibling it replaces.

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

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

The phrase 'for a table or a chart' implies when the series form is appropriate, and the second sentence gives guidance on choosing steps. However, there is no explicit when-to-use vs perigee_distance / perigee_close_approach routing, which is the sibling decision an agent actually faces.

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?

With readOnlyHint and openWorldHint already supplied, the description adds useful behavior: the default 30-day window, the 31-day cap, the catalogue source, and the fact that eclipse results depend on a place. It does not discuss output structure or ordering, but the safety profile is already covered by annotations.

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

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

The description is front-loaded and contains no filler, with each clause naming a meaningful event family. It is one very long sentence, though, which makes it slightly less scannable than an ideally structured definition.

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 description covers event categories well and links location to eclipse appearance, which is important context. Because there is no output schema, it should do more to describe the shape or ordering of returned events, and it lacks sibling differentiation for a family of overlapping astronomy tools.

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 seven parameters are already documented in the schema. The description echoes the default/max period and implies latitude/longitude matter for eclipses, but it adds little beyond the structured parameter descriptions.

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 clearly identifies the resource as astronomical and mission events over a period, and enumerates the event families covered (Moon phases, eclipses, seasons, planetary events, mission events). It does not explicitly distinguish this from overlapping siblings such as perigee_tonight or perigee_sky_conjunctions, so it stops short of a 5.

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

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

Usage is implied by the period-based framing and the default/maximum range, which tells the agent this is for upcoming event calendars. However, there is no explicit when-to-use or when-not-to-use guidance and no named alternatives among the many sibling 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 declare readOnlyHint and openWorldHint, so safety is covered; the description adds genuinely new behavioral detail — multilingual matching, optional accents, and accepted identifier schemes (NORAD, COSPAR). It does not state what happens with ambiguous or zero matches (multiple results, empty set), which is the main remaining behavioral 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?

One dense sentence that front-loads the verb and the accepted input formats, with the return value last. Every clause earns its place; only the missing `limit` mention keeps it from being complete rather than verbose.

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

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

With no output schema, the description should say more about the return shape than 'returns ids' — whether it returns one or many matches, and what fields accompany each. The unaddressed `limit` parameter compounds this, though the input-format guidance is strong for a discovery tool.

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

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

Schema coverage is 0%, so the description must carry parameter meaning. It richly characterizes `query` (names or identifiers, English/French, accents optional, multiple id formats) but never mentions `limit` (1-50) — whether it caps matches or is a fuzzy-match threshold is left entirely to guesswork.

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?

A specific verb ('looks up') plus an enumerated set of resources (planets, moons, missions, satellites, sites, stars) makes the scope unmistakable. It also states the return value's role ('Returns ids for the other tools'), which implicitly separates it from perigee_object and perigee_state, though no sibling is named directly.

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?

'Returns ids for the other tools' implies this is a resolution step before calling id-based tools, which is useful implied usage. There is no explicit when-not or named alternative (e.g. when to prefer perigee_object if you already have an id), so selection still requires 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 readOnlyHint and openWorldHint, so safety is covered; the description goes beyond that by disclosing the return shape (time/latitude/longitude/height points, GeoJSON MultiLineString split at the antimeridian) and a hard 360-point cap. With no output schema, this disclosure is genuinely load-bearing, though it says nothing about failure modes for non-Earth objects.

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

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

A single dense sentence with the primary subject front-loaded and no filler; each clause (points, GeoJSON, antimeridian split, point cap) carries information. Slightly weakened by being a sentence fragment with no explicit framing verb.

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?

Because no output schema exists, the description correctly takes on the return-format explanation and does it well. However, it leaves the required `id` parameter and the units of 'height' unaddressed, and gives no indication of behavior when the id does not denote an Earth satellite.

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 80%, so the baseline is 3. The description only echoes constraints already in the schema ('one or two orbits', 'up to 360 points') and says nothing about the sole required parameter `id`, which lacks a schema description and whose meaning (satellite identifier) must be inferred.

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 concrete resource — the ground path of an Earth satellite over one or two orbits — and enumerates its output form (point list plus GeoJSON MultiLineString). It is clearly distinct from siblings like perigee_orbit or perigee_sky by virtue of the map-ready ground geometry, though it never names an alternate tool to contrast with.

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?

Usage is only implied: 'ready for a map' hints at the mapping use case and 'over one or two orbits' bounds the scope, but there is no explicit statement of when to pick this over perigee_orbit, perigee_state, or perigee_passes, and no prerequisites such as requiring an Earth-orbiting object.

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 readOnlyHint and openWorldHint, so safety is covered; the description adds real value by disclosing the full return payload (sources and verification date, image credit/licence, Perigee view links) in the absence of an output schema. It also explains that include_image changes the response to embed the image, which hints at a larger payload, but it omits what happens for an unknown id and any rate-limit or error behaviour.

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, then a dense but useful enumeration of returned fields, plus one short sentence on include_image. The long field list is justified because no output schema exists, though it could be trimmed slightly.

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 read-only lookup with no output schema, documenting the return fields is the right move and largely done. However, with three parameters at 33% schema coverage and a crowded sibling set, the description leaves gaps on id format, failure modes, and how it relates to perigee_find or perigee_describe_view.

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 33%: only 'lang' is documented, while the required 'id' has merely min/max length and 'include_image' is bare. The description rescues include_image ('also returns the image itself') but never explains what form an id takes (NORAD number, COSPAR ID, or Perigee slug), which is the single most consequential ambiguity for a required parameter.

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 makes clear this is a catalogue-metadata lookup for a single object, and the enumerated field list (agency, country, launch date, NORAD/COSPAR/Horizons identifiers, sources, image) sharpens that. It does not state a verb explicitly ('Facts about an object') and never distinguishes itself from siblings like perigee_find, perigee_orbit or perigee_describe_view, so an agent must infer the boundary.

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?

There is no when-to-use, when-not-to-use, or prerequisite guidance at all. With 19 siblings including perigee_find and perigee_orbit, the description gives no routing signal for when an agent should fetch static facts versus query find/orbit/state.

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 and open-world behavior, and the description adds genuinely non-obvious semantics: mean elements for Earth satellites vs instantaneous two-body elements otherwise, plus which reference frame inclination is measured in. It omits failure behavior for objects with no orbit solution, which keeps it off 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?

The output contents lead, then the regime distinction and framing rules follow, so it is front-loaded and information-dense. The second clause is long and compound, but every clause carries distinct semantic content.

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

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

With no output schema, the description usefully enumerates return quantities, so an agent knows what comes back. However, the only required parameter ('id') is never explained — name vs catalog number vs SPICE identifier — and how the tool decides Earth-satellite vs other-object behavior is left unstated.

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

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

Schema coverage is 67% and the description adds real meaning beyond it: the 'centre' default is the body the object orbits, and the inclination reference frame differs by centre (equator vs ecliptic around the Sun). The required 'id' parameter remains undocumented in both places, which is the main gap.

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

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

The description names the resource (an object's orbit) and enumerates exactly what is returned: perigee/apogee altitudes, period, inclination, eccentricity, semi-major axis. That is specific enough to separate it from perigee_state (state vectors) or perigee_distance, but no sibling is named explicitly, so it stops short of a 5.

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

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

Usage is only implied by the regime split: Earth satellites get mean elements from a published element set, everything else gets instantaneous two-body elements at a date. It never says when to prefer this over perigee_state or perigee_object, nor any precondition such as the object needing a published element set.

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 and openWorldHint, so safety is covered. The description adds genuine behavioral context — the 3-day lookahead limit and the rule that visibility requires a sunlit satellite against a dark sky — but says nothing about response volume (how many passes typically return) or how min_elevation filters both culminations and visibility.

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?

Everything is packed into a single front-loaded sentence that leads with the operation and follows with required inputs and output content; no filler. It is dense to the point of being slightly hard to scan, which is why it is not 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 9-parameter tool with no output schema, the description does the important work of describing what comes back and the visibility semantics. Defaults for days, start, lang and min_elevation are only in the schema, but that is an acceptable division of labor.

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 89%, so the baseline is 3. The description does add real value for `id` by giving NORAD examples (ISS=25544, Tiangong=48274, Hubble=20580) and restates the east-positive longitude convention, but it leaves days, start, lang, height_m and min_elevation entirely to the schema.

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

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

The description names a specific verb and resource — computing satellite passes over a place — and enumerates the returned quantities (rise, culmination, set, azimuth/compass, elevation, naked-eye visibility). It is unmistakable what the tool does, but it never names an overlapping sibling such as perigee_sky or perigee_tonight to disambiguate.

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 operating context clearly: supply latitude/longitude in degrees (east positive) and an IANA time zone for local times, with a horizon of up to 3 days. There is no explicit when-not-to-use guidance or routing to alternatives, which keeps it below 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?

The annotations already declare readOnlyHint=true and openWorldHint=true, so safety and external-data properties are covered. The description adds useful behavioral context: the shadow-casting body is derived from the object's orbit unless overridden, and the search window defaults to two orbits capped at 12 hours. It stops short of describing the returned states/times in any detail, which matters since there is no output schema.

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 the core capability and followed by defaults and the intuition-building fade-out explanation. Dense but every clause carries information; the parenthetical body list is slightly long but earns its place by clarifying which shadow applies for Earth, lunar and Martian orbiters.

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 read-only, six-parameter query tool with no output schema, the description covers what is computed, the default window, and the unit-of-interest (which body casts the shadow). The main remaining gap is the shape of the result — states and entry/exit timestamps — which an agent must infer.

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 83%, so the schema already documents date, lang, hours, centre and time_zone. The description only restates the hours default and 12-hour cap, which the schema already encodes as default and maximum; it adds no syntax or semantic detail for id, date or time_zone. 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?

The description states a precise verb and resource: it determines whether an object is in sunlight, penumbra or umbra, and when it next enters and leaves the shadow, plus which body casts the shadow. This is specific enough that no sibling (perigee_passes, perigee_sky, perigee_events) could be confused with it, although siblings are not named explicitly.

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

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

It gives a concrete use case ('Explains why a satellite crossing the night sky suddenly fades out') and states defaults and a hard bound ('over two orbits, at most 12 hours'), which tells the agent what it gets without extra parameters. It does not say when NOT to use it or name an alternative tool for related 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?

With readOnlyHint=true and openWorldHint=false already covering safety and locality, the description contributes substantial behavioral context by enumerating what is returned: day/twilight/night, Sun rise/set, Moon phase and illumination, planets with altitude/direction/magnitude/constellation/visibility, and bright stars. It does not discuss errors or edge cases, but for a read-only query this is above the annotation baseline.

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

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

The definition is front-loaded with the core question and then packs the return contents into one dense but purposeful list. The final sentence is a direct usage cue, and no sentence is wasted.

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?

Because there is no output schema, the description carries the burden of explaining return values, and it does so comprehensively across the sky objects and conditions. Together with the fully documented input schema and read-only annotation, an agent has enough to invoke the tool correctly.

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

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

Schema description coverage is 100%, so latitude, longitude, date, time_zone, height_m and lang are already documented. The description adds only the default-now behavior and the evening-time usage hint, which is useful but not much 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 names the resource precisely—sky conditions from a place at a date—and enumerates the Sun, Moon, planets and bright stars it reports. It is clear enough to distinguish from general event or orbit tools, but it does not explicitly differentiate itself from sibling perigee_tonight despite using the overlapping phrase 'what can I see tonight.'

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

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

It gives a concrete usage hint: for 'what can I see tonight', supply the evening time. However, it does not state when not to use this tool or name an alternative such as perigee_tonight, so the agent must infer the boundary from the sibling list.

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 readOnly and openWorld, so the lower bar applies; the description goes beyond them by disclosing that results are reduced to closest approach, include where to look and visibility (above horizon, dark sky), and that the period cap is 7 days (1 day with a satellite). It does not describe result structure, ordering, or empty-result behavior, but the behavioral picture is substantially richer than 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?

The core statement is front-loaded in the first clause and the satellite exception is placed last where it belongs. The enumerative star list ('Regulus, Spica, Antares, Aldebaran, Pollux…') is somewhat padded, but the sentences otherwise carry real 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?

For a 9-parameter read-only tool with no output schema, the description supplies the essential missing pieces: what the output conceptually contains (closest separation, sky position, visibility) and the temporal cap. It leaves return shape, ordering and the role of lang/time_zone to the schema, which is acceptable but not complete.

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 every parameter, including the default/max on days and the satellite-day interaction. The description only restates the 7-day default/cap and the one-day satellite case, adding essentially nothing beyond the schema on lat/long, start, height, max_separation, lang or time_zone.

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 concrete resource ('apparent close pairings' of Moon, planets and ecliptic bright stars) and a concrete scope (observer location, bounded period), plus a satellite variant. It is clearly a conjunction-finder rather than a general ephemeris or events tool, though it never explicitly contrasts itself with siblings like perigee_events or perigee_sky.

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?

Usage is implied by the stated scope (pairings within a period, up to 7 days; satellite mode limited to one day), but there is no explicit when-to-use/when-not guidance and no sibling is named as an alternative. An agent can infer the case but must guess where the boundary with perigee_events or perigee_tonight lies.

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 and openWorldHint, so the description is free to add value, which it does: output units (km, km/s), ICRF/J2000 axes, the default centre rule, and the presence of derived values like light time, sunlight flag and provenance. It does not say whether this is a single instant only (no series) or how large a response is, which is the remaining 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?

Position and velocity lead, with units and frame immediately attached, so it is front-loaded and dense. The trailing 'over Brazil' / 'over the Indian Ocean' examples add colour at some length, but they clarify the ground-point output rather than pad.

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

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

With no output schema, the description carries responsibility for describing the return and does so thoroughly: units, frame, centre-relative geometry, and the conditional ground-point fields. Only the response shape boundaries (single instant, no series, no request limits) are left unstated.

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

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

Schema coverage is 67%: date and centre are already documented in the schema. The description adds meaning beyond that by explaining what centre defaults to ('the body it orbits or stands on') and its effect on which extras appear, and by implying that id is an object identifier.

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 concrete verb and resource ('position ... and velocity ... of an object at a date') plus the frame, units and centre semantics, which is far more specific than the title. It doesn't name a sibling it replaces, so the agent must infer that perigee_orbit or perigee_ground_track do related but different things.

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?

Usage is implied by the returned quantities ('at a date', default centre, ground point only around Earth/Moon/Mars), but there is no explicit when-to-use or when-not guidance. Nothing tells the agent to prefer perigee_orbit, perigee_distance or perigee_ground_track instead for their cases.

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?

With readOnlyHint=true and openWorldHint=true already covering the safety profile, the description adds the returned category set and the filtering semantics of owner/operator/group (code or name). It does not disclose response shape details, how 'recent launches' is bounded in time, or what happens with non-matching filter 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?

Two sentences, front-loaded with the core purpose, and the long comma-delimited enumeration is dense but informational rather than padding. Slightly list-heavy, but nothing is redundant.

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

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

There is no output schema, so the description must convey what comes back, and it largely does by listing every count category plus the per-category listing behavior implied by 'limit'. Minor gaps remain around result ordering and the time window for 'recent launches'.

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 only 40%, with group, owner and operator undocumented in the schema, so the description carries real weight here. It supplies concrete example values for each (US/PRC/CIS/ESA for owner, SpaceX/OneWeb/Amazon Kuiper for operator, constellations/navigation/weather for group) and clarifies that codes or names are accepted.

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 ('Counts of the active satellites') and enumerates the exact breakdown dimensions returned (owner, operator, CelesTrak group, orbit regime, object type, launch year, altitude bands). This makes it unmistakably the aggregation/statistics tool versus siblings like perigee_find or perigee_object, though no sibling is named explicitly.

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?

Usage is only implied: an agent can infer this is the tool for aggregate counts rather than object lookup, and the note that owner/operator/group 'narrow a list' hints at filtering behavior. There is no explicit 'use this instead of X when Y' guidance or stated prerequisites.

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?

With readOnlyHint and openWorldHint already declared, the description adds real value by disclosing the return payload — phase/illumination details, visible passes, conjunctions, 'short highlights ready to read' — and by noting that local times depend on the supplied time zone. It omits any note on edge cases (e.g. polar latitudes with no true night), 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?

Two sentences, front-loaded with the core purpose ('What there is to see tonight from a place'), followed by a dense but purposeful enumeration of returned content and one usage directive. No filler, though the content list is long enough to strain a single sentence.

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

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

There is no output schema, so the description must carry return-value information — and it does, listing every major output section plus 'highlights ready to read'. Combined with the read-only annotation and fully described 6-param schema, an agent has enough to call it correctly; only edge-case behavior 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%, so every parameter (date, lang, height_m, latitude, longitude, time_zone) is already documented with types and ranges. The description only reinforces that lat/long are required and that time_zone governs local times, adding little beyond the schema — the baseline 3 for full coverage 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 names the resource and enumerates its contents precisely: night start/end, Moon phase and illumination, naked-eye planets, ISS/Tiangong/Hubble passes, Moon-planet pairings, and events. It is clearly an aggregate 'summary of tonight' tool, distinguishable by content from narrower siblings like perigee_passes or perigee_sky_conjunctions, though it never names those siblings.

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

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

It clarifies which night is covered ('the coming night, or the current one') and tells the agent to supply latitude/longitude plus an IANA time zone for local times, which is useful context. However, it gives no explicit when-to-use versus alternatives (e.g. perigee_sky or perigee_passes) and no exclusions, so usage is only implied.

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/openWorld annotations, it discloses what is produced (URL and iframe snippet), that the embed is the live view stripped of bars and panels, that the host page can drive the view and take PNG snapshots via postMessage under protocol perigee:v1 documented in `embedApi`, and that star_map renders the star 'alone in the iframe'. That is substantive behavioral detail an agent cannot get from the annotations.

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

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

Two dense, front-loaded sentences: the primary output (link + iframe snippet) comes first, then the postMessage capability, then the star_map exception. The long clause stacking in sentence one costs a little readability but nothing is padding.

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 nine optional-heavy parameters and no output schema, the description covers purpose, the embed's default chrome behavior, the postMessage embedding contract, and the star_map/compare interaction. The main residual gap is the format of `id` (e.g. `star:<id>`), which is only implied indirectly through the star_map and compare parameter descriptions.

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

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

Schema coverage is already 89%, so the bar is a baseline of 3; the description adds real meaning on top, notably that the embed omits bars/panels by default (clarifying panel and time_bar semantics), that the view can be paused or accelerated (rate) and followed (follow), and that star_map restricts the embed to the star alone. Only `lang` and the `id` format are left to the schema.

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

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

The description states a specific verb and output: it produces a link to a live Perigee 3D view plus an iframe snippet for embedding. It also distinguishes the star special case (star_map opens the star's own 3D map with the Sun instead). It does not explicitly contrast with nearby siblings like perigee_describe_view, so it stops short of a 5.

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

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

It supplies concrete usage context ('for a lesson page') and spells out a branch condition: for a star, star_map opens the 3D map with the Sun rather than the normal object view, optionally with compare. There are no explicit when-not statements or named alternative tools, so it's clear context rather than full routing guidance.

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