Skip to main content
Glama

find_repeat_sites

Read-only

Rank sites imaged more than once, before a change tool is pointed at one.

Use this when the site is not already known. Each site's ``hrefs`` are that
site's STAC URLs, oldest first, ready for ``pick_change_interval``,
``change_composite``, or ``stack_stats``. Prefer this, or
``search_catalog(area=..., fuzzy=True)``, over ``semantic=True`` when the
name shares words with a task. No model is called.

Argument reference (ranking, recency, cadence, baseline, return fields):
https://umbra-py.space/find-repeat-sites/

Filters bound which acquisitions are ranked. ``bbox`` is WGS84
``[min_lon, min_lat, max_lon, max_lat]``. ``intersects`` is one GeoJSON
Point, or a Polygon or MultiPolygon (or a Feature, FeatureCollection, or
GeometryCollection wrapping those). A point matches footprints that
contain it. It cannot be combined with ``bbox`` or ``place``. ``place`` is geocoded
only when ``bbox`` is omitted. ``area`` is a task-name substring;
``fuzzy=True`` is a deterministic loose match. When ``area`` matches no
task and ``bbox``, ``intersects``, and ``place`` are omitted, it is
geocoded. The result then adds ``matched_by`` (``geocode``) plus the
resolved place and bbox. A name Nominatim does not know, and a geocoder
that is busy or unreachable, set ``hint`` and return no sites
(``resolved_area`` is the ``area`` that was tried). A task-name hit adds
nothing. ``start`` / ``end`` bound
which passes enter the pool (ISO date, bare year or month, or a relative
expression). ``products`` is any of GEC, CSI, SIDD, SICD, CPHD.
``polarizations``, ``min_incidence``, ``max_incidence``, and
``max_resolution`` (metres) drop passes missing that field.

``top`` (default 20) is how many sites to return. ``min_passes`` (default
2) is the minimum depth: comparable passes when ``rank_by`` is
``comparable``, otherwise raw dated passes. ``rank_by`` is ``passes``
(default), ``comparable`` (largest same-polarization subset), ``recency``
(newest pass), ``span`` (first to last), or ``cadence`` (tightest median
gap). For the three temporal orders, ``min_passes`` still counts raw
passes.

``active_since`` / ``active_before`` select sites by newest pass;
``first_since`` / ``first_before`` select by earliest pass. Those keep
each survivor's full history, unlike ``start`` / ``end``, which truncate
the pool. ``max_revisit_days`` caps the worst gap and
``median_revisit_days`` caps the median gap. ``min_span_days`` /
``max_span_days`` bound the first-to-last span. A non-positive cadence or
span raises ``ValueError``. With ``rank_by="comparable"`` the cadence and
span filters use that subset. A bare year or month on a ``*_before``
bound includes the whole period.

``limit`` (default 500) sizes only a live or Canopy pool. A local index
ranks each task over the whole index and ignores ``limit``. ``local``
matches ``search_catalog``: unset uses the index when present. A Canopy
token (``$UMBRA_CANOPY_TOKEN``) draws the pool from the commercial
archive, and ``local=True`` cannot be combined with it.

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": "find_repeat_sites"
  }
}

Input Schema

