CycleCalcs Astronomy

Solar and lunar eclipses

astro_eclipses

Read-onlyIdempotent

Solar and lunar eclipses: the next or previous from a date, or all in a range, with type, magnitude, obscuration, Saros series and global geometry. A solar eclipse also carries a computed hybrid flag and, when central, the duration, path width and Sun altitude at greatest eclipse. With a location it adds local circumstances, contact times, and an explicit visible-from-here answer; set visible_only to true to keep only eclipses visible there. include adds the precomputed central path or the circumstances at greatest local eclipse. NOTE: count applies per type, so count=3 with type "both" can return six events.

Input Schema

TableJSON Schema

Name	Required	Description
`tz`	No	IANA timezone like "Europe/Lisbon" to render event times in local time. Optional; a resolved place supplies its own timezone.
`end`	No	Last day of an explicit window. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.
`lat`	No	Latitude in decimal degrees, north positive. Send lat and lon together.
`lon`	No	Longitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.
`date`	No	Anchor date to search from. ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.
`type`	No	Which kind of eclipse to report. Default "both".
`count`	No	How many eclipses PER TYPE to return.
`place`	No	Place name instead of lat/lon, as "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Resolved server-side; the response then carries a required GeoNames CC BY 4.0 credit in its attribution field, which must be preserved when shown.
`start`	No	First day of an explicit window (use with end). ISO 8601 UTC date or datetime, e.g. "2026-08-06" or "2026-08-06T21:00:00Z". Or jd: followed by a Julian Day on the UT scale, e.g. "jd:2461000.5". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there.
`cursor`	No	Opaque pagination cursor from a previous result's next_cursor. Send it with the same start/end arguments as the first page.
`include`	No	Optional extras, added to the default blocks rather than replacing them. "path": the precomputed central path of a solar eclipse as inline GeoJSON (central line, northern and southern limits, and per-minute duration, width, phase and Sun altitude), for the central eclipses that have one; every other eclipse says why it has none. Large: about 65 to 90 KB of JSON per eclipse, returned as both text and structured content, so ask for one eclipse at a time (type "solar", a date just before it, count 1). "greatest": the circumstances at greatest eclipse from the supplied location, inside each solar eclipse's local block (requires a location).
`direction`	No	Search direction from the anchor date. Default "next".
`visible_only`	No	true keeps only eclipses visible from the supplied location (requires a location).

Output Schema

TableJSON Schema

Name	Required	Description
`data`	Yes	Solar and lunar eclipses in a date range, optionally filtered to one location.
`rights`	No	Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.
`warnings`	No	Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.
`attribution`	No	The credit line to display verbatim when rights is attribution_required.
`next_cursor`	No	Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.
`not_computed`	No	Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as "withheld", never as "none exists".

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedSep 27, 2026

changedInput schema / properties / date / description

Previous value: -"Anchor date to search from. ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."New value: +"Anchor date to search from. ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Or jd: followed by a Julian Day on the UT scale, e.g. \"jd:2461000.5\". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."

changedInput schema / properties / end / description

Previous value: -"Last day of an explicit window. ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."New value: +"Last day of an explicit window. ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Or jd: followed by a Julian Day on the UT scale, e.g. \"jd:2461000.5\". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."

addedInput schema / properties / include

Added value: +{
+  "description": "Optional extras, added to the default blocks rather than replacing them. \"path\": the precomputed central path of a solar eclipse as inline GeoJSON (central line, northern and southern limits, and per-minute duration, width, phase and Sun altitude), for the central eclipses that have one; every other eclipse says why it has none. Large: about 65 to 90 KB of JSON per eclipse, returned as both text and structured content, so ask for one eclipse at a time (type \"solar\", a date just before it, count 1). \"greatest\": the circumstances at greatest eclipse from the supplied location, inside each solar eclipse's local block (requires a location).",
+  "items": {
+    "enum": [
+      "path",
+      "greatest"
+    ],
+    "type": "string"
+  },
+  "type": "array",
+  "uniqueItems": true
+}

changedInput schema / properties / start / description

Previous value: -"First day of an explicit window (use with end). ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."New value: +"First day of an explicit window (use with end). ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". Or jd: followed by a Julian Day on the UT scale, e.g. \"jd:2461000.5\". On astro_positions, date may list up to 24 datetimes separated by commas, answered in the order sent. Omit for the current moment. Years 1700 to 2200 only; outside that range the API refuses with DATE_OUT_OF_RANGE because the ephemeris is not reliable there."

