Skip to main content
Glama

astronomy-mcp-server: get rise/set times

astronomy_get_rise_set
Read-onlyIdempotent

Compute rise, set, and culmination (transit) times and maximum transit altitude for a body at an observer location. Searches forward from start (default now) for count daily cycles (default 1), including days without crossings. For the Sun, each cycle carries civil −6°, nautical −12°, and astronomical −18° twilight: dusk after its set or culmination, then dawn before the next day begins. A crossing absent from that night is null. When the Sun is down and the first cycle's day begins after start, night_in_progress carries the preceding night, including polar nights without a sunset and times before start that have passed. A first cycle beginning after the culmination of a dark day instead carries that night itself, with rise, set, and transit null. When a body is already up, the partial first cycle has null rise and the imminent set; no set precedes its own rise. Circumpolar and never-rises cycles have null crossings and explanatory notes. At most 31 cycles are served per call; a count up to 366 returns the first 31 with a notice naming the exact start and count for the rest, or saying no continuation exists past 2100. A continuation may repeat the preceding night in night_in_progress, while cycles continue without overlap. Default elevation is 0 m; pass an IANA timezone for local output. Resolve coordinates upstream; this server does not geocode.

Input Schema

NameRequiredDescriptionDefault
bodyYesThe body to compute rise/set for. Twilight is included only when this is "sun".
countNoNumber of forward rise/set cycles to return. Default 1. At most 31 are computed per call; a count up to 366 returns the first 31 with a notice naming the `start` and `count` that continue the series.
startNoSearch start as an ISO 8601 UTC string, e.g. "2024-06-21T00:00:00Z". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process.
latitudeYesObserver latitude in decimal degrees, north positive.
timezoneNoIANA timezone for localized output, e.g. "America/Los_Angeles". When omitted, output is UTC-only.
elevationNoObserver elevation in meters above sea level. Default 0.
longitudeYesObserver longitude in decimal degrees, east positive.

Output Schema