NameRequiredDescriptionDefault
endNoPool filter: inclusive upper bound on which passes are counted. Same grammar as start.
topNoMaximum sites to return, best first. Default 20.
areaNoPool filter: task-name substring. With fuzzy, a loose token match. If it matches no task and bbox, intersects, and place are omitted, it is geocoded.
bboxNoPool filter: WGS84 [min_lon, min_lat, max_lon, max_lat]. When set, place is not geocoded.
fuzzyNoLoose task-name match for area. No model call.
limitNoHow many acquisitions to pull for a live or Canopy ranking. Default 500. Ignored on a local index, which groups the whole index.
localNoTrue uses only the local index; False forces a live walk. Omit to use the index when present. True cannot be combined with a Canopy token.
placeNoPool filter: free-text place. Geocoded to a bbox only when bbox is omitted.
startNoPool filter: inclusive lower bound on which passes are counted. ISO date, bare year or month, or a relative expression.
rank_byNopasses (default), comparable, recency, span, or cadence. Unknown values raise ValueError.passes
productsNoPool filter: keep passes that expose one of these types (GEC, CSI, SIDD, SICD, CPHD). Case-insensitive.
intersectsNoPool filter: one GeoJSON Point, or a Polygon or MultiPolygon, optionally wrapped in a Feature, FeatureCollection, or GeometryCollection. A point matches footprints that contain it. Cannot be combined with bbox or place.
min_passesNoMinimum series depth. Default 2. Counts comparable passes when rank_by is comparable, otherwise raw dated passes.
first_sinceNoKeep sites whose earliest pass is on or after this date. Same grammar as start.
active_sinceNoKeep sites whose newest pass is on or after this date. Same grammar as start.
first_beforeNoKeep sites whose earliest pass is on or before this date. A bare year or month includes that whole period.
active_beforeNoKeep sites whose newest pass is on or before this date. A bare year or month includes that whole period.
max_incidenceNoPool filter: maximum incidence angle in degrees. Passes missing it are dropped.
max_span_daysNoDrop sites whose first-to-last span is longer than this many days. Non-positive raises. Uses the comparable series when rank_by is comparable.
min_incidenceNoPool filter: minimum incidence angle in degrees. Passes missing it are dropped.
min_span_daysNoDrop sites whose first-to-last span is shorter than this many days. Non-positive raises. Uses the comparable series when rank_by is comparable.
polarizationsNoPool filter: keep passes exposing any listed polarization. Missing values are dropped.
max_resolutionNoPool filter: keep passes this fine or finer, in metres. Missing resolution is dropped.
max_revisit_daysNoDrop sites whose worst revisit gap exceeds this many days. Non-positive raises. Uses the comparable series when rank_by is comparable.
median_revisit_daysNoDrop sites whose median revisit gap exceeds this many days. Non-positive raises. Uses the comparable series when rank_by is comparable.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed25 schema fields changed
    • addedInput schema / properties / active_before / description
      Added value: +"Keep sites whose newest pass is on or before this date. A bare year or month includes that whole period."
    • addedInput schema / properties / active_since / description
      Added value: +"Keep sites whose newest pass is on or after this date. Same grammar as start."
    • addedInput schema / properties / area / description
      Added value: +"Pool filter: task-name substring. With fuzzy, a loose token match. If it matches no task and bbox, intersects, and place are omitted, it is geocoded."
    • addedInput schema / properties / bbox / description
      Added value: +"Pool filter: WGS84 [min_lon, min_lat, max_lon, max_lat]. When set, place is not geocoded."
    • addedInput schema / properties / end / description
      Added value: +"Pool filter: inclusive upper bound on which passes are counted. Same grammar as start."
    • addedInput schema / properties / first_before / description
      Added value: +"Keep sites whose earliest pass is on or before this date. A bare year or month includes that whole period."
    • addedInput schema / properties / first_since / description
      Added value: +"Keep sites whose earliest pass is on or after this date. Same grammar as start."
    • addedInput schema / properties / fuzzy / description
      Added value: +"Loose task-name match for area. No model call."
    • addedInput schema / properties / intersects / description
      Added value: +"Pool filter: one GeoJSON Point, or a Polygon or MultiPolygon, optionally wrapped in a Feature, FeatureCollection, or GeometryCollection. A point matches footprints that contain it. Cannot be combined with bbox or place."
    • addedInput schema / properties / limit / description
      Added value: +"How many acquisitions to pull for a live or Canopy ranking. Default 500. Ignored on a local index, which groups the whole index."
    • addedInput schema / properties / local / description
      Added value: +"True uses only the local index; False forces a live walk. Omit to use the index when present. True cannot be combined with a Canopy token."
    • addedInput schema / properties / max_incidence / description
      Added value: +"Pool filter: maximum incidence angle in degrees. Passes missing it are dropped."
    • addedInput schema / properties / max_resolution / description
      Added value: +"Pool filter: keep passes this fine or finer, in metres. Missing resolution is dropped."
    • addedInput schema / properties / max_revisit_days / description
      Added value: +"Drop sites whose worst revisit gap exceeds this many days. Non-positive raises. Uses the comparable series when rank_by is comparable."
    • addedInput schema / properties / max_span_days / description
      Added value: +"Drop sites whose first-to-last span is longer than this many days. Non-positive raises. Uses the comparable series when rank_by is comparable."
    • addedInput schema / properties / median_revisit_days / description
      Added value: +"Drop sites whose median revisit gap exceeds this many days. Non-positive raises. Uses the comparable series when rank_by is comparable."
    • addedInput schema / properties / min_incidence / description
      Added value: +"Pool filter: minimum incidence angle in degrees. Passes missing it are dropped."
    • addedInput schema / properties / min_passes / description
      Added value: +"Minimum series depth. Default 2. Counts comparable passes when rank_by is comparable, otherwise raw dated passes."
    • addedInput schema / properties / min_span_days / description
      Added value: +"Drop sites whose first-to-last span is shorter than this many days. Non-positive raises. Uses the comparable series when rank_by is comparable."
    • addedInput schema / properties / place / description
      Added value: +"Pool filter: free-text place. Geocoded to a bbox only when bbox is omitted."
    • addedInput schema / properties / polarizations / description
      Added value: +"Pool filter: keep passes exposing any listed polarization. Missing values are dropped."
    • addedInput schema / properties / products / description
      Added value: +"Pool filter: keep passes that expose one of these types (GEC, CSI, SIDD, SICD, CPHD). Case-insensitive."
    • addedInput schema / properties / rank_by / description
      Added value: +"passes (default), comparable, recency, span, or cadence. Unknown values raise ValueError."
    • addedInput schema / properties / start / description
      Added value: +"Pool filter: inclusive lower bound on which passes are counted. ISO date, bare year or month, or a relative expression."
    • addedInput schema / properties / top / description
      Added value: +"Maximum sites to return, best first. Default 20."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond readOnlyHint=true, it discloses that no model is called, that geocode failure sets 'hint' and returns zero sites with resolved_area, that non-positive cadence/span raises ValueError, that a local index ignores limit while a live/Canopy pool honors it, and that local=True cannot be combined with a Canopy token. This is substantial operational context an agent could not infer from annotations.

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 critical routing information and the output contract ('hrefs' are STAC URLs, oldest first) are front-loaded, and paragraphs are grouped by concern (filters, ranking, site selection, pool sizing). It is dense for 25 parameters but nearly every sentence carries a distinct rule; the external documentation URL for ranking/return fields is the main thing that displaces in-description content.

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?

For a 25-parameter tool with a real output schema this is close to complete: it explains the pool-vs-site filter split, mutual exclusions, geocoding fallback, and error behavior. The remaining gap is that ranking semantics and return-field detail are delegated to a URL rather than described inline.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, but the description adds cross-parameter meaning the schema does not: start/end truncate the pool while active_*/first_* keep full history, min_passes counts comparable vs raw passes depending on rank_by, and a bare year/month on *_before includes the whole period. It stops short of covering return fields, deferring that to an external URL.

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 opening line names a specific verb and resource ('Rank sites imaged more than once') and immediately frames the tool's role relative to change tools ('before a change tool is pointed at one'). An agent can distinguish this from siblings like change_composite or stack_stats without opening any schema.

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?

It gives an explicit selection rule ('Use this when the site is not already known'), names concrete alternatives with arguments (search_catalog(area=..., fuzzy=True)), and names the downstream consumers (pick_change_interval, change_composite, stack_stats). It also excludes the semantic=True path under a stated condition.

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.