interactive-star-lab.vercel.app

{
  "name": "get_observation_site",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns the observation site currently selected in InteractiveStarLab, including its latitude and longitude.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "predict_visible_stars",
  "kind": "act",
  "impl": "imperative",
  "description": "Finds stars above the astronomical horizon for the selected observation site, date, and maximum magnitude. This geometric prediction does not include weather, horizon obstacles, or light-pollution APIs.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dateTime": {
        "type": "string",
        "description": "ISO 8601 observation date and time; a value without an offset is interpreted in the site's timeZone. Omit to predict for the currently configured view — preferred right after configure_sky_view."
      },
      "maxMagnitude": {
        "type": "integer",
        "minimum": 1,
        "maximum": 4,
        "description": "Faintest magnitude to include"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "description": "Maximum number of stars to return"
      }
    },
    "required": [
      "maxMagnitude"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_current_sky_state",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns the current sky viewer conditions and a structured list of stars in the current view.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "describe_current_view",
  "kind": "answer",
  "impl": "imperative",
  "description": "Describes what the human is currently looking at: site, date/time, camera direction and field of view, sky projection mode, display layers, scene counts and objects in frame, the current selection, and a log of the human's recent interactions. Read-only.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_night_ephemeris",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns the darkness ephemeris for one observing night at the selected site: sunset/sunrise, the three twilight boundaries, the astronomical darkness window, Moon illumination and moon-free intervals. A night runs local noon to local noon; omit nightOf for the night containing the current observation time. Geometric prediction only: no weather or horizon obstacles.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "nightOf": {
        "type": "string",
        "description": "Calendar date the night starts on, YYYY-MM-DD (defaults to the current night)"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "rank_nights",
  "kind": "answer",
  "impl": "imperative",
  "description": "Scores every observing night in a date range at the selected site and returns them best first. The score is 10 points per usable dark hour (astronomical darkness with the Moon down or faint), capped at 100. Use it to answer 'when should I observe'. Geometric prediction only: no weather.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from": {
        "type": "string",
        "description": "First night to score, YYYY-MM-DD"
      },
      "to": {
        "type": "string",
        "description": "Last night to score, YYYY-MM-DD (max range 62 days)"
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 62,
        "description": "Maximum nights to return (default all)"
      }
    },
    "required": [
      "from",
      "to"
    ],
    "additionalProperties": false
  }
}

{
  "name": "open_plan_view",
  "kind": "act",
  "impl": "imperative",
  "description": "Opens the human-facing Plan screen without creating or changing a Mission.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "create_observation_plan",
  "kind": "act",
  "impl": "imperative",
  "description": "Creates an observation Mission for up to five selected star IDs using the current observation site, then opens Plan for human review before Sky or Observe. To archive the actual rendered Sky canvas, open Sky with the same Mission date and site and call capture_sky_snapshot with the returned missionId.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dateTime": {
        "type": "string",
        "description": "ISO 8601 observation date and time; a value without an offset is interpreted in the site's timeZone"
      },
      "maxMagnitude": {
        "type": "integer",
        "minimum": 1,
        "maximum": 4,
        "description": "Faintest magnitude allowed for targets"
      },
      "starIds": {
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "type": "string"
        },
        "description": "One to five star IDs returned by predict_visible_stars"
      }
    },
    "required": [
      "dateTime",
      "maxMagnitude",
      "starIds"
    ],
    "additionalProperties": false
  }
}

{
  "name": "restore_observation_mission",
  "kind": "act",
  "impl": "imperative",
  "description": "Restores one observation Mission using its mission-specific recovery code. The code is a capability for that Mission, is never returned by this tool, and must not be exposed in conversation or logs. Opens the Observe screen after a successful restore.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "recoveryCode": {
        "type": "string",
        "minLength": 1,
        "description": "Mission-specific recovery code copied from the Mission creation screen"
      }
    },
    "required": [
      "recoveryCode"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_observation_mission",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns one Mission by ID, including its creation-time site, date, fixed target predictions, and cloud Snapshot status.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Observation Mission ID"
      }
    },
    "required": [
      "missionId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "get_observation_results",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns a completed observation record with star names, prediction snapshots, and human observation statuses. Without a missionId, returns the selected record or the newest completed record.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Optional observation Mission ID"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "compare_prediction_and_observation",
  "kind": "act",
  "impl": "imperative",
  "description": "Compares the fixed Mission prediction with human observation results. Unsure observations are excluded from the match-rate denominator.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Observation Mission ID"
      }
    },
    "required": [
      "missionId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "configure_sky_view",
  "kind": "act",
  "impl": "imperative",
  "description": "Configures a location and local wall-clock time, then opens Sky in one operation. Use either a built-in preset id (for example new-york) or a custom site with latitude, longitude, and timeZone. localDateTime has no UTC offset and is interpreted in the selected site's time zone.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "preset": {
        "type": "string",
        "enum": [
          "tokyo",
          "Tokyo",
          "sapporo",
          "Sapporo",
          "naha",
          "Naha",
          "singapore",
          "Singapore",
          "sydney",
          "Sydney",
          "london",
          "London",
          "new-york",
          "New York",
          "north-pole",
          "North Pole",
          "equator",
          "Equator"
        ],
        "description": "Built-in place preset id or name"
      },
      "site": {
        "type": "object",
        "description": "Custom site; required when preset is omitted",
        "properties": {
          "name": {
            "type": "string"
          },
          "latitude": {
            "type": "number",
            "minimum": -90,
            "maximum": 90
          },
          "longitude": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          },
          "timeZone": {
            "type": "string",
            "description": "IANA time zone, for example America/New_York"
          }
        },
        "required": [
          "name",
          "latitude",
          "longitude",
          "timeZone"
        ],
        "additionalProperties": false
      },
      "localDateTime": {
        "type": "string",
        "description": "Local wall-clock time as YYYY-MM-DDTHH:mm[:ss]; fractional seconds and an offset suffix are ignored"
      },
      "azimuth": {
        "type": "number",
        "minimum": 0,
        "maximum": 359.999999
      },
      "altitude": {
        "type": "number",
        "minimum": 0,
        "maximum": 90
      },
      "fieldOfView": {
        "type": "number",
        "minimum": 20,
        "maximum": 140
      }
    },
    "required": [
      "localDateTime"
    ],
    "additionalProperties": false
  }
}

{
  "name": "open_sky_view",
  "kind": "act",
  "impl": "imperative",
  "description": "Opens the human-facing Sky screen without changing sky conditions. Use get_current_sky_state to read structured star positions; this tool does not return a screenshot.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "open_observe_view",
  "kind": "act",
  "impl": "imperative",
  "description": "Opens the human-facing Observe screen so the user can record observations for the active Mission.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "set_observation_site",
  "kind": "act",
  "impl": "imperative",
  "description": "Sets the observation site and synchronizes its latitude and longitude with the Sky viewer. Existing Missions keep their creation-time site snapshots.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "description": "Optional display name; the existing name is kept when omitted"
      },
      "latitude": {
        "type": "number",
        "minimum": -90,
        "maximum": 90,
        "description": "Latitude in degrees"
      },
      "longitude": {
        "type": "number",
        "minimum": -180,
        "maximum": 180,
        "description": "Longitude in degrees"
      },
      "timeZone": {
        "type": "string",
        "description": "Optional IANA time zone, for example Asia/Tokyo"
      }
    },
    "required": [
      "latitude",
      "longitude"
    ],
    "additionalProperties": false
  }
}

{
  "name": "set_sky_view_settings",
  "kind": "act",
  "impl": "imperative",
  "description": "Changes Sky viewer date/time, direction, elevation, and field of view. Use set_observation_site for latitude and longitude. Existing Mission predictions are not recalculated.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dateTime": {
        "type": "string",
        "description": "ISO 8601 observation date and time"
      },
      "azimuth": {
        "type": "number",
        "minimum": 0,
        "maximum": 359.999999,
        "description": "View azimuth in degrees; 0 is north"
      },
      "altitude": {
        "type": "number",
        "minimum": 0,
        "maximum": 90,
        "description": "View altitude in degrees"
      },
      "fieldOfView": {
        "type": "number",
        "minimum": 20,
        "maximum": 140,
        "description": "Vertical field of view in degrees"
      },
      "skyMode": {
        "type": "string",
        "enum": [
          "window",
          "dome"
        ],
        "description": "Sky projection: the azimuth/altitude window or the stereographic all-sky dome"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "set_sky_display_settings",
  "kind": "act",
  "impl": "imperative",
  "description": "Changes Sky display layers, labels, and local simulation settings. firstMagnitude through faintMagnitude are display layers only; they are not Mission maxMagnitude and never change Mission targets or prediction snapshots.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "stars": {
        "type": "boolean",
        "description": "Show stars"
      },
      "starNames": {
        "type": "boolean",
        "description": "Show star names"
      },
      "constellationLines": {
        "type": "boolean",
        "description": "Show constellation lines"
      },
      "constellationNames": {
        "type": "boolean",
        "description": "Show constellation names"
      },
      "milkyWay": {
        "type": "boolean",
        "description": "Show the Milky Way band"
      },
      "denseStars": {
        "type": "boolean",
        "description": "Show the dense background star field"
      },
      "deepSky": {
        "type": "boolean",
        "description": "Show Messier objects, planets and the Moon"
      },
      "nightMode": {
        "type": "boolean",
        "description": "Red-light mode for night-time instrument use"
      },
      "firstMagnitude": {
        "type": "boolean",
        "description": "Enable 1st-magnitude display layer only"
      },
      "secondMagnitude": {
        "type": "boolean",
        "description": "Enable 2nd-magnitude display layer only"
      },
      "thirdMagnitude": {
        "type": "boolean",
        "description": "Enable 3rd-magnitude display layer only"
      },
      "fourthMagnitude": {
        "type": "boolean",
        "description": "Enable 4th-magnitude display layer only"
      },
      "faintMagnitude": {
        "type": "boolean",
        "description": "Enable 5th-magnitude-and-fainter display layer"
      },
      "daylightMode": {
        "type": "string",
        "enum": [
          "real",
          "removed"
        ],
        "description": "Use real daylight or remove daylight for simulation"
      },
      "lightPollution": {
        "type": "string",
        "enum": [
          "city-center",
          "urban",
          "suburban",
          "dark-sky",
          "perfect"
        ],
        "description": "Local light-pollution preset"
      },
      "limitingMagnitude": {
        "type": "number",
        "minimum": 1,
        "maximum": 6.5,
        "description": "Manual faintest simulated magnitude"
      },
      "observerSensitivity": {
        "type": "number",
        "minimum": -0.5,
        "maximum": 0.5,
        "description": "Observer sensitivity correction in magnitudes"
      },
      "showHiddenStars": {
        "type": "boolean",
        "description": "Show stars that are present but hidden"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "save_observation_results",
  "kind": "act",
  "impl": "imperative",
  "description": "Saves only observation statuses explicitly reported by the user for every target in a Mission. It does not invent or infer observations, and it preserves the Mission creation-time prediction snapshot. Overwriting a Mission that already has saved results requires confirm:true. A successful save returns an undoToken valid for 5 minutes; pass it back as { \"undoToken\": \"...\" } to restore the previous record (or remove a newly created one).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Mission ID to complete"
      },
      "results": {
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "description": "Exactly one user-reported result per Mission target",
        "items": {
          "type": "object",
          "properties": {
            "starId": {
              "type": "string",
              "description": "Star ID from the Mission"
            },
            "status": {
              "type": "string",
              "enum": [
                "visible",
                "not_visible",
                "unsure"
              ],
              "description": "The user's observation status"
            }
          },
          "required": [
            "starId",
            "status"
          ],
          "additionalProperties": false
        }
      },
      "confirm": {
        "type": "boolean",
        "description": "Required as true when the Mission already has saved results and this call would overwrite them"
      },
      "undoToken": {
        "type": "string",
        "description": "Token returned by an earlier save: restores the previous record instead of saving new results"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "open_observation_results",
  "kind": "act",
  "impl": "imperative",
  "description": "Selects a saved observation result and opens the human-facing Results screen. Without a missionId, uses the selected record or newest completed record. This tool does not recompute or modify results.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Optional saved Mission ID"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "capture_sky_snapshot",
  "kind": "act",
  "impl": "imperative",
  "description": "Captures the currently rendered Sky canvas as a PNG, stores it in the app's snapshot storage, and returns its metadata. An optional missionId links the image to an existing Mission. The tool does not return a large base64 image; use the returned browser download URL or the Snapshots screen.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Optional existing Mission ID to associate"
      },
      "download": {
        "type": "boolean",
        "description": "Trigger a browser download in addition to saving; defaults to true"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "list_sky_snapshots",
  "kind": "answer",
  "impl": "imperative",
  "description": "Lists saved Sky snapshot metadata in newest-first order. PNG blobs are not included.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 50,
        "description": "Maximum metadata records to return"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "get_sky_snapshot_metadata",
  "kind": "answer",
  "impl": "imperative",
  "description": "Returns one saved Sky snapshot's observation conditions and storage metadata without returning the PNG blob.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "snapshotId": {
        "type": "string",
        "description": "Saved snapshot ID"
      }
    },
    "required": [
      "snapshotId"
    ],
    "additionalProperties": false
  }
}

