Skip to main content
Glama
Sign In

CycleCalcs Astronomy

by com.cyclecalcs
OverviewDiscussionsAdmin

Clear, dark observing windows tonight

observing_windows
Read-onlyIdempotent

Is tonight good for observing here, and when? The clear, dark windows of tonight, and of the next nights the hourly cloud forecast covers, for one place: astronomical night with the Moon down (or up, with moon "any"), under the MET Norway cloud forecast. The windows are the ones the CycleCalcs Observing Planner widget draws, and the rule below decides which count; the answer is the /api/observing-windows feed's. Returns summary (tonight in one sentence on the place's clock), go_tonight (true when tonight has a window that passes the rule), next (the first window ahead that passes, with start, end, minutes and starts_in_minutes), tonight and later. Give lat, lon and tz, or a place name; lat and lon are rounded to two decimals (about 1 km), the precision of the forecast. The right tool for "is it clear enough to stargaze tonight" or "when should I set up the telescope". For the moonless dark alone, without weather, or for nights past the forecast, use astro_dark_window.

Input Schema

NameRequiredDescriptionDefault
tzNoThe place's IANA timezone, such as "America/Chicago". Required with lat and lon: tonight and every time in the answer are on the place's clock. A resolved place supplies its own.
latNoLatitude in decimal degrees, north positive. Send lat and lon together.
lonNoLongitude in decimal degrees, east positive (Lisbon is about -9.14). Send lat and lon together.
moonNo"down" (the default) counts only windows with the Moon below the horizon; "any" lets it be up.
placeNoThe 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.
cloudmaxNoThe clear limit: an hour is clear when the forecast gives under this percent of total cloud (and under 25 percent fog, with no rain forecast). Default 30.
min_minutesNoThe shortest window worth going out for, in minutes. Default 60.

Output Schema

NameRequiredDescriptionDefault
dataYesTonight's clear, dark windows at one place under the cloud forecast, and the first one ahead that passes the rule. The same plan /api/observing-windows serves.
rightsNoattribution_required when the cloud forecast or a resolved place name was used, else unrestricted. When attribution_required, the attribution line must be shown.
warningsNoMachine-readable notices about this answer. Present only when non-empty. Never changes whether the call succeeded.
attributionNoThe credit line to display verbatim when rights is attribution_required.
next_cursorNoPresent only when more rows exist. Send it back with the SAME start/end arguments as the first call to get the next page.
not_computedNoData 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.

  1. Changed1 schema field changed
    • changedInput schema / properties / cloudmax / description
      Previous value: -"The clear limit: an hour is clear when the forecast gives under this percent of total cloud (and under 25 percent fog). Default 30."New value: +"The clear limit: an hour is clear when the forecast gives under this percent of total cloud (and under 25 percent fog, with no rain forecast). Default 30."
  2. Added

TDQS

A4.2/5.0
Behavior4/5

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

Annotations already cover the safe-read profile (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: coordinates are rounded to two decimals matching forecast precision, the forecast source is MET Norway and covers only the next few nights, and a place-based lookup obligates preserving a GeoNames CC BY 4.0 attribution field. It stops short of describing failure behavior when no window qualifies or when a place fails to resolve.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose is front-loaded in the first sentence, but the middle is cluttered with implementation trivia an agent cannot act on ("the ones the CycleCalcs Observing Planner widget draws", "the /api/observing-windows feed's answer") and a dangling "the rule below" that refers to a parameter, not text below. Dense but partially wasteful.

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?

An output schema documents the return shape and annotations cover safety, so the description rightly focuses on sourcing, precision, and attribution obligations. For a seven-parameter, forecast-backed tool it is nearly complete, missing only edge-case guidance such as empty results or unresolvable place names.

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 all seven parameters are already documented, including the lat/lon/tz-vs-place alternative encoded in anyOf. The description adds only modest extra meaning — the approximate 1 km consequence of two-decimal rounding and the moon="any" relaxation — which is a marginal increment over 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?

States a specific verb-plus-resource outcome — the clear, dark observing windows for tonight and the forecast nights at one place — and explicitly names the exact inputs (lat/lon/tz or place) and output fields (summary, go_tonight, next). It is unambiguously distinct from the sibling astro_dark_window, which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete user-phrasings that should select it ("is it clear enough to stargaze tonight", "when should I set up the telescope") and an explicit exclusion with the correct alternative: "For the moonless dark alone, without weather, or for nights past the forecast, use astro_dark_window."

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

All CycleCalcs Astronomy toolsInspect
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