Offline observational astronomy: positions, rise/set, moon phases, eclipses, and seasons.
Search forward from a start time for the next occurrences of one sky-event class, selected by the event enum: solar_eclipse, lunar_eclipse, equinox, solstice, moon_quarter, opposition, conjunction, max_elongation, or perigee_apogee. Only solar_eclipse takes an observer: pass latitude and longitude to get local circumstances (contact times plus local_visible). Every other class is geocentric and needs no location — a lunar eclipse is the same event everywhere the Moon is up, so it returns contact times and no local_visible. The body-relative events (opposition, conjunction, max_elongation, perigee_apogee) require a body: opposition applies to the superior planets (mars through pluto), conjunction to any planet, max_elongation to mercury and venus, and perigee_apogee to the moon (perigee/apogee), earth, or a planet (perihelion/aphelion). Returns the next count occurrences (default 1). Start defaults to now; pass an IANA timezone for observer-local timestamps.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Target body — required for opposition, conjunction, max_elongation, and perigee_apogee; ignored otherwise. "earth" is accepted only for perigee_apogee, which returns its perihelion and aphelion. | |
| count | No | Number of forward occurrences to return. Default 1, max 20. | |
| event | Yes | Which class of event to search for. | |
| start | No | Search start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | No | Observer latitude in decimal degrees — required for solar_eclipse to get local circumstances, ignored by every other event. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | No | Observer longitude in decimal degrees — required for solar_eclipse, ignored by every other event. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| events | No | The next occurrences of the requested event class, in chronological order. |
| totalCount | No | Number of event occurrences returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, which is reinforced by the description's emphasis on searching and returning occurrences. Beyond that, the description discloses important behavioral nuances: solar eEclipse returns local circumstances and `local_visible`; all others are geocentric and lack `local_visible`; body-relative events have specific body constraints; start defaults to now and timezone handling is explained. No contradiction, and it adds substantial context beyond 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?
The description is a single dense paragraph, but every sentence earns its place: it covers the core function, parameter dependencies, special cases, and defaults. It is front-loaded with the main verb and event concept, then builds logically. Slightly long, but not padded or redundant. A minor structural improvement would be using bullets for the event-specific rules, but it remains readable and efficient.
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 tool's complexity (8 parameters, multiple event classes with interdependent requirements), the description is comprehensive. It addresses every condition an agent needs to call it correctly: which events require location, which require body, valid body values per event, defaults for count and start, timezone semantics, and what the output contains (contact times, local_visible presence). With an output schema present, nothing about return values is missing. It fully covers the decision space.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3, but the description adds significant meaning beyond individual parameter descriptions. It explains conditional requirements (latitude/longitude only for solar eclipse, body only for specific event classes), clarifes that 'earth' is accepted only for perigee_apogee, and describes defaults and timezone handling. This transforms a flat enum list into actionable guidance, fully compensating for any ambiguity in 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 precise verb ('Search forward from a start time') and the exact resource ('next occurrences of one sky-event class'), and enumerates the specific event types. It clearly distinguishes from sibling tools like get_ephemeris or get_rise_set, which cover different queries. An agent can immediately infer what this tool does and what it does not do.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to pass location (only solar_eclipse) and when to pass `body` (opposition, conjunction, max_elongation, perigee_apogee), including which bodies are valid for each. It explains defaults and timezone behavior. It does not name alternative tools, but the parameter-specific instructions are clear enough for correct selection. A slight deduction for lack of explicit 'use this instead of X' phrasing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch a time-series ephemeris for a small body (asteroid or comet) or spacecraft from JPL Horizons — RA/Dec, distance, and apparent magnitude over a span, optionally with observer-relative altitude/azimuth. This covers objects the in-process major-body set cannot. The designation is passed to Horizons verbatim, so it must be in a form Horizons resolves to a single record: a numbered asteroid takes a trailing-semicolon record lookup (e.g. "433;" for Eros, "1;" for Ceres), and a periodic comet takes the DES + closest-apparition form (e.g. "DES=1P;CAP" for Halley) — a bare name like "433 Eros" or "1P/Halley" returns no match or an ambiguous record list and is rejected. Spacecraft take their negative SPK-ID. start and stop are ISO 8601 UTC and stop must be after start; step is a count plus a unit of m, h, d, mo, or y, such as "1d", "1h", or "10m". Supplying observer latitude/longitude yields topocentric coordinates and adds alt/az — supply both or neither. This is a gated, network-backed extension (JPL Horizons is keyless but rate-limited and best-effort); large spans truncate inline at 200 rows, and the truncation notice names the exact start to resume from — one step past the last row returned, because Horizons includes the start instant in its output — so re-calling from there continues the series without repeating a sample. Splitting the range into smaller adjacent spans works too; keep the same step either way so no sample is lost.
| Name | Required | Description | Default |
|---|---|---|---|
| step | No | Step size as a positive count plus a unit of m (minutes), h (hours), d (days), mo (months), or y (years), e.g. "10m", "1h", "1d". Default "1h". | 1h |
| stop | No | Ephemeris stop as an ISO 8601 UTC string, and must be later than start. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| start | No | Ephemeris start as an ISO 8601 UTC string, e.g. "2024-01-01T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | No | Observer latitude in decimal degrees — supply together with longitude for topocentric coordinates and alt/az. Supplying one without the other is rejected. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | No | Observer longitude in decimal degrees. Supply together with latitude; one without the other is rejected. | |
| designation | Yes | JPL Horizons target, passed verbatim — use a form that resolves to one record. Numbered asteroid: trailing-semicolon record lookup, e.g. "433;" (Eros), "1;" (Ceres). Periodic comet: DES + closest-apparition flag, e.g. "DES=1P;CAP" (Halley), "DES=2P;CAP" (Encke). Spacecraft: negative SPK-ID, e.g. "-48" (Hubble). A bare name like "433 Eros" or "1P/Halley" fails. Look up designations at ssd.jpl.nasa.gov/tools/sbdb_lookup.html. |
| Name | Required | Description |
|---|---|---|
| cap | No | The inline row cap that was applied. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of ephemeris rows returned. |
| notice | No | Caveats on the returned series — how to retrieve rows omitted by the cap, and whether any rows were dropped. Absent when the whole span came back intact. |
| points | No | Time-series of positions, one per step, in chronological order. |
| dropped | No | Rows Horizons returned that carried no usable time, position, or distance and were dropped. Present only when at least one row was dropped, in which case the series has gaps and is shorter than the requested step count. |
| truncated | No | True when Horizons returned more rows than the inline cap. |
| designation | No | The body designation echoed from the request. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, and idempotentHint, but the description goes well beyond them: it reveals the tool is network-backed and rate-limited ('best-effort'), truncates at 200 rows, and explains the exact resume behavior (one step past the last row). It also notes that missing zones are interpreted as UTC. This is rich behavioral disclosure that complements, and does not contradict, 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?
The description is long but every sentence earns its place. It is front-loaded with the core purpose, then flows logically through designation format, time/interval syntax, observer parameters, and truncation behavior. No fluff or redundancy; it is dense with necessary guidance. The only minor downside is its length, which might require careful reading, but it is efficiently structured.
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 complex, network-backed tool with 7 parameters and an output schema, the description is exceptionally complete. It covers all critical usage aspects: designation encoding with examples, ISO time format and timezone handling, step unit rules, observer coordinate requirements, and the truncation resume mechanism with precise instructions. An agent has everything needed to call this tool correctly, including edge cases.
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 covers all 7 parameters with detailed descriptions, so the baseline is 3. The description adds significant value beyond the schema: it explains the designation format rules in depth (trailing semicolon, DES+CAP, negative SPK-ID), emphasizes the pairwise requirement for latitude/longitude, and describes the step unit semantics and default stop. It doesn't just repeat the schema; it clarifies pitfalls and edge cases.
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 opens with a clear verb and resource: 'Fetch a time-series ephemeris for a small body (asteroid or comet) or spacecraft from JPL Horizons' and enumerates the returned quantities (RA/Dec, distance, magnitude, optional alt/az). It explicitly distinguishes itself from the in-process major-body set, so an agent can tell it apart from siblings without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states exactly when this tool is appropriate ('covers objects the in-process major-body set cannot') and gives precise, unambiguous invocation requirements: the designation format must resolve to a single Horizons record, with examples of what fails. It also explains when to supply observer coordinates and how to handle truncation via resume, leaving no ambiguity about usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the Moon phase for an instant: illuminated fraction, phase name, synodic age in days since the new moon, phase angle, and the next four quarter phases (new, first quarter, full, last quarter) with timestamps. Answers "what is the moon phase tonight" and "when is the next full moon" in one call without iteration. The time defaults to now; pass an IANA timezone to also receive observer-local timestamps. The phase is geocentric — no observer location is needed.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | Instant to evaluate as an ISO 8601 UTC string, e.g. "2024-12-15T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| age_days | No | Synodic age in days since the previous new moon. |
| time_utc | No | The instant the phase was computed for, in ISO 8601 UTC. |
| phase_name | No | Human-readable phase name (New Moon, Waxing Crescent, First Quarter, …, Waning Crescent). |
| time_local | No | The same instant in the observer-local timezone with offset, present only when a timezone was supplied. |
| next_quarters | No | The next four lunar quarter phases (new/first/full/last) in chronological order. |
| phase_angle_degrees | No | Moon phase angle in degrees: 0 = new, 90 = first quarter, 180 = full, 270 = last quarter. |
| illuminated_fraction | No | Fraction of the lunar disc illuminated, 0 to 1. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, signaling safe read-only behavior. The description adds valuable context beyond annotations: the phase is 'geocentric — no observer location is needed', which clarifies an important assumption for callers. It also explains the default-time behavior and that time without a zone is read as UTC. These details supplement the annotation-provided safety profile without contradicting it.
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 moderately long but each sentence earns its place: it front-loads the core outputs, then adds use cases, defaults, and geocentric context. The structure is logical and not redundant; while it could be tightened slightly, the information density is high and well-ordered. There is no filler, and the key facts appear early.
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 tool's complexity (returns multiple data points) and the presence of an output schema, the description sufficiently covers all necessary context: what the tool returns, how to invoke it (default time, optional timezone), and the geocentric nature that removes the need for an observer location. It also clarifies the default-to-now behavior and the UTC interpretation. No critical information is missing for an agent 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 description coverage is 100% – both 'time' and 'timezone' have detailed descriptions covering defaults, format, and semantics. The tool description adds minimal extra meaning beyond the schema: it reiterates time defaults and explains that timezone yields observer-local timestamps, but these are already implied in the schema descriptions. At high coverage, the baseline of 3 is appropriate; the description does not materially improve parameter comprehension 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 clearly states the tool 'Report[s] the Moon phase for an instant' and enumerates specific outputs: illuminated fraction, phase name, synodic age, phase angle, and next four quarter phases. It also names the concrete user questions ('what is the moon phase tonight', 'when is the next full moon') it answers, making its purpose distinct from the sibling astronomy tools such as get_ephemeris or get_sky_position. The verb-resource pairing is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: it defaults to current time, explains the timezone parameter for localized output, and emphasizes that the tool answers two common questions 'in one call without iteration', implying it is the right choice for these requests. However, it does not explicitly name alternative tools or state when NOT to use it, which would fully distinguish it from siblings. The guidance is clear but not exhaustive on exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute rise, set, and culmination (transit) times for a body at an observer location, plus the maximum altitude at culmination. For the Sun, also returns the three twilight pairs (civil −6°, nautical −12°, astronomical −18°) so a single call answers "when does the sun set and when is it truly dark." Searches forward from start (default today) and returns the next count cycles (default 1). When the body is already above the horizon at start, the first cycle is the interval in progress: its set is the imminent one and its rise is null, since that rise precedes the search — so a set is never reported earlier than the rise beside it. Circumpolar or never-rises situations are reported as null rise/set fields with an explanatory note rather than an error — the fact is the answer. Default elevation is 0 m; pass an IANA timezone for observer-local times. This server does not geocode — resolve coordinates upstream first.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | The body to compute rise/set for. Twilight is included only when this is "sun". | |
| count | No | Number of forward rise/set cycles to return. Default 1, max 31. | |
| start | No | Search start as an ISO 8601 UTC string, e.g. "2024-06-21T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | Yes | Observer latitude in decimal degrees, north positive. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | Yes | Observer longitude in decimal degrees, east positive. |
| Name | Required | Description |
|---|---|---|
| body | No | The body these rise/set cycles are for, echoed from the request. |
| error | No | Present when the call failed. Absent on success. |
| events | No | One entry per rise/set/transit cycle, searching forward from the start time. |
| totalCount | No | Number of rise/set cycles returned. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already declaring readOnlyHint=true and idempotentHint=true, the description adds valuable behavioral nuance beyond those hints: it explains the null-rise behavior when the body is already above the horizon, and how circumpolar/never-rises cases return null fields with explanatory notes instead of errors. This is exactly the kind of edge-case transparency that informs correct invocation.
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 long but each sentence earns its place: the core purpose is front-loaded, then edge cases and prerequisites follow logically. It could be tightened marginally, but for a tool with 7 parameters and several non-obvious behaviors, the detail is justified and well-structured.
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 structure is covered elsewhere. The description covers all operational aspects necessary for correct use: search direction, interval-in-progress logic, null handling for polar cases, default elevation, timezone handling, and the explicit geocoding limitation. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description nevertheless adds semantic value: it clarifies what 'count' cycles means, explains the default start as 'today' (schema says 'now' – a minor imprecision), and notes the timezone effect on output. It also ties the twilight parameter to the Sun. This goes beyond simple schema restatement, warranting a 4.
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 opens with a precise verb+resource statement: 'Compute rise, set, and culmination (transit) times for a body at an observer location, plus the maximum altitude at culmination.' This clearly distinguishes it from siblings like astronomy_get_ephemeris or astronomy_get_sky_position. The Sun-specific twilight addition further sharpens its identity.
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 context on search direction ('Searches forward from `start`'), defaults, and the observer-ground requirement ('This server does not geocode — resolve coordinates upstream first'). However, it does not name alternative tools for contrasting use cases, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Predict visible passes of a satellite (e.g. the ISS, NORAD 25544) over an observer in the next days. Identify the satellite by exactly one of norad_id or name — supplying both, or neither, is rejected. name is matched as a case-insensitive substring of CelesTrak's catalog names, so it resolves only when it picks out a single object: a broader query comes back with the matching objects and their catalog numbers to choose from, and the result echoes the query that resolved it as resolved_from_name. Fetches the object's current GP element set from CelesTrak, propagates it with SGP4 in-process, and returns each pass's rise, peak, and set times with azimuths and the peak elevation. Only passes that are naked-eye-plausible are returned — the satellite must be sunlit at peak while the observer's sky is dark. Every returned pass rises within the requested window: a pass already underway at start is omitted rather than reported with start as its rise, so back up start to see it. A start further than about a month from the element set's epoch is rejected as out of range on that distance alone, and an element set that will not propagate to a window inside that horizon is rejected as a reentry — so an empty passes means only that nothing was visible. CelesTrak publishes only current element sets, so in practice start must be within about a month of today. NORAD catalog numbers and catalog names are found at celestrak.org or heavens-above.com. This is a gated, network-backed extension (CelesTrak is keyless but rate-limited; element sets are cached briefly). Default elevation 0 m; pass an IANA timezone for observer-local pass times.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Number of days ahead to search for passes. Default 7, max 10. | |
| name | No | Satellite name to resolve against CelesTrak, e.g. "ISS (ZARYA)". Matched as a case-insensitive substring of the catalog name, so give the fullest name you have — a short one matches many objects and is rejected as ambiguous. Mutually exclusive with `norad_id` — supply exactly one. | |
| start | No | Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | Yes | Observer latitude in decimal degrees, north positive. | |
| norad_id | No | NORAD catalog number of the satellite, e.g. 25544 for the ISS. Found at celestrak.org or heavens-above.com. Mutually exclusive with `name` — supply exactly one. | |
| timezone | No | IANA timezone for localized pass times, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | Yes | Observer longitude in decimal degrees, east positive. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| passes | No | Visible passes (sunlit satellite over a dark-enough sky) in the requested window, chronological. |
| norad_id | No | The NORAD catalog number echoed from the request. |
| totalCount | No | Number of visible passes found in the window. |
| satellite_name | No | Satellite name as CelesTrak catalogs it (the element set's OBJECT_NAME). |
| resolved_from_name | No | The name query that resolved this object. Present only when the request supplied `name` rather than `norad_id`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses a wealth of behavioral details beyond the annotations: it fetches from CelesTrak, propagates with SGP4, filters for naked-eye visibility (sunlit at peak, dark sky), omits passes already underway, rejects starts too far from the element set epoch, and rejects nonexistent objects as reentries. It also mentions rate limiting and brief caching. Annotations (readOnly, idempotent, openWorld) are consistent; no contradiction.
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 long but every sentence carries functional weight. It is logically structured: core purpose up front, then identifier constraints, then propagation and filtering behavior, then edge cases and constraints, then operational notes. While it could be trimmed slightly, the complexity of the tool warrants the detail.
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 tool's complexity and the presence of an output schema (which covers return values), the description is remarkably complete. It covers all major behavioral aspects: identifier resolution, propagation method, visibility filtering, temporal constraints, error conditions (rejection criteria), and operational notes (rate limits, caching, defaults). An agent would have all necessary context 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. The description adds significant semantics: it explains the mutual exclusivity of norad_id and name, the resolution behavior and echo of `resolved_from_name`, the start window constraint relative to element set epoch, timezone handling, and default elevation. This goes well beyond the schema parameter descriptions, justifying a 4.
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 opens with a specific verb and resource: 'Predict visible passes of a satellite ... over an observer in the next `days`.' It clearly states the function and distinguishes it from sibling tools like ephemeris or rise/set by focusing on pass prediction with visibility filtering. The mention of the ISS and NORAD ID example grounds it concretely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit when-to-use guidance: it mandates exactly one of `norad_id` or `name` and explains the rejection of both/neither. It details the substring matching behavior and how ambiguity is resolved, plus edge cases like passes already underway and start horizon constraints. It doesn't name sibling alternatives but the context makes it clear this is the satellite-pass tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compute the apparent topocentric position of one solar-system body (sun, moon, mercury through neptune, pluto) or a named bright star for an observer location and instant. Returns equatorial (RA/Dec), refraction-corrected horizontal (altitude/azimuth), and ecliptic coordinates, plus distance, apparent magnitude, angular diameter, phase angle, illuminated fraction, and the constellation it falls in. For a solar-system body it also returns that body card — classification, mean radius, naked-eye visibility — the same values served at astronomy://body/{body}, so a client without resource support does not need a second surface to reach them; a catalog star has no card and the field is absent. Positions are parallax- and aberration-corrected for the given observer; default elevation is 0 m and the default time is now. Supply star (e.g. "Sirius", "Polaris") instead of body to target a catalog star; body is ignored when star is set. Pass an IANA timezone to also receive the observer-local time. This server does not geocode — resolve a place name to latitude/longitude upstream first.
| Name | Required | Description | Default |
|---|---|---|---|
| body | No | Solar-system body to locate. Omit when targeting a named star via `star`. | |
| star | No | Named bright star to locate (common name or Bayer designation, e.g. "Sirius", "Alpha Centauri"). Takes precedence over `body`. | |
| time | No | Instant of observation as an ISO 8601 UTC string, e.g. "2024-04-08T18:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | Yes | Observer latitude in decimal degrees, north positive. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | Yes | Observer longitude in decimal degrees, east positive. |
| Name | Required | Description |
|---|---|---|
| body | No | The body or star this position is for, echoed from the request. |
| error | No | Present when the call failed. Absent on success. |
| ecliptic | No | Ecliptic-of-date coordinates of the body. |
| time_utc | No | The instant of the observation in ISO 8601 UTC. |
| magnitude | No | Apparent visual magnitude (lower is brighter). Null for bodies where the engine cannot compute it. |
| equatorial | No | Apparent equatorial coordinates, corrected for precession, nutation, parallax, and aberration. |
| horizontal | No | Refraction-corrected horizontal coordinates as seen from the observer. |
| time_local | No | The same instant in the observer-local timezone with offset, present only when a timezone was supplied. |
| body_metadata | No | The body card also served at astronomy://body/{body}, copied here so a client without resource support can reach it. Present for the ten solar-system bodies; absent for a catalog star, which has no card. |
| constellation | No | The constellation the body currently falls within. |
| phase_angle_degrees | No | Sun-body-observer phase angle in degrees. Null when not applicable (e.g. stars). |
| illuminated_fraction | No | Fraction of the disc illuminated, 0 to 1. Null when not applicable. |
| angular_diameter_arcsec | No | Apparent angular diameter of the disc in arcseconds. Null for point-source convention bodies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses far more than the annotations already provide: parallax/aberration correction, refraction-corrected horizontal coordinates, defaults for elevation and time, the UTC interpretation of zone-less time strings, the differing behavior for solar-system bodies (body card included) versus catalog stars (no card, field absent), and the explicit note that the server does not geocode. These are valuable behavioral traits beyond readOnly/idempotent hints, with no contradiction to 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?
The description is long but every sentence carries information. It opens with the core function, then lists outputs, then surfaces usage constraints and defaults, and closes with the geocoding caveat. There is no filler or repetition; the dense structure is front-loaded and well ordered.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description is remarkably complete. It covers all required parameters and defaults, the body/star selection model, timezone handling, geocoding limitations, and the difference in return shape between solar-system bodies and stars. Even though an output schema exists, the description adds context that no structured field captures, leaving no critical gap for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The prose adds genuinely useful semantics on top: the precedence rule between `star` and `body`, the fact that only solar-system bodies return a body card, and the clarification that `time` without a zone is read as UTC. These go beyond the schema and materially help an agent call the tool correctly, earning a 4.
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 the verb and resource: compute the apparent topocentric position of a solar-system body or named star for a given observer and instant, and lists the many returned coordinate systems and derived quantities. It is specific enough to distinguish from generic astronomy queries, but it does not explicitly differentiate from siblings such as astronomy_get_ephemeris or astronomy_get_rise_set, so the purpose is clear but the sibling distinction is not 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?
The description gives useful usage directives: how to select a star versus body, the precedence of `star` over `body`, default time and elevation, and the external requirement that geocoding must be done upstream. However, it never says when to choose this tool over astronomy_get_ephemeris (which likely covers time ranges) or astronomy_get_rise_set, leaving relative usage to inference. It covers some usage conditions but omits explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The one-call "what is up right now" answer. For an observer location and instant, iterate every naked-eye solar-system body (and, with include_stars, the bundled bright stars), compute altitude and azimuth, keep those above the horizon, rank them brightest-and-highest first, and attach a plain-language visibility note to each. The whole sky is gated by the Sun's altitude into daylight / civil / nautical / astronomical twilight / dark, returned alongside the list. time is a single evaluation instant, not a window — for "tonight" pass a time after astronomical dusk (use astronomy_get_rise_set on the sun to find it). Default elevation 0 m; use min_altitude to skip objects grazing the horizon. This server does not geocode — resolve coordinates upstream first; pass an IANA timezone for observer-local times on each body.
| Name | Required | Description | Default |
|---|---|---|---|
| time | No | Evaluation instant as an ISO 8601 UTC string, e.g. "2024-08-12T05:00:00Z". Defaults to now. A single instant, not a window. A value with no zone designator is read as UTC, not the local zone of the server process. | |
| latitude | Yes | Observer latitude in decimal degrees, north positive. | |
| timezone | No | IANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only. | |
| elevation | No | Observer elevation in meters above sea level. Default 0. | |
| longitude | Yes | Observer longitude in decimal degrees, east positive. | |
| min_altitude | No | Minimum altitude in degrees to include a body. Default 0 (above the horizon); use e.g. 5 to require clearance. | |
| include_stars | No | Include the bundled bright stars alongside planets. Default false. |
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| bodies | No | Every body (and optional star) above the minimum-altitude filter, ranked brightest-and-highest first. |
| total_count | No | Number of bodies returned above the minimum-altitude filter. |
| sky_condition | No | Sky condition derived from the Sun's altitude — the gate for whether faint objects are observable. |
| sun_altitude_degrees | No | The Sun's altitude in degrees that produced the sky condition. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description need not repeat safety. It adds valuable behavioral detail: time is 'a single evaluation instant, not a window,' results are ranked 'brightest-and-highest first,' sky gating is based on Sun's altitude, and default elevation/min_altitude semantics are explained. The geocoding limitation is also disclosed. No contradiction with 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 a bit long but well-organized: the opening sentence delivers the core purpose, followed by process, time semantics, elevation guidance, and a geocoding caveat. It is front-loaded with the most important information and each sentence earns its place by either clarifying semantics or giving usage direction. Slightly more verbose than necessary, but structure compensates.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and an output schema, the description covers everything an agent needs to invoke it correctly: the evaluation procedure, the meaning of `time` as a single instant, how to handle 'tonight,' default elevation, min_altitude for horizon filtering, include_stars behavior, and the upstream geocoding requirement. The output schema handles return details. Nothing essential 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 100%, so parameters are already documented. The description enriches semantics beyond the schema: it clarifies that `time` must be a single instant and suggests using it after astronomical dusk for 'tonight' queries, and it explains that `min_altitude` is for skipping horizon-grazing objects. This adds decision-relevant context not present in the raw schema field 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 opens with a crisp one-line purpose: 'The one-call “what is up right now” answer,' then details the algorithm (iterate bodies, compute altitude/azimuth, filter above horizon, rank brightest-and-highest). It clearly distinguishes itself from sibling tools like astronomy_get_ephemeris or astronomy_get_rise_set by focusing on the aggregate visible-sky snapshot. The verb (list) and resource (visible bodies) are 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?
The description gives concrete usage context: for 'tonight,' it instructs to pass a time after astronomical dusk and points to astronomy_get_rise_set on the Sun as the way to find that time. It also notes the server does not geocode, advising to resolve coordinates upstream. While it doesn't enumerate every alternative tool, it implicitly separates this from ephemeris/rise-set tools by framing it as the quick sky summary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
astronomy_find_events6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "events",
+ "totalCount"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `observer_required`: A solar_eclipse event was requested without observer latitude/longitude. `body_required`: A body-relative event was requested without a target body. `body_not_supported`: The body has no such event — opposition for the Sun, Moon, Earth, or an inner planet; conjunction for the Sun, Moon, or Earth; max_elongation for anything but mercury or venus; perigee_apogee for the Sun. `invalid_time`: The `start` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested start instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "observer_required",
+ "body_required",
+ "body_not_supported",
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "events",
- "totalCount"
-]astronomy_get_ephemeris6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "designation",
+ "points",
+ "truncated",
+ "shown",
+ "cap"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The start or stop timestamp is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `invalid_time_range`: The resolved stop instant is at or before the resolved start instant. `incomplete_observer`: Exactly one of latitude and longitude was supplied. `invalid_step`: The step is not a positive count followed by a unit of m, h, d, mo, or y. `body_not_found`: JPL Horizons has no match for the designation, or the designation is ambiguous (a bare comet name matches multiple apparition records). `horizons_unavailable`: The JPL Horizons API failed after retries. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "invalid_time_range",
+ "incomplete_observer",
+ "invalid_step",
+ "body_not_found",
+ "horizons_unavailable"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "designation",
- "points",
- "truncated",
- "shown",
- "cap"
-]astronomy_get_moon_phase6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "time_utc",
+ "phase_angle_degrees",
+ "illuminated_fraction",
+ "phase_name",
+ "age_days",
+ "next_quarters"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The `time` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "time_utc",
- "phase_angle_degrees",
- "illuminated_fraction",
- "phase_name",
- "age_days",
- "next_quarters"
-]astronomy_get_rise_set6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "body",
+ "events",
+ "totalCount"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The `start` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested start instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "body",
- "events",
- "totalCount"
-]astronomy_get_satellite_passes6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "norad_id",
+ "passes",
+ "totalCount"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The start timestamp is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The start instant is outside the SGP4 high-accuracy span (≈1900–2100), or more than about a month from the epoch of the current element set — checked on the epoch distance itself, since SGP4 keeps returning positions well past the point where the mean elements describe the orbit. `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. `invalid_target`: Neither `norad_id` nor `name` was supplied, or both were. `tle_not_found`: CelesTrak has no current element set for the NORAD ID. `satellite_name_not_found`: No current CelesTrak object has a name containing the `name` value. `ambiguous_satellite_name`: The `name` value matches more than one current object and none of them carries it as their whole name. The error names the match count and lists the matching objects with their catalog numbers, capped when there are more than the list holds. A capped list carries a hint leading with narrowing instead of with the list, since the wanted object need not be among the ones shown. `object_decayed`: A current element set will not propagate to a window near its own epoch — the signature of an object that has reentered. `celestrak_unavailable`: The element-set fetch failed after retries, or returned a body that is not JSON at all. `malformed_element_set`: CelesTrak answered with parsable JSON whose GP record does not carry the fields an OMM element set requires — a permanent property of that record, not the transient outage celestrak_unavailable covers. The same request returns the same record, so retrying it can only fail again. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone",
+ "invalid_target",
+ "tle_not_found",
+ "satellite_name_not_found",
+ "ambiguous_satellite_name",
+ "object_decayed",
+ "celestrak_unavailable",
+ "malformed_element_set"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "norad_id",
- "passes",
- "totalCount"
-]astronomy_get_sky_position6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "body",
+ "time_utc",
+ "equatorial",
+ "horizontal",
+ "ecliptic",
+ "magnitude",
+ "angular_diameter_arcsec",
+ "phase_angle_degrees",
+ "illuminated_fraction",
+ "constellation"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The `time` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. `star_not_found`: The `star` name is not present in the bundled bright-star catalog. `body_required`: Neither a `body` nor a `star` was supplied. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone",
+ "star_not_found",
+ "body_required"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "body",
- "time_utc",
- "equatorial",
- "horizontal",
- "ecliptic",
- "magnitude",
- "angular_diameter_arcsec",
- "phase_angle_degrees",
- "illuminated_fraction",
- "constellation"
-]astronomy_list_visible6 fields changedInput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Input schema / additionalPropertiesAdded value: +falseOutput schema / $schemaPrevious value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"Output schema / anyOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "error"
+ ]
+ },
+ "required": [
+ "sky_condition",
+ "sun_altitude_degrees",
+ "total_count",
+ "bodies"
+ ]
+ },
+ {
+ "required": [
+ "error"
+ ]
+ }
+]Output schema / properties / errorAdded value: +{
+ "additionalProperties": {},
+ "description": "Present when the call failed. Absent on success.",
+ "properties": {
+ "code": {
+ "description": "JSON-RPC error code for this failure.",
+ "maximum": 9007199254740991,
+ "minimum": -9007199254740991,
+ "type": "integer"
+ },
+ "data": {
+ "additionalProperties": {},
+ "properties": {
+ "reason": {
+ "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The `time` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. Other values are possible when a failure originates below the handler.",
+ "examples": [
+ "invalid_time",
+ "time_out_of_range",
+ "invalid_timezone"
+ ],
+ "type": "string"
+ },
+ "recovery": {
+ "additionalProperties": {},
+ "description": "Actionable next step for the caller.",
+ "properties": {
+ "hint": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "hint"
+ ],
+ "type": "object"
+ },
+ "retryable": {
+ "description": "Whether retrying may succeed.",
+ "type": "boolean"
+ }
+ },
+ "type": "object"
+ },
+ "message": {
+ "description": "Human-readable description of what went wrong.",
+ "type": "string"
+ }
+ },
+ "required": [
+ "code",
+ "message"
+ ],
+ "type": "object"
+}Output schema / requiredRemoved value: -[
- "sky_condition",
- "sun_altitude_degrees",
- "total_count",
- "bodies"
-]astronomy_find_events1 field changedInput schema / properties / start / descriptionPrevious value: -"Search start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\". Defaults to now."New value: +"Search start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."astronomy_get_ephemeris2 fields changedInput schema / properties / start / descriptionPrevious value: -"Ephemeris start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\". Defaults to now."New value: +"Ephemeris start as an ISO 8601 UTC string, e.g. \"2024-01-01T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."Input schema / properties / stop / descriptionPrevious value: -"Ephemeris stop as an ISO 8601 UTC string, and must be later than start. Defaults to 24 hours after start."New value: +"Ephemeris stop as an ISO 8601 UTC string, and must be later than start. Defaults to 24 hours after start. A value with no zone designator is read as UTC, not the local zone of the server process."astronomy_get_moon_phase1 field changedInput schema / properties / time / descriptionPrevious value: -"Instant to evaluate as an ISO 8601 UTC string, e.g. \"2024-12-15T00:00:00Z\". Defaults to now."New value: +"Instant to evaluate as an ISO 8601 UTC string, e.g. \"2024-12-15T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."astronomy_get_rise_set2 fields changedInput schema / properties / start / descriptionPrevious value: -"Search start as an ISO 8601 UTC string, e.g. \"2024-06-21T00:00:00Z\". Defaults to now."New value: +"Search start as an ISO 8601 UTC string, e.g. \"2024-06-21T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."Output schema / properties / events / items / properties / rise_utc / descriptionPrevious value: -"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle (e.g. circumpolar)."New value: +"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle — because it is circumpolar, or because it was already above the horizon at the search start, whose rise precedes the search. The accompanying note says which."astronomy_get_satellite_passes1 field changedInput schema / properties / start / descriptionPrevious value: -"Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now."New value: +"Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."astronomy_get_sky_position2 fields changedInput schema / properties / time / descriptionPrevious value: -"Instant of observation as an ISO 8601 UTC string, e.g. \"2024-04-08T18:00:00Z\". Defaults to now."New value: +"Instant of observation as an ISO 8601 UTC string, e.g. \"2024-04-08T18:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."Output schema / properties / body_metadataAdded value: +{
+ "additionalProperties": false,
+ "description": "The body card also served at astronomy://body/{body}, copied here so a client without resource support can reach it. Present for the ten solar-system bodies; absent for a catalog star, which has no card.",
+ "properties": {
+ "mean_radius_km": {
+ "description": "Mean radius in kilometers, from IAU/NASA fact sheets.",
+ "type": "number"
+ },
+ "naked_eye": {
+ "description": "True when the body is typically visible to the naked eye.",
+ "type": "boolean"
+ },
+ "type": {
+ "description": "Classification of the body.",
+ "enum": [
+ "star",
+ "planet",
+ "moon",
+ "dwarf"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "mean_radius_km",
+ "naked_eye"
+ ],
+ "type": "object"
+}astronomy_list_visible1 field changedInput schema / properties / time / descriptionPrevious value: -"Evaluation instant as an ISO 8601 UTC string, e.g. \"2024-08-12T05:00:00Z\". Defaults to now. A single instant, not a window."New value: +"Evaluation instant as an ISO 8601 UTC string, e.g. \"2024-08-12T05:00:00Z\". Defaults to now. A single instant, not a window. A value with no zone designator is read as UTC, not the local zone of the server process."astronomy_get_satellite_passes1 field changedInput schema / properties / start / descriptionPrevious value: -"Search start as an ISO 8601 UTC string, within about a month of today — the current element set cannot be propagated further. Defaults to now."New value: +"Search start as an ISO 8601 UTC string, within about a month of the current element set's epoch — for a tracked object that epoch is hours old, so in practice within about a month of today. A start further out is rejected rather than answered from elements that no longer describe the orbit. Defaults to now."astronomy_get_satellite_passes6 fields changedInput schema / oneOfAdded value: +[
+ {
+ "not": {
+ "required": [
+ "name"
+ ]
+ },
+ "required": [
+ "norad_id"
+ ],
+ "type": "object"
+ },
+ {
+ "not": {
+ "required": [
+ "norad_id"
+ ]
+ },
+ "required": [
+ "name"
+ ],
+ "type": "object"
+ }
+]Input schema / properties / nameAdded value: +{
+ "description": "Satellite name to resolve against CelesTrak, e.g. \"ISS (ZARYA)\". Matched as a case-insensitive substring of the catalog name, so give the fullest name you have — a short one matches many objects and is rejected as ambiguous. Mutually exclusive with `norad_id` — supply exactly one.",
+ "type": "string"
+}Input schema / properties / norad_id / descriptionPrevious value: -"NORAD catalog number of the satellite, e.g. 25544 for the ISS. Found at celestrak.org or heavens-above.com."New value: +"NORAD catalog number of the satellite, e.g. 25544 for the ISS. Found at celestrak.org or heavens-above.com. Mutually exclusive with `name` — supply exactly one."Input schema / requiredPrevious value: -[
- "norad_id",
- "latitude",
- "longitude"
-]New value: +[
+ "latitude",
+ "longitude"
+]Output schema / properties / resolved_from_nameAdded value: +{
+ "description": "The name query that resolved this object. Present only when the request supplied `name` rather than `norad_id`.",
+ "type": "string"
+}Output schema / properties / satellite_name / descriptionPrevious value: -"Satellite name from the TLE header, when present."New value: +"Satellite name as CelesTrak catalogs it (the element set's OBJECT_NAME)."astronomy_find_eventsastronomy_get_ephemerisastronomy_get_moon_phaseastronomy_get_rise_setastronomy_get_satellite_passesastronomy_get_sky_positionastronomy_list_visibleClaiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as io.github.alice/server, link the matching GitHub user, then choose Claim with GitHub. An organization namespace such as io.github.acme/server also needs that organization to have installed the Glama AI GitHub App and approved its permissions, because GitHub discloses organization membership only to apps it has installed. Use HTTP or DNS when it has not.
HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at /.well-known/glama.json on the same origin as the connector, then choose Check HTTP challenge.
DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
No comments yet. Be the first to start the discussion!
Astronomy: sun, moon, planet, eclipse, twilight and star position calculations.
Observatory-grade Indian astronomy, years -5000..+5000: positions, eclipses, panchang date search.
Sub-arcsecond ephemeris and astrology on NASA JPL DE440: natal, transits, eclipses, Human Design.
Add one secure layer between your agents and this server.
Each tool targets a clearly distinct aspect of astronomy: event lookup, ephemeris for small bodies, moon phase, rise/set times, satellite passes, sky position for bodies/stars, and a visible-objects summary. Even overlapping capabilities (e.g., get_sky_position vs. get_ephemeris) are separated by scope (single instant vs. time series, major bodies vs. small bodies). No ambiguity in choosing between tools.
All tool names follow a consistent pattern: 'astronomy_' prefix + descriptive verb ('find', 'get', 'list') + object. The verbs are homogeneous (mostly 'get_', plus 'find_events' and 'list_visible'), and the snake_case style is uniform. Predictable and easy to navigate.
Seven tools is a well-scoped number for an astronomy server. Each tool covers a distinct major query type, and none feel redundant or unnecessary. This is within the ideal 3–15 range and feels neither too thin nor too heavy.
The tool set covers the full range of common astronomy asks: positions, phases, events, rise/set, satellite passes, and a 'what's up' overview. Small-body ephemerides fill the gap for non-major objects. There are no obvious dead ends; an agent can answer most user questions with these tools alone.