{
  "name": "propose_plan",
  "kind": "act",
  "impl": "imperative",
  "description": "Stages a ghost plan proposal for human review without creating a Mission. The proposal lists one item per star; the human accepts or rejects items on the Plan screen, and commit_proposal materializes the accepted subset into a real Mission. Proposing again replaces the pending proposal.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dateTime": {
        "type": "string",
        "description": "ISO 8601 observation date and time; a value without an offset is interpreted in the site's timeZone"
      },
      "maxMagnitude": {
        "type": "integer",
        "minimum": 1,
        "maximum": 4,
        "description": "Faintest magnitude allowed for targets"
      },
      "starIds": {
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "type": "string"
        },
        "description": "One to five star IDs, e.g. returned by predict_visible_stars"
      }
    },
    "required": [
      "dateTime",
      "maxMagnitude",
      "starIds"
    ],
    "additionalProperties": false
  }
}

{
  "name": "commit_proposal",
  "kind": "act",
  "impl": "imperative",
  "description": "Materializes the pending proposal's accepted items into a real Mission via the normal creation path (immutable from then on). Pass acceptedStarIds to commit a subset, or omit to commit the items currently marked accepted.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "acceptedStarIds": {
        "type": "array",
        "minItems": 1,
        "maxItems": 5,
        "items": {
          "type": "string"
        },
        "description": "Subset of the proposal's star IDs to commit (defaults to the accepted items)"
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "plan_stale",
  "kind": "answer",
  "impl": "imperative",
  "description": "Reports whether the pending proposal's assumptions still hold: it compares the site and observation dateTime the proposal was computed against with the current ones. A stale proposal's per-star predictions may no longer be accurate.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "get_sky_conditions",
  "kind": "answer",
  "impl": "imperative",
  "description": "Fetches live cloud cover (total and per layer) and visibility for the current observation site from Open-Meteo, plus a 0-100 stargazing score. Advisory only: weather is not part of the geometric visibility prediction and the tool fails cleanly when the service is unreachable.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  }
}

{
  "name": "compare_dark_sky_sites",
  "kind": "act",
  "impl": "imperative",
  "description": "Fetches Open-Meteo cloud cover and visibility for the current site plus reference dark-sky sites (or a caller-provided list of 2-8 sites), scores each for stargazing, and reports the clearest one. Sites that fail are reported individually instead of failing the whole comparison.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sites": {
        "type": "array",
        "minItems": 2,
        "maxItems": 8,
        "description": "Optional site list; defaults to the current site plus reference dark-sky locations",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "latitude": {
              "type": "number",
              "minimum": -90,
              "maximum": 90
            },
            "longitude": {
              "type": "number",
              "minimum": -180,
              "maximum": 180
            }
          },
          "required": [
            "name",
            "latitude",
            "longitude"
          ],
          "additionalProperties": false
        }
      }
    },
    "additionalProperties": false
  }
}

{
  "name": "generate_observation_guide",
  "kind": "act",
  "impl": "imperative",
  "description": "Prepares a print-ready Observation Guide using the Mission creation-time site, date, and fixed star predictions. It includes a deterministic Mission Sky Snapshot as inline SVG and generates a PDF directly in the browser. The tool does not return the PDF binary to the Agent; it starts a browser download, while the Guide screen also offers Print / Save as PDF.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "missionId": {
        "type": "string",
        "description": "Existing Mission ID"
      },
      "title": {
        "type": "string",
        "minLength": 1,
        "maxLength": 80,
        "description": "Optional guide title"
      },
      "durationMinutes": {
        "type": "integer",
        "minimum": 5,
        "maximum": 180,
        "description": "Optional observation duration"
      },
      "timeZone": {
        "type": "string",
        "description": "Optional IANA time zone for printed time"
      }
    },
    "required": [
      "missionId"
    ],
    "additionalProperties": false
  }
}