Skip to main content
Glama

astronomy-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

astronomy-mcp-server: list visible bodies

astronomy_list_visible
Read-onlyIdempotent

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, along with its angular distance from the Sun. The whole sky is gated by the Sun's altitude into daylight / civil / nautical / astronomical twilight / dark, returned alongside the list, and each note says when daylight, civil twilight, or the Sun's glare hides or dims that body. 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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
timeNoEvaluation 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.
latitudeYesObserver latitude in decimal degrees, north positive.
timezoneNoIANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only.
elevationNoObserver elevation in meters above sea level. Default 0.
longitudeYesObserver longitude in decimal degrees, east positive.
min_altitudeNoMinimum altitude in degrees to include a body. Default 0 (above the horizon); use e.g. 5 to require clearance.
include_starsNoInclude the bundled bright stars alongside planets. Default false.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
bodiesNoEvery body (and optional star) above the minimum-altitude filter, ranked brightest-and-highest first.
total_countNoNumber of bodies returned above the minimum-altitude filter.
sky_conditionNoSky condition derived from the Sun's altitude — the gate for whether faint objects are observable.
sun_altitude_degreesNoThe Sun's altitude in degrees that produced the sky condition.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 schema fields changed
    • addedOutput schema / properties / bodies / items / properties / sun_elongation_degrees
      Added value: +{
+  "description": "Angular distance from the Sun in degrees [0,180], seen from Earth's center. A body within about 15° of the Sun is lost in its glare. 0 for the Sun itself.",
+  "type": "number"
+}
    • changedOutput schema / properties / bodies / items / properties / visibility_note / description
      Previous value: -"Server-computed one-line headline from real values, e.g. \"Venus, mag -4.1, 12° above the WSW horizon — very bright\"."New value: +"Server-computed one-line headline from real values, e.g. \"Venus, mag -4.1, 12° above the WSW horizon — very bright\". It states when the conditions hide a body: \"daylight, not naked-eye visible\" when the Sun is up, \"N° from the Sun, lost in glare\" within 15° of the Sun, and \"civil twilight, sky still bright\" in civil twilight. The Moon and a negative-magnitude Venus take no daylight or twilight caveat, being visible in a blue sky; the Sun takes none."
    • changedOutput schema / properties / bodies / items / required
      Previous value: -[
-  "body",
-  "time_utc",
-  "equatorial",
-  "horizontal",
-  "ecliptic",
-  "magnitude",
-  "angular_diameter_arcsec",
-  "phase_angle_degrees",
-  "illuminated_fraction",
-  "constellation",
-  "rank",
-  "visibility_note"
-]New value: +[
+  "body",
+  "time_utc",
+  "equatorial",
+  "horizontal",
+  "ecliptic",
+  "magnitude",
+  "angular_diameter_arcsec",
+  "phase_angle_degrees",
+  "illuminated_fraction",
+  "sun_elongation_degrees",
+  "constellation",
+  "rank",
+  "visibility_note"
+]
  2. Changed8 schema fields changed
    • removedOutput schema / properties / bodies / items / properties / angular_diameter_arcsec / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / bodies / items / properties / angular_diameter_arcsec / type
      Added value: +[
+  "number",
+  "null"
+]
    • removedOutput schema / properties / bodies / items / properties / illuminated_fraction / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / bodies / items / properties / illuminated_fraction / type
      Added value: +[
+  "number",
+  "null"
+]
    • removedOutput schema / properties / bodies / items / properties / magnitude / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / bodies / items / properties / magnitude / type
      Added value: +[
+  "number",
+  "null"
+]
    • removedOutput schema / properties / bodies / items / properties / phase_angle_degrees / anyOf
      Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
    • addedOutput schema / properties / bodies / items / properties / phase_angle_degrees / type
      Added value: +[
+  "number",
+  "null"
+]
  3. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "sky_condition",
+      "sun_altitude_degrees",
+      "total_count",
+      "bodies"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]
    • addedOutput schema / properties / error
      Added 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"
+}
    • removedOutput schema / required
      Removed value: -[
-  "sky_condition",
-  "sun_altitude_degrees",
-  "total_count",
-  "bodies"
-]
  4. Changed1 schema field changed
    • changedInput schema / properties / time / description
      Previous 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."
  5. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description explains how the sky is gated by the Sun's altitude into daylight/twilight/dark, how visibility notes are generated, that time is a single instant not a window, that unzoned times are read as UTC, and that the server does not geocode. This gives the agent exactly the operational context it needs.

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

Conciseness5/5

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

The description is dense but every sentence carries distinct information: scope, ranking/notes, time semantics, defaults, and geocoding constraint. It is front-loaded with the core purpose and scales naturally to the complexity of a 7-parameter tool.

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

Completeness5/5

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

Given the rich annotations, the 100%-covered input schema, and the existence of an output schema, the description supplies the remaining context: timezone behavior, no-geocoding limitation, twilight gating, and how to plan 'tonight' observations. Nothing an agent needs to invoke this tool correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful operational meaning: time must be a single instant, min_altitude is for skipping horizon-grazing objects, elevation defaults to 0 m, and timezone controls observer-local output. This raises it above baseline while the schema still carries the formal definitions.

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

Purpose5/5

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

The description names a specific verb and resource ('list visible bodies' for an observer location and instant) and immediately frames it as the one-call 'what is up right now' answer, which distinguishes it from ephemeris, rise/set, and event tools. It clearly specifies scope: naked-eye solar-system bodies, optional bright stars, horizon filtering, ranking, and visibility notes.

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

Usage Guidelines4/5

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

It gives concrete conditions: use a single evaluation instant, pass a time after astronomical dusk for 'tonight', and consult astronomy_get_rise_set on the sun to find that time. It also tells users to geocode upstream and to use min_altitude to avoid horizon-grazing objects. It does not enumerate when every sibling should be chosen instead, so it falls just 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.

All astronomy-mcp-server toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources