astronomy-guide

Scope

• In-process and keyless: the Sun, the Moon, Mercury through Neptune, Pluto, and a 32-star bright-star catalog, for 1900–2100.
• Not covered: deep-sky objects (galaxies, nebulae, clusters), meteor showers, cloud cover, light pollution, aurora. Pair with a weather server for cloud cover and a space-weather server for aurora.
• Two network tools exist only where the deployment enables them: astronomy_get_ephemeris (JPL Horizons: asteroids, comets, spacecraft, and major bodies by Horizons ID number) and astronomy_get_satellite_passes (CelesTrak element sets).

Gates

• Check the tool list before promising an extension answer. When astronomy_get_ephemeris or astronomy_get_satellite_passes is not listed, it is switched off on this deployment and a call fails with "Tool … not found". Tell the user the question needs that tool; never approximate a comet position or a satellite pass from the core tools.
• Anchor a date to the observer's local day. A bare date (2026-10-28) or a UTC-midnight start resolves to 00:00 UTC, which west of Greenwich is the previous local afternoon, so astronomy_get_rise_set returns the previous evening's sunset. Pass local midday of the target date, converted to UTC, as start: the first Sun cycle then carries that evening's sunset and dusk and the next morning's dawn. Pass timezone and confirm the night from the *_local fields.
• Dark starts at astronomical dusk, not sunset. The dark-sky window runs from astronomical (−18°) dusk to astronomical dawn. In astronomy_list_visible, civil_twilight, nautical_twilight, and astronomical_twilight are all brighter than dark.
• astronomy_list_visible lists what is above the horizon, not what can be seen. It returns the Sun in daylight and a planet beside the Sun alike; judge each from sky_condition and its visibility_note ("daylight, not naked-eye visible", "lost in glare"), never from membership in the list. It never includes Uranus, Neptune, or Pluto, and includes stars only with include_stars — ask astronomy_get_sky_position for the outer planets.
• Moon phase does not say whether the Moon is up. The phase is geocentric. Before calling a night moon-washed or moon-free, get the Moon's rise and set with astronomy_get_rise_set over the same night and compare them with the dark window.
• Outside 1900–2100 every core tool fails time_out_of_range. Where astronomy_get_ephemeris is listed, it reaches other dates for a major body by its Horizons ID number — 301 for the Moon, 499 for Mars — returning position, distance, and magnitude (altitude and azimuth with an observer), but no phase name, rise/set, or event search. Without it, the date is out of reach.