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

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". With a location, a bare date means that date there: its day, its evening and its night. 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". With a location, a bare date means that date there: its day, its evening and its night. 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	The place NAME only, one to three words, instead of lat/lon: "City" or "City,CC" with an ISO country code, e.g. "Lisbon,PT". Never a question or a sentence. 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". With a location, a bare date means that date there: its day, its evening and its night. 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

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.

Changed1 schema field changedOct 23, 2026

changedInput schema / properties / place / description

Previous value: -"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."New value: +"The place NAME only, one to three words, instead of lat/lon: \"City\" or \"City,CC\" with an ISO country code, e.g. \"Lisbon,PT\". Never a question or a sentence. 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."

Changed4 schema fields changedOct 23, 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\". 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."New value: +"Anchor date to search from. ISO 8601 UTC date or datetime, e.g. \"2026-08-06\" or \"2026-08-06T21:00:00Z\". With a location, a bare date means that date there: its day, its evening and its night. 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\". 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."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\". With a location, a bare date means that date there: its day, its evening and its night. 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 / 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\". 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."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\". With a location, a bare date means that date there: its day, its evening and its night. 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."

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

Previous 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."New value: +"Each eclipse with its peak instant, kind and Saros series. peak is greatest eclipse for the whole Earth; with a location, a solar row's local block gives the kind, magnitude and maximum_instant where you are. 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."

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.1/5.0

Behavior4/5

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

Annotations already cover read-only, idempotent, closed-world safety, so the description is free to spend its words on what annotations cannot express: the per-type counting quirk (count=3 with type "both" yields six events) and the distinction between global and location-dependent output (local circumstances, contact times, an explicit visible-from-here flag). The only gap is that the heavy payload warning for the path include lives in the schema rather than the description.

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?

One front-loaded paragraph that moves from core modes to output fields to location behavior to the counting caveat, with no filler sentences. It is dense and long, but every clause carries information an agent would otherwise have to infer.

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?

For a 13-parameter, output-schema-backed astronomy query tool, the description covers the mode selection, the optional location path, the include extras, and the main footgun. Pagination (cursor), the 1700-2200 year bound, and payload sizing are left to the schema, which is acceptable given those fields are fully documented there.

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

Parameters3/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. The description restates the include, visible_only, and type semantics that the schema already spells out at length, adding only the concrete count-per-type example; it does not explain direction anchoring or start/end interplay beyond what the schema says.

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?

Opens with a specific verb/resource pair (solar and lunar eclipses) and immediately enumerates the three retrieval modes: next from a date, previous from a date, and all in a range. It also lists the returned data (type, magnitude, obscuration, Saros series, geometry), so an agent knows exactly what it gets without opening the schema.

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?

Gives concrete operational guidance: use direction for next/previous, start/end for a range, set visible_only to true to keep only locally visible events, and use include to add path or greatest-eclipse blocks. It stops short of naming exclusion cases or pointing at sibling tools, but the siblings are different resources so the risk of misrouting is low.

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?