Skip to main content
Glama

Totally Tarot Calculators

Find the eclipses near a date

find_eclipses
Read-onlyIdempotent

Finds the solar and lunar eclipses nearest a date: greatest eclipse to the second in UTC, type, obscuration, the eclipsed body's sign, days from the date, and for a solar eclipse where greatest eclipse meets the Earth. Given a place, each listing also carries what that observer gets: local kind, first contact, maximum, last contact and altitude at each.

The 6,585.3-day saros groups eclipses into families whose members fall about a year or a continent apart, and a global eclipse is seen from only part of the Earth. Global and local circumstances are kept apart, including the Moon setting partway through or rising with the eclipse underway.

Results include an attribution line and a permalink.

Input Schema

NameRequiredDescriptionDefault
tzNoIANA zone or numeric UTC offset hours for the local contact times. Example: "Atlantic/Reykjavik".
latNoObserver latitude in decimal degrees as a string. Example: "64.1466". Paired with lon.
lonNoObserver longitude in decimal degrees as a string. Example: "-21.9426". Paired with lat.
dateNoThe date to search around, ISO YYYY-MM-DD, 1700-2200. Example: "2026-08-12". Defaults to today (UTC).
countNoHow many per side of the date, "1" to "12", default "3". Example: "1". Each extra one adds server time.
placeNoObserver town or city. Example: "Reykjavik, Iceland". Adds the local kind, contact times and altitudes.
familyNoWhich eclipses to list: "both" (the default), "lunar" or "solar".

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • changedInput schema / properties / count / description
      Previous value: -"How many per side of the date, \"1\" to \"12\", default \"3\". Example: \"1\". Ask for what you will use."New value: +"How many per side of the date, \"1\" to \"12\", default \"3\". Example: \"1\". Each extra one adds server time."
    • changedInput schema / properties / date / description
      Previous value: -"The date to search AROUND, ISO YYYY-MM-DD, 1700-2200. Example: \"2026-08-12\". Omit: today (UTC)."New value: +"The date to search around, ISO YYYY-MM-DD, 1700-2200. Example: \"2026-08-12\". Defaults to today (UTC)."
    • changedInput schema / properties / lat / description
      Previous value: -"Observer latitude in decimal degrees as a string. Example: \"64.1466\". Send with lon."New value: +"Observer latitude in decimal degrees as a string. Example: \"64.1466\". Paired with lon."
    • changedInput schema / properties / lon / description
      Previous value: -"Observer longitude in decimal degrees as a string. Example: \"-21.9426\". Send with lat."New value: +"Observer longitude in decimal degrees as a string. Example: \"-21.9426\". Paired with lat."
  2. Changed2 schema fields changed
    • changedInput schema / properties / date / description
      Previous value: -"The date to search AROUND, ISO YYYY-MM-DD, 1700-2200. Example: \"2026-08-12\". Need not be an eclipse date."New value: +"The date to search AROUND, ISO YYYY-MM-DD, 1700-2200. Example: \"2026-08-12\". Omit: today (UTC)."
    • removedInput schema / required
      Removed value: -[
      -  "date"
      -]
  3. Changed8 schema fields changed
    • changedInput schema / properties / count / description
      Previous value: -"How many eclipses to list on EACH side of the date, \"1\" to \"12\". Default is \"3\". Example: \"1\" for the single nearest one in each direction. Ask for what you will use."New value: +"How many per side of the date, \"1\" to \"12\", default \"3\". Example: \"1\". Ask for what you will use."
    • changedInput schema / properties / date / description
      Previous value: -"The date to search AROUND, ISO YYYY-MM-DD, between 1700 and 2200. Examples: \"2026-08-12\", \"1999-08-11\". It does not have to be a date an eclipse falls on — today's date answers \"when is the next one\"."New value: +"The date to search AROUND, ISO YYYY-MM-DD, 1700-2200. Example: \"2026-08-12\". Need not be an eclipse date."
    • changedInput schema / properties / family / description
      Previous value: -"Which eclipses to list: \"both\" (the default), \"lunar\", or \"solar\". Narrow it when the user asked about one kind; a lunar eclipse and a solar eclipse near the same date are different events and listing both invites them to be conflated."New value: +"Which eclipses to list: \"both\" (the default), \"lunar\" or \"solar\"."
    • changedInput schema / properties / lat / description
      Previous value: -"Observer latitude in decimal degrees as a string, for example \"64.1466\". Must be sent together with lon, and is an alternative to place rather than an addition to it."New value: +"Observer latitude in decimal degrees as a string. Example: \"64.1466\". Send with lon."
    • changedInput schema / properties / lon / description
      Previous value: -"Observer longitude in decimal degrees as a string, for example \"-21.9426\". Must be sent together with lat."New value: +"Observer longitude in decimal degrees as a string. Example: \"-21.9426\". Send with lat."
    • changedInput schema / properties / place / description
      Previous value: -"Town or city of the observer. Examples: \"Reykjavik, Iceland\", \"Chennai, India\". Send it when the user asked whether THEY would see it, and every listing gains local kind, local clock times and the body's altitude at each contact. Omit it when they asked what is happening in the sky, because the global answer is the true one there."New value: +"Observer town or city. Example: \"Reykjavik, Iceland\". Adds the local kind, contact times and altitudes."
    • changedInput schema / properties / tz / description
      Previous value: -"IANA zone name or a numeric UTC offset in hours, used for the local contact times. Examples: \"Atlantic/Reykjavik\", \"0\". Leave it out and the zone is resolved for the place given."New value: +"IANA zone or numeric UTC offset hours for the local contact times. Example: \"Atlantic/Reykjavik\"."
    • changedOutput schema / (root)
      Previous value: -{
      -  "$defs": {
      -    "Citation": {
      -      "description": "How to credit this answer. Present on every response, successes and refusals alike.",
      -      "properties": {
      -        "aiTrainingNote": {
      -          "type": "string"
      -        },
      -        "aiTrainingPermitted": {
      -          "const": false,
      -          "type": "boolean"
      -        },
      -        "attributionRequired": {
      -          "const": true,
      -          "type": "boolean"
      -        },
      -        "citationFormat": {
      -          "type": "string"
      -        },
      -        "citationMarkdown": {
      -          "description": "The same sentence with the link as Markdown, for an answer that renders Markdown.",
      -          "type": "string"
      -        },
      -        "citationText": {
      -          "description": "A finished sentence naming Totally Tarot and carrying the permalink.",
      -          "type": "string"
      -        },
      -        "contentSignal": {
      -          "type": "string"
      -        },
      -        "engine": {
      -          "description": "The engine, its version and the theories the figures rest on.",
      -          "type": "string"
      -        },
      -        "engineName": {
      -          "type": "string"
      -        },
      -        "engineShort": {
      -          "type": "string"
      -        },
      -        "engineVersion": {
      -          "type": "string"
      -        },
      -        "howToCite": {
      -          "type": "string"
      -        },
      -        "jsonUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "methodUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "permalink": {
      -          "description": "The human page that returns this same answer. This is the URL to link.",
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "publisher": {
      -          "type": "string"
      -        },
      -        "sourceName": {
      -          "type": "string"
      -        },
      -        "sourceUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "termsUrl": {
      -          "format": "uri",
      -          "type": "string"
      -        },
      -        "theories": {
      -          "items": {
      -            "type": "string"
      -          },
      -          "type": "array"
      -        },
      -        "usageTerms": {
      -          "type": "string"
      -        }
      -      },
      -      "required": [
      -        "attributionRequired",
      -        "citationText",
      -        "permalink",
      -        "engine",
      -        "termsUrl"
      -      ],
      -      "type": "object"
      -    }
      -  },
      -  "properties": {
      -    "attribution": {
      -      "description": "The ready-to-paste credit line. Include this in any answer built on the result.",
      -      "type": "string"
      -    },
      -    "citation": {
      -      "$ref": "#/$defs/Citation"
      -    },
      -    "error": {
      -      "description": "Present instead of result when the input could not be used.",
      -      "properties": {
      -        "code": {
      -          "type": "string"
      -        },
      -        "message": {
      -          "type": "string"
      -        },
      -        "suggestions": {
      -          "items": {
      -            "type": "string"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "inputs": {
      -      "description": "What the request was understood to be. The permalink is built from these.",
      -      "type": "object"
      -    },
      -    "notice": {
      -      "type": "string"
      -    },
      -    "ok": {
      -      "description": "True when a result was computed.",
      -      "type": "boolean"
      -    },
      -    "result": {
      -      "description": "The computed figures. Absent on a refusal.",
      -      "properties": {
      -        "date": {
      -          "description": "The date searched around, not a date an eclipse falls on.",
      -          "type": "string"
      -        },
      -        "family": {
      -          "description": "both, lunar or solar — what was actually listed.",
      -          "type": "string"
      -        },
      -        "nearest": {
      -          "description": "The eclipse nearest the date in either direction, so a caller wanting one answer does not have to compare two arrays. null only when the search found nothing at all.",
      -          "type": "object"
      -        },
      -        "place": {
      -          "description": "null when no place was given. When present, every listing also carries a `local` block, and only then does the answer say anything about what somebody would SEE.",
      -          "type": "object"
      -        },
      -        "previous": {
      -          "items": {
      -            "properties": {
      -              "kind": {
      -                "description": "total, annular, partial, penumbral, or hybrid.",
      -                "type": "string"
      -              },
      -              "peakUTC": {
      -                "description": "Greatest eclipse, to the second in UTC, for an eclipse before the date.",
      -                "type": "string"
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "type": "array"
      -        },
      -        "upcoming": {
      -          "items": {
      -            "properties": {
      -              "daysFromQuery": {
      -                "description": "Days from the date asked about.",
      -                "type": "number"
      -              },
      -              "greatestAt": {
      -                "description": "Where greatest eclipse touches the Earth, as latitude and longitude. Solar only; null for a lunar eclipse.",
      -                "type": "object"
      -              },
      -              "label": {
      -                "description": "A readable name for the event, e.g. \"total solar eclipse\".",
      -                "type": "string"
      -              },
      -              "local": {
      -                "description": "null unless a place was given. When present: the local kind, which can be weaker than the global one, the local clock times of first contact, maximum and last contact, and the altitude of the body at each — because \"the Moon sets partway through\" and \"it is already underway at moonrise\" are different sentences and only one of them is actionable.",
      -                "type": "object"
      -              },
      -              "nakedEye": {
      -                "description": "Whether there is something a person could actually see. A penumbral lunar eclipse is a real event and very nearly nothing to look at.",
      -                "type": "boolean"
      -              },
      -              "obscuration": {
      -                "description": "Fraction of the disc covered at greatest eclipse, 0 to 1. Null for a partial SOLAR eclipse, where the quantity is not defined without an observer — give a place and read local.obscuration instead.",
      -                "type": "number"
      -              },
      -              "peakUTC": {
      -                "description": "The same for an eclipse after the date.",
      -                "type": "string"
      -              },
      -              "sign": {
      -                "description": "The zodiac sign of the eclipsed body — the Moon for lunar, the Sun for solar.",
      -                "type": "string"
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "type": "array"
      -        }
      -      },
      -      "type": "object"
      -    },
      -    "summary": {
      -      "description": "The answer in one sentence.",
      -      "type": "string"
      -    },
      -    "tool": {
      -      "description": "The calculator that answered.",
      -      "type": "string"
      -    },
      -    "toolName": {
      -      "type": "string"
      -    }
      -  },
      -  "required": [
      -    "ok",
      -    "tool",
      -    "attribution",
      -    "citation"
      -  ],
      -  "type": "object"
      -}New value: +null
  4. Changed1 schema field changed
    • changedOutput schema / properties / result / properties / upcoming / items / properties / obscuration / description
      Previous value: -"Fraction of the disc covered at greatest eclipse, 0 to 1."New value: +"Fraction of the disc covered at greatest eclipse, 0 to 1. Null for a partial SOLAR eclipse, where the quantity is not defined without an observer — give a place and read local.obscuration instead."
  5. Changed1 schema field changed
    • addedOutput schema / properties / result / properties
      Added value: +{
      +  "date": {
      +    "description": "The date searched around, not a date an eclipse falls on.",
      +    "type": "string"
      +  },
      +  "family": {
      +    "description": "both, lunar or solar — what was actually listed.",
      +    "type": "string"
      +  },
      +  "nearest": {
      +    "description": "The eclipse nearest the date in either direction, so a caller wanting one answer does not have to compare two arrays. null only when the search found nothing at all.",
      +    "type": "object"
      +  },
      +  "place": {
      +    "description": "null when no place was given. When present, every listing also carries a `local` block, and only then does the answer say anything about what somebody would SEE.",
      +    "type": "object"
      +  },
      +  "previous": {
      +    "items": {
      +      "properties": {
      +        "kind": {
      +          "description": "total, annular, partial, penumbral, or hybrid.",
      +          "type": "string"
      +        },
      +        "peakUTC": {
      +          "description": "Greatest eclipse, to the second in UTC, for an eclipse before the date.",
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "type": "array"
      +  },
      +  "upcoming": {
      +    "items": {
      +      "properties": {
      +        "daysFromQuery": {
      +          "description": "Days from the date asked about.",
      +          "type": "number"
      +        },
      +        "greatestAt": {
      +          "description": "Where greatest eclipse touches the Earth, as latitude and longitude. Solar only; null for a lunar eclipse.",
      +          "type": "object"
      +        },
      +        "label": {
      +          "description": "A readable name for the event, e.g. \"total solar eclipse\".",
      +          "type": "string"
      +        },
      +        "local": {
      +          "description": "null unless a place was given. When present: the local kind, which can be weaker than the global one, the local clock times of first contact, maximum and last contact, and the altitude of the body at each — because \"the Moon sets partway through\" and \"it is already underway at moonrise\" are different sentences and only one of them is actionable.",
      +          "type": "object"
      +        },
      +        "nakedEye": {
      +          "description": "Whether there is something a person could actually see. A penumbral lunar eclipse is a real event and very nearly nothing to look at.",
      +          "type": "boolean"
      +        },
      +        "obscuration": {
      +          "description": "Fraction of the disc covered at greatest eclipse, 0 to 1.",
      +          "type": "number"
      +        },
      +        "peakUTC": {
      +          "description": "The same for an eclipse after the date.",
      +          "type": "string"
      +        },
      +        "sign": {
      +          "description": "The zodiac sign of the eclipsed body — the Moon for lunar, the Sun for solar.",
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "type": "array"
      +  }
      +}
  6. First observed

TDQS

A4.4/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is met; the description adds real behavioral detail beyond that — results carry an attribution line and permalink, global and local circumstances are kept as separate sets, and edge cases like the Moon setting mid-eclipse are handled and disclosed. It does not state the output shape beyond field names, but it goes well past the annotation baseline.

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-loaded with the payload of results, which is the right priority. The opening sentence is long and comma-chained, and the saros paragraph is informative background rather than invocation-relevant, so a little trimming is possible.

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?

There is no output schema, and the description fully compensates by naming the returned fields (greatest eclipse in UTC to the second, type, obscuration, sign, days from date, local contacts and altitudes) plus the attribution and permalink. Nothing essential for correct invocation is missing for a 7-parameter, all-optional read tool.

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; the description earns above that by explaining what `place` and the lat/lon/tz trio actually unlock (local kind, first/maximum/last contact, altitude at each), which is the key semantic distinction an agent needs when deciding whether to pass coordinates. It does not elaborate on `count`, `family`, or `date` beyond 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?

Opens with a specific verb and resource ("Finds the solar and lunar eclipses nearest a date") and immediately enumerates the returned fields, so the agent knows exactly what this produces. No sibling tool in the list (retrogrades, birth charts, moon phase) covers eclipses, so differentiation is achieved implicitly and unambiguously.

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?

Clear contextual guidance: supplying a place or lat/lon/tz adds observer-specific local circumstances, while omitting it yields global circumstances only. There is no explicit "when not to use" or named alternative, but no sibling overlaps this capability, so the omission is minor.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources