Skip to main content
Glama

astronomy-mcp-server

by io.github.cyanheads

astronomy-mcp-server: find sky events

astronomy_find_events
Read-onlyIdempotent

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.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
bodyNoTarget 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.
countNoNumber of forward occurrences to return. Default 1, max 20.
eventYesWhich class of event to search for.
startNoSearch 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.
latitudeNoObserver latitude in decimal degrees — required for solar_eclipse to get local circumstances, ignored by every other event.
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.
longitudeNoObserver longitude in decimal degrees — required for solar_eclipse, ignored by every other event.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
eventsNoThe next occurrences of the requested event class, in chronological order.
totalCountNoNumber of event occurrences returned.

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

All astronomy-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.6/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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.

Resources