Skip to main content
Glama
savecharlie

io.github.savecharlie/almanac

by savecharlie
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

sky_positions

Read-onlyIdempotent

Compute accurate sun, moon, and planet positions for any location and time, with rise/set, phase, twilight, and season events.

Instructions

Sun, Moon and planet positions and events for a place and time.

Call this instead of recalling ephemeris values from memory: rise/set times, moon phase and body positions depend on a multi-megabyte JPL kernel and are not reliably predictable token-by-token.

Args: lat: Geodetic latitude in degrees, -90 to 90. lon: Longitude in degrees, -180 to 180. elevation_m: Observer height above sea level in metres. Defaults to 0. when: ISO date/datetime or "now". Defaults to "now" (UTC).

Returns: JSON-serializable dict with: - bodies: for the Sun and Moon, altitude_deg/azimuth_deg, above_horizon, distance_km and distance_au, plus ecliptic ("zodiac") sign - sun: rise/set/transit times and day_length_hours - moon: rise/set/transit, phase_angle_deg, illuminated_fraction, phase_name and the next new/full moons - twilight: the four twilight-phase times - next_season_event: the next equinox or solstice - query: echoed inputs and resolved UTC time; plus kernel, engine, deterministic Times are ISO-8601 UTC; angles in degrees.

Raises: ValueError: if lat or lon is out of range.

Computed from the public-domain JPL DE421 kernel via skyfield, cross-checked against an independent engine to ~1 arcsecond. Deterministic: same inputs → same output. github.com/savecharlie/almanac

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
latYes
lonYes
whenNo
elevation_mNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.2

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, the description details determinism, approximate accuracy, the JPL DE421 kernel and skyfield engine, the exact return structure, error behavior, and time/angle formatting. This goes well beyond what annotations alone provide and contradicts nothing.

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 long but well structured with Args, Returns, and Raises sections and the core purpose front-loaded. Every major section earns its place given the absence of an output schema; a little provenance detail, such as the github link, is slightly beyond what is needed for invocation.

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

Completeness4/5

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

The description is nearly complete for a complex astronomical tool with no output schema: parameters, defaults, return keys, units, errors, and computational guarantees are all covered. The one gap is that the opening promises 'planet positions' while the return details only specify Sun and Moon fields, leaving planetary ephemeris coverage ambiguous.

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?

With 0% schema description coverage, the description fully compensates: it gives lat/lon ranges, explains elevation_m with a default and units, and documents when's accepted formats and 'now' default. This is exactly the operational meaning the schema omits.

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 first sentence names a concrete resource (Sun/Moon/planet positions) and a specific operation (compute positions and events for a place and time). It also explicitly distinguishes itself from recall-from-memory, and its only sibling is the unrelated magnetic_field, so there is no ambiguity about scope.

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 clearly states when to use the tool: whenever ephemeris values such as rise/set times or moon phase are needed, rather than trusting model memory. It does not provide explicit when-not-to-use rules or alternative-tool routing, but the absence is low-impact because the only sibling is not a close substitute.

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

Deploy Server

Other Tools