addedOutput schema / properties / data / properties / central_geometry_note

Added value: +{
+  "description": "Only when solar eclipses are listed: the lunar-radius convention behind hybrid, the greatest_eclipse fields and the path.",
+  "type": "string"
+}

changedOutput schema / properties / data / properties / eclipses / description

Previous value: -"Each eclipse with its peak instant, kind and Saros series."New value: +"Each eclipse with its peak instant, kind and Saros series. Solar rows also carry hybrid (true for an eclipse total along part of its central track and annular along the rest; kind keeps the value at greatest eclipse), hybrid_transitions, and greatest_eclipse_duration_seconds, greatest_eclipse_path_width_km and greatest_eclipse_sun_altitude_deg (null when there is no central line). With include path, each row has a path object: available, and when true an inline GeoJSON FeatureCollection."

Changed1 schema field changedAug 9, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "description": "The MCP projection of a CycleCalcs v2 response: the answer, plus the provenance a caller needs to use it honestly.",
+  "properties": {
+    "attribution": {
+      "description": "The credit line to display verbatim when rights is attribution_required.",
+      "type": "string"
+    },
+    "data": {
+      "additionalProperties": true,
+      "description": "Solar and lunar eclipses in a date range, optionally filtered to one location.",
+      "properties": {
+        "eclipse_count": {
+          "description": "How many eclipses matched.",
+          "type": "integer"
+        },
+        "eclipses": {
+          "description": "Each eclipse with its peak instant, kind and Saros series.",
+          "type": "array"
+        },
+        "next_visible": {
+          "description": "Only when a location was given: the next one visible from there, with local circumstances.",
+          "type": "object"
+        },
+        "next_visible_note": {
+          "description": "Only when a location was given: a caveat about that visibility, when one applies.",
+          "type": "string"
+        },
+        "summary": {
+          "description": "A one-line reading of the range.",
+          "type": "string"
+        },
+        "type": {
+          "description": "Which kinds were asked for: solar, lunar or both.",
+          "type": "string"
+        },
+        "window": {
+          "description": "The range actually evaluated.",
+          "type": "object"
+        }
+      },
+      "type": "object"
+    },
+    "next_cursor": {
+      "description": "Present only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.",
+      "type": "string"
+    },
+    "not_computed": {
+      "description": "Data this API deliberately does not serve, and why. Present only when the question touched such a field. An absence named here is information: treat it as \"withheld\", never as \"none exists\".",
+      "type": "array"
+    },
+    "rights": {
+      "description": "Either unrestricted, or attribution_required when third-party place data was used. When attribution_required, the attribution line must be shown.",
+      "type": "string"
+    },
+    "warnings": {
+      "description": "Machine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.",
+      "type": "array"
+    }
+  },
+  "required": [
+    "data"
+  ],
+  "type": "object"
+}

First observedAug 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations only cover the safe-read profile, and the description adds substantial non-obvious behavior: count applies per type (count=3 with type 'both' can return six events), include='path' returns 65–90 KB per eclipse and should be requested one at a time, place resolution requires preserving a GeoNames credit, and years are limited to 1700–2200. These are exactly the operational caveats an agent needs.

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?

Front-loads the core capability and then layers conditionals (location, include, count caveat) in compact clauses. It is dense but nearly every sentence carries information; only the trailing NOTE could arguably be folded in, so it falls just short of perfect economy.

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?

For a 13-parameter, read-only, open-world-off tool with a full output schema, the description covers query modes, location behavior, optional extras, the pagination-adjacent count caveat, and the date-range limitation. An agent has everything needed to call it correctly without inspecting the schema.

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 genuinely adds meaning beyond the schema: the per-type semantics of count, the requirement that visible_only/greatest need a location, and the practical advice to request include='path' one eclipse at a time. These go beyond the parameter descriptions themselves.

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?

States a specific resource (solar and lunar eclipses) plus the three query modes (next/previous from a date, all in a range), and enumerates the data returned (type, magnitude, obscuration, Saros series, geometry). This clearly separates it from siblings like astro_moon_phases or astro_planet_events.

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?

Explains the conditional usage well: supplying a location adds local circumstances and enables visible_only, and include=greatest requires a location. It does not explicitly contrast with siblings such as astro_moon or astro_moon_phases, so it stops short of full when/when-not routing guidance.

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

All CycleCalcs Astronomy tools Inspect

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

Need Help?