NameRequiredDescriptionDefault
capNoThe per-call cycle cap that was applied.
bodyNoThe body these rise/set cycles are for, echoed from the request.
errorNoPresent when the call failed. Absent on success.
shownNoNumber of cycles returned when the cap applied.
eventsNoOne entry per rise/set/transit cycle, searching forward from the start time.
noticeNoHow to retrieve the cycles the per-call cap held back: the exact `start` and `count` to re-call with, or — when the next cycle starts after 2100, the end of the supported span — that no call can continue the series. Absent when every requested cycle came back.
truncatedNoTrue when `count` exceeded the per-call cap and only the first cycles came back.
totalCountNoNumber of rise/set cycles returned.
night_in_progressNoThe night under way at `start`, present only for the Sun when it is below the horizon and the first cycle's day begins after `start`. Each pair is bounded from the previous culmination, or a sunset after it, to the first day's sunrise or culmination. This includes polar nights without a sunset and excludes stale sunsets before an intervening polar day. Times earlier than `start` are included and have already passed; an absent crossing is null. Absent when the first cycle already carries that night, including a rest-of-dark-day cycle. A continuation may repeat here the night the previous call's last cycle carried; its `events` do not repeat. Not one of `events` and not counted by `count`.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • changedOutput schema / properties / events / items / properties / twilight / description
      Previous value: -"The three twilight pairs, present only when body is \"sun\". Each pair spans one night: dusk is the evening of this cycle's set — or, in a cycle with no set, the evening after its culmination — and dawn is the following morning, so a cycle's dawn falls a day after its rise. Each is searched only up to the start of the next cycle's day (its sunrise, or its culmination when it has no rise), so a depth the night never reaches is null. A first cycle with no rise, set, or transit is the rest of the day the search started in, inside or at the edge of a polar night; its pairs can include times before `start` that have passed. The dawn before a given sunrise is in the previous cycle's pair; before the first cycle's sunrise it is in `night_in_progress` when `start` falls in a night that began with a sunset, and otherwise start the search a day earlier to get it."New value: +"The three twilight pairs, present only when body is \"sun\". Each pair spans one night: dusk is the evening of this cycle's set — or, in a cycle with no set, the evening after its culmination — and dawn is the following morning, so a cycle's dawn falls a day after its rise. Each is searched only up to the start of the next cycle's day (its sunrise, or its culmination when it has no rise), so an absent crossing is null. A first cycle with no rise, set, or transit is the rest of the day the search started in, inside or at the edge of a polar night; its pairs can include times before `start` that have passed. The dawn before a given sunrise is in the previous cycle's pair; when the first cycle's day begins after `start`, its preceding night is in `night_in_progress`, including polar nights without a sunset."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / night_in_progress / description
      Previous value: -"The night under way at `start`, present only when body is \"sun\", the Sun is below the horizon at `start`, it set since its last culmination and within the two days before, and it rises within the two days after. The first cycle then opens with the next day — at its sunrise, or its culmination when the Sun does not rise that day — and its twilight is the night after, so this field holds the night the caller is in: for each depth, dusk on the evening of that sunset and dawn before the day of the first cycle begins. Times earlier than `start` are included and have already passed. Each pair is searched only within that night, so a depth the night never reaches is null. Absent when a day the Sun never rose on fell between the last sunset and `start`: that sunset began an earlier night. A continuation call, started one second past the last set of the previous call, repeats here the night the last cycle of that call carried; its `events` do not repeat. Not one of `events` and not counted by `count`."New value: +"The night under way at `start`, present only for the Sun when it is below the horizon and the first cycle's day begins after `start`. Each pair is bounded from the previous culmination, or a sunset after it, to the first day's sunrise or culmination. This includes polar nights without a sunset and excludes stale sunsets before an intervening polar day. Times earlier than `start` are included and have already passed; an absent crossing is null. Absent when the first cycle already carries that night, including a rest-of-dark-day cycle. A continuation may repeat here the night the previous call's last cycle carried; its `events` do not repeat. Not one of `events` and not counted by `count`."
    • changedOutput schema / properties / night_in_progress / properties / astronomical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / night_in_progress / properties / astronomical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / night_in_progress / properties / civil / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / night_in_progress / properties / civil / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / night_in_progress / properties / nautical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / night_in_progress / properties / nautical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when that crossing does not occur during the night. In a cycle, this is the evening of that cycle's set, or after its culmination when it has no set."
  2. Changed22 schema fields changed
    • changedInput schema / properties / count / description
      Previous value: -"Number of forward rise/set cycles to return. Default 1, max 31."New value: +"Number of forward rise/set cycles to return. Default 1. At most 31 are computed per call; a count up to 366 returns the first 31 with a notice naming the `start` and `count` that continue the series."
    • changedInput schema / properties / count / maximum
      Previous value: -31New value: +366
    • addedOutput schema / properties / cap
      Added value: +{
      +  "description": "The per-call cycle cap that was applied.",
      +  "type": "number"
      +}
    • changedOutput schema / properties / events / items / properties / rise_utc / description
      Previous value: -"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle — because it is circumpolar, or because it was already above the horizon at the search start, whose rise precedes the search. The accompanying note says which."New value: +"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle — because it is circumpolar, or because it was already above the horizon when the cycle opened (at the search start, or after a day it never set on), so its rise precedes the cycle. The accompanying note says which."
    • changedOutput schema / properties / events / items / properties / transit_utc / description
      Previous value: -"Culmination (highest point) time in ISO 8601 UTC, or null when not found."New value: +"Culmination (highest point) time in ISO 8601 UTC, or null when it falls outside this cycle — before its rise, after its set, or before the search start."
    • changedOutput schema / properties / events / items / properties / twilight / description
      Previous value: -"The three twilight pairs, present only when body is \"sun\". Each pair spans one night: dusk is the evening of this cycle's set and dawn is the following morning, so a cycle's dawn falls a day after its rise. The dawn before a given sunrise is in the previous cycle's pair — start the search a day earlier to get it."New value: +"The three twilight pairs, present only when body is \"sun\". Each pair spans one night: dusk is the evening of this cycle's set — or, in a cycle with no set, the evening after its culmination — and dawn is the following morning, so a cycle's dawn falls a day after its rise. Each is searched only up to the start of the next cycle's day (its sunrise, or its culmination when it has no rise), so a depth the night never reaches is null. A first cycle with no rise, set, or transit is the rest of the day the search started in, inside or at the edge of a polar night; its pairs can include times before `start` that have passed. The dawn before a given sunrise is in the previous cycle's pair; before the first cycle's sunrise it is in `night_in_progress` when `start` falls in a night that began with a sunset, and otherwise start the search a day earlier to get it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set."
    • addedOutput schema / properties / night_in_progress
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "The night under way at `start`, present only when body is \"sun\", the Sun is below the horizon at `start`, it set since its last culmination and within the two days before, and it rises within the two days after. The first cycle then opens with the next day — at its sunrise, or its culmination when the Sun does not rise that day — and its twilight is the night after, so this field holds the night the caller is in: for each depth, dusk on the evening of that sunset and dawn before the day of the first cycle begins. Times earlier than `start` are included and have already passed. Each pair is searched only within that night, so a depth the night never reaches is null. Absent when a day the Sun never rose on fell between the last sunset and `start`: that sunset began an earlier night. A continuation call, started one second past the last set of the previous call, repeats here the night the last cycle of that call carried; its `events` do not repeat. Not one of `events` and not counted by `count`.",
      +  "properties": {
      +    "astronomical": {
      +      "additionalProperties": false,
      +      "description": "Astronomical twilight (Sun at −18°): dusk and the following dawn, bounding the dark-sky window.",
      +      "properties": {
      +        "dawn_local": {
      +          "description": "Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dawn_utc": {
      +          "description": "Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_local": {
      +          "description": "Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_utc": {
      +          "description": "Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        }
      +      },
      +      "required": [
      +        "dawn_utc",
      +        "dusk_utc"
      +      ],
      +      "type": "object"
      +    },
      +    "civil": {
      +      "additionalProperties": false,
      +      "description": "Civil twilight (Sun at −6°): dusk and the following dawn.",
      +      "properties": {
      +        "dawn_local": {
      +          "description": "Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dawn_utc": {
      +          "description": "Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_local": {
      +          "description": "Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_utc": {
      +          "description": "Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        }
      +      },
      +      "required": [
      +        "dawn_utc",
      +        "dusk_utc"
      +      ],
      +      "type": "object"
      +    },
      +    "nautical": {
      +      "additionalProperties": false,
      +      "description": "Nautical twilight (Sun at −12°): dusk and the following dawn.",
      +      "properties": {
      +        "dawn_local": {
      +          "description": "Dawn in observer-local time — the morning that ends the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dawn_utc": {
      +          "description": "Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It ends the night that begins at the dusk beside it: in a cycle, the morning after that cycle's set, or after its culmination when it has no set — a day later than the cycle's rise, not the dawn before it.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_local": {
      +          "description": "Dusk in observer-local time — the evening that begins the night — present only when a timezone was supplied.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        },
      +        "dusk_utc": {
      +          "description": "Dusk (Sun descending through the depth) in ISO 8601 UTC, or null when the night never reaches the depth. It is the evening the night begins: in a cycle, the evening of that cycle's set, or after its culmination when it has no set.",
      +          "type": [
      +            "string",
      +            "null"
      +          ]
      +        }
      +      },
      +      "required": [
      +        "dawn_utc",
      +        "dusk_utc"
      +      ],
      +      "type": "object"
      +    }
      +  },
      +  "required": [
      +    "civil",
      +    "nautical",
      +    "astronomical"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / notice
      Added value: +{
      +  "description": "How to retrieve the cycles the per-call cap held back: the exact `start` and `count` to re-call with, or — when the next cycle starts after 2100, the end of the supported span — that no call can continue the series. Absent when every requested cycle came back.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / shown
      Added value: +{
      +  "description": "Number of cycles returned when the cap applied.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / truncated
      Added value: +{
      +  "description": "True when `count` exceeded the per-call cap and only the first cycles came back.",
      +  "type": "boolean"
      +}
  3. Changed16 schema fields changed
    • changedOutput schema / properties / events / items / properties / twilight / description
      Previous value: -"The three twilight pairs. Present only when body is \"sun\"."New value: +"The three twilight pairs, present only when body is \"sun\". Each pair spans one night: dusk is the evening of this cycle's set and dawn is the following morning, so a cycle's dawn falls a day after its rise. The dawn before a given sunrise is in the previous cycle's pair — start the search a day earlier to get it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / description
      Previous value: -"Astronomical twilight (Sun at −18°) dawn and dusk — the dark-sky window."New value: +"Astronomical twilight (Sun at −18°): dusk and the following dawn, bounding the dark-sky window."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time, present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time, present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / description
      Previous value: -"Civil twilight (Sun at −6°) dawn and dusk."New value: +"Civil twilight (Sun at −6°): dusk and the following dawn."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time, present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time, present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / description
      Previous value: -"Nautical twilight (Sun at −12°) dawn and dusk."New value: +"Nautical twilight (Sun at −12°): dusk and the following dawn."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_local / description
      Previous value: -"Dawn in observer-local time, present only when a timezone was supplied."New value: +"Dawn in observer-local time — the morning after the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_utc / description
      Previous value: -"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dawn (Sun ascending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the morning after the cycle's set, ending the night that begins at the dusk beside it — a day later than the cycle's rise, not the dawn before it."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_local / description
      Previous value: -"Dusk in observer-local time, present only when a timezone was supplied."New value: +"Dusk in observer-local time — the evening of the cycle's set — present only when a timezone was supplied."
    • changedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_utc / description
      Previous value: -"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur."New value: +"Dusk (Sun descending through the depth) in ISO 8601 UTC, or null if it does not occur. This is the evening of the cycle's set."
  4. Changed32 schema fields changed
    • removedOutput schema / properties / events / items / properties / rise_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / rise_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / set_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / set_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / transit_altitude_degrees / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / transit_altitude_degrees / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / transit_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / transit_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dawn_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / astronomical / properties / dusk_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dawn_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / civil / properties / dusk_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dawn_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_local / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_local / type
      Added value: +[
      +  "string",
      +  "null"
      +]
    • removedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_utc / anyOf
      Removed value: -[
      -  {
      -    "type": "string"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / events / items / properties / twilight / properties / nautical / properties / dusk_utc / type
      Added value: +[
      +  "string",
      +  "null"
      +]
  5. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "body",
      +      "events",
      +      "totalCount"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `invalid_time`: The `start` value is not a parseable ISO 8601 instant, or names a calendar date that does not exist (e.g. 2026-02-30). `time_out_of_range`: The requested start instant is outside the engine's high-accuracy span (≈1900–2100). `invalid_timezone`: The `timezone` value is not an IANA zone this runtime knows. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_time",
      +            "time_out_of_range",
      +            "invalid_timezone"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "body",
      -  "events",
      -  "totalCount"
      -]
  6. Changed2 schema fields changed
    • changedInput schema / properties / start / description
      Previous value: -"Search start as an ISO 8601 UTC string, e.g. \"2024-06-21T00:00:00Z\". Defaults to now."New value: +"Search start as an ISO 8601 UTC string, e.g. \"2024-06-21T00:00:00Z\". Defaults to now. A value with no zone designator is read as UTC, not the local zone of the server process."
    • changedOutput schema / properties / events / items / properties / rise_utc / description
      Previous value: -"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle (e.g. circumpolar)."New value: +"Rise time in ISO 8601 UTC, or null when the body does not rise in this cycle — because it is circumpolar, or because it was already above the horizon at the search start, whose rise precedes the search. The accompanying note says which."
  7. First observed

TDQS

A4.4/5.0
Behavior5/5

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint=false. The description adds substantial behavioral context beyond that: the 31-cycle cap with continuation notices, handling of partial first cycles, null crossings for circumpolar bodies, polar night behavior, and the fact that the server does not geocode. These details are exactly what an agent needs to interpret results correctly.

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 front-loaded with the core purpose and structured logically. It is long, but every sentence conveys an edge case or constraint that is not available elsewhere. Some sentences are dense, but the length is justified by the tool's complexity.

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?

Given the rich annotations, complete schema, and the presence of an output schema, the description covers all necessary behavioral and operational details. An agent would know exactly how to call the tool and how to interpret unusual outputs like `night_in_progress` and null crossings.

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 description coverage is 100%, so the schema already documents all seven parameters. The description adds marginal value, such as clarifying that `count` includes days without crossings, but most parameter details (defaults, timezone usage, elevation) are already in the schema. Baseline 3 is appropriate.

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 specific verb and a precise set of outputs (rise, set, culmination times and maximum transit altitude) for a body at an observer location. This clearly distinguishes it from siblings like astronomy_get_sky_position and astronomy_find_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?

The description gives clear operational context: searches forward from `start` (default now) for `count` cycles, includes days without crossings, and notes coordinate resolution is upstream. It does not explicitly name alternatives or when not to use the tool, but the context is sufficient for an agent to select it correctly.

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.