Skip to main content
Glama

SeekSat

Best pass

best_pass
Read-onlyIdempotent

Find the best upcoming pass(es) over a location, ranked by the rating seeksat.com shows ("what's the best pass tonight?"). Give satellite to rank that one satellite's passes. Omit it to scan: in visual mode (default) the popular satellites plus every satellite in CelesTrak's visual group (the brightest objects in the sky, about 160, many of them spent rocket bodies), over 72 hours by default (168 at most); in radio mode every satellite with known downlinks (about a thousand), optionally only those with a downlink in bands or of a kind in modes, over 24 hours by default (72 at most). A scan reports satellitesScanned, leaves out satellites whose orbital elements are more than 14 days old at the start (skippedStaleElements) and any pass more than 14 days from its satellite's elements, counts what else it skipped, and radio passes list the satellite's downlinks. Returns best (the top pass) plus a passes array of the top-ranked options, each tagged with its satellite. Each pass has rise/peak/set times (UTC, plus riseLocal etc. on the observer's clock), peak elevation, azimuths with compass words (direction), the range at the peak (peakRangeKm), duration, brightness (magnitude, lower is brighter; peakMagnitudeEstimated means no measured magnitude is known for it, so it is a cautious guess; most of the bright satellites have a measured one, and a Starlink still flying in its launch train uses a typical train brightness, a rule of thumb rather than a measurement), and when it can be seen by eye: visibleFrom/visibleUntil (null if never on that pass) plus leavesShadow/entersShadow when it appears or fades mid-sky. rating is the rating seeksat.com shows for the pass: { word (Poor, Fair, Good, Great, Excellent), bars (1-5), level (low, ok, good), reason }. In visual mode it is how much brighter than the faintest visible star the pass gets for skyType (headroomMag), stepped down for a cloudy forecast up to 4 days ahead, and no higher than Fair when the brightness is estimated; in radio mode it is the peak height, a bar lower for each 6 dB of extra path loss when the satellite is more than 2,000 km away at the peak (8,000 km costs two bars), and no higher than Fair when SatNOGS stations tried at least 3 times in 30 days and heard nothing (the result then carries the satellite's reception and receptionSource). captureProbability (0-1) is the chance a camera captures the pass: sky darkness, height, clear-sky odds and length, with brightness playing no part; quality is its old name, the same number. Rise and set are when it crosses minElevation, not the horizon. In visual mode rise and set are the part of the pass that can be seen, so they can start or end mid-sky, and peak, peakElevationDeg and direction.peak are the highest point of that part (the whole pass may climb higher). passUrl opens that pass on seeksat.com, from that place, to hand to the user. Visual passes rank by rating bars, then a known brightness before an estimated one, then headroomMag, then captureProbability; the cloud forecast for the location is folded in where it reaches (cloudCoverPct at the peak; weather says whether a forecast was used). Radio scans rank satellites with a downlink a hobby receiver can tune (30 MHz to 1 GHz) ahead of the rest unless bands is given, then by rating bars, then how recently SatNOGS stations heard the satellite (last 48 hours, 7 days, 30 days, unknown, probably silent), then peak elevation, then captureProbability. A probably silent satellite (SatNOGS stations tried at least 3 times in 30 days and heard nothing) rates no higher than Fair; unknown is never held down. Radio rows carry the satellite's reception (its best downlink's). Downlinks carry reception from SatNOGS Network observations when known: { state (heard, silent: stations tried and heard nothing, or unknown: no observations, never a sign it is dead), heardLast48h, heardLast7d, heardLast30d, failedLast30d, lastHeard }, listed most recently heard first; receptionSource names the source (CC BY-SA 4.0). An empty result comes with a note saying why. Set chart:true to also render the winning pass's sky chart in this same call.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "best_pass"
  }
}

Input Schema

NameRequiredDescriptionDefault
latNoobserver latitude in decimal degrees, north positive (-90 to 90). Give it with lon, or give location instead.
lonNoobserver longitude in decimal degrees, east positive and west negative (-180 to 180).
modeNo"visual" (default): naked-eye passes, sunlit while the sky is dark; "radio": every line-of-sight pass, day or night.
bandsNoradio scan only: keep satellites with a downlink in these bands: hf (3-30 MHz), wx (137 MHz weather), 2m (144-148 MHz), 70cm (420-450 MHz), l (1-2 GHz), s (2-4 GHz), other. Default: any band.
chartNotrue to also render the winning pass's polar sky chart (PNG) and return it in this same result. Default false.
limitNohow many ranked passes to return, 1 to 20. Default 3.
modesNoradio scan only: keep satellites with a downlink of one of these kinds, matched on its mode or label, e.g. ["fm", "apt", "sstv"]. Default: any.
minElevNoold name for minElevation; still accepted.
skyTypeNohow dark the observer's sky is, for the visual rating as on seeksat.com: "city" (stars to magnitude 3.5), "suburban" (stars to magnitude 4.5), "rural" (stars to magnitude 5.5), "dark" (stars to magnitude 6.5). Default "suburban".
locationNowhere the observer is, when lat and lon are not given (they win when both are): a Maidenhead grid square (EN52, EN52ve, EN52ve12), coordinates in any common form ("41.88, -87.63", "41.88N 87.63W", "41°52'48"N 87°37'48"W", a Google Maps link or geo: URI), all read locally, or a place name (city, address, landmark) looked up with OpenStreetMap. Prefer lat and lon, or a grid square, when you have them: a place name is a network lookup.
satelliteNoNORAD catalog number (as a number or a string) or a name, e.g. 25544, "25544" or "iss". Omit to scan: visual mode scans the popular satellites plus CelesTrak's visual group, radio mode every satellite with known downlinks.
windowHoursNohow far ahead to look, in hours, up to 240 (10 days). Default 72. With no satellite named, a visual scan stops at 168, and a radio scan defaults to 24 and stops at 72.
minElevationNolowest elevation that counts: a pass must climb above it, and rise and set are when it crosses it, in degrees above the horizon (0 to 90). Default 10.
minElevationDegNoold name for minElevation; still accepted.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.2/5.0
Behavior5/5

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

Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior. The description adds extensive behavioral detail beyond that: what satellites are scanned, stale-element exclusions, ranking tiebreakers, null semantics for visibility, cloud forecast integration, and reception source licensing.

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

Conciseness2/5

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

The description is one very long, dense paragraph packed with nearly every implementation detail. While front-loaded with purpose, it is substantially overlong and hard to scan, and could be structured more concisely for an agent parsing it.

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?

For a complex 14-parameter tool with no output schema, the description thoroughly documents return shape, ranking behavior, null handling, and edge cases. It leaves little ambiguity about what results look like or how they are ordered.

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 explains all 14 parameters with formats, defaults, and limits. The description largely restates or elaborates on those same semantics, adding little parameter meaning that is not already structured in 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 and resource: find the best upcoming pass(es) over a location, ranked by seeksat.com rating. It distinguishes scan mode from single-satellite mode and explains what visual vs radio mode return, so an agent can tell what the tool does without opening the schema.

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

Usage Guidelines4/5

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

Provides clear context for when to omit satellite to scan, how visual and radio modes differ, and default time windows. It does not explicitly name rival sibling tools like find_passes or next_visible_pass, so the when-to-use guidance is strong but not fully comparative.

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