Skip to main content
Glama

search_catalog

Read-only

Search Umbra's catalog and return compact context cards.

Filters (all optional, combine freely): ``bbox`` as
``[min_lon, min_lat, max_lon, max_lat]`` in WGS84 degrees; ``intersects`` as
a GeoJSON object (a ``Point``, ``Polygon``, or ``MultiPolygon``, or a
``Feature`` / ``FeatureCollection`` wrapping one; a point matches footprints
that contain it) to keep only footprints
intersecting it -- a tighter spatial filter than the rectangular ``bbox``,
and mutually exclusive with ``bbox`` / ``place``; ``place`` as a
free-text name geocoded to a bbox; ``area`` as a substring of the Umbra
task (site) name (set ``fuzzy`` to match it loosely -- word-order- and
punctuation-independent and typo-tolerant, resolved deterministically with
no model call, so ``"beet piler"`` still reaches ``"Beet Piler - ND"`` and
``"utah centerfield"`` still reaches ``"Centerfield,
Utah"``). When ``area`` matches no task and ``bbox``, ``intersects``, and
``place`` are omitted, it is geocoded and that footprint is searched; the
result then adds ``matched_by`` (``geocode``), ``resolved_place``, and
``resolved_bbox``. A name Nominatim does not know sets ``hint`` to
``no task named X; try place= or bbox=``. When geocoding is busy (the
Nominatim gate, or the public host's quick outbound pool) or
unreachable, ``hint`` is ``no task named X; geocoding was unavailable``
and ``resolved_area`` is the ``area`` that was tried. A task-name hit
adds nothing. Set ``semantic``
instead to treat ``area`` as a plain-language
*description* of a site whose name you don't know and resolve it to the
closest task names by *meaning* via the prebuilt embedding index, so
``"grain storage north dakota"`` reaches ``"Beet Piler - ND"`` -- a query
that shares no word with the label, which ``fuzzy`` cannot and should not
fake; ``semantic`` and ``fuzzy`` are mutually exclusive, and the resolved
task name is returned as ``resolved_area`` with the ranked candidates in
``semantic_matches`` so you can audit and retry with a different one, and
``min_score`` -- a cosine threshold in ``[0, 1]`` -- drops weak aliases, so
a description that matches nothing confidently returns an empty result
rather than an arbitrary top pick); ``start``/``end`` as acquisition-date
bounds -- an ISO
``YYYY-MM-DD`` date, a bare year/month (``2024``, ``2024-03``), or a
relative expression (``today``, ``yesterday``, ``3 months ago``,
``last month``), resolved deterministically with no model call;
``products`` to restrict to product types
(any of GEC, SICD, SIDD, CPHD); the SAR acquisition-property filters
``polarizations`` (keep items exposing any of these, e.g. ``["VV"]`` -- the
filter that keeps a change comparison like-with-like), ``min_incidence`` /
``max_incidence`` (view incidence-angle bounds in degrees) and
``max_resolution`` (keep items at least this fine, in metres) -- each a hard
predicate that excludes items missing that metadata; ``canonical`` to keep
the preferred copy of a collect Umbra republished under another prefix
(``True``), only the other copies (``False``), or every item when omitted;
``limit`` to cap
results (on the public host a value above 100 is clamped to 100 and the
result includes ``note``; the argument and its default are unchanged);
``max_per_task`` to cap items per site (use 1 for a one-pin-per-site
overview).

``local`` selects the backend: leave it unset to use the on-disk index when
present (instant) and fall back to a live S3 walk otherwise. When the server
is configured with a Canopy token (``$UMBRA_CANOPY_TOKEN``), the search runs
against Umbra's authenticated commercial archive instead and ``source`` is
reported as ``"canopy-archive"``. Returns the per-item context cards, not
full STAC JSON, to protect the context window; call ``get_item`` for one
item's full metadata.

Prefer ``fuzzy=True`` (or :func:`find_repeat_sites`) when ``area`` shares
words with a task name; that path is deterministic and needs no key.
``semantic=True`` is only for a description that shares **no** tokens with
the label. It requires a task-embedding index built ahead of time with
``umbra semantic build`` and a user-supplied embedding key (``OPENAI_API_KEY``,
optionally ``OPENAI_BASE_URL`` / ``UMBRA_EMBED_MODEL``); it raises a helpful
setup error otherwise, so it never runs implicitly. The only model call is
turning ``area`` into a vector -- the resolved search over the chosen backend
stays fully deterministic.

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

Input Schema

NameRequiredDescriptionDefault
endNoInclusive acquisition-date upper bound. Same grammar as start.
areaNoTask-name substring. If it matches no task and bbox, intersects, and place are omitted, it is geocoded. With semantic, a plain-language description.
bboxNoWGS84 [min_lon, min_lat, max_lon, max_lat]. When set, place is not geocoded.
fuzzyNoLoose task-name match for area (word order, punctuation, typos). No model. Cannot be combined with semantic.
limitNoMaximum cards. Default 20. The public host clamps a value above 100 to 100 and adds note.
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.
placeNoFree-text place name. Geocoded to a bbox only when bbox is omitted.
startNoInclusive acquisition-date lower bound: ISO date, bare year or month, or a relative expression such as 3 months ago.
productsNoKeep items that expose one of these types (GEC, CSI, SIDD, SICD, CPHD). A collection id such as umbra-gec or umbra-open-data raises; use the product type.
semanticNoResolve area by embedding similarity. Needs a semantic index and an embedding key. Cannot be combined with fuzzy.
canonicalNoTrue keeps the preferred copy of a republished collect; False keeps only the other copies. Omit to keep every item.
min_scoreNoCosine cutoff in [0, 1] for semantic matches. Scores below it are dropped.
intersectsNoOne 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.
max_per_taskNoMaximum items per task (site). 1 is one pin per site.
max_incidenceNoMaximum incidence angle in degrees. Items missing incidence are dropped.
min_incidenceNoMinimum incidence angle in degrees. Items missing incidence are dropped.
polarizationsNoKeep items exposing any listed polarization, such as VV. Missing values are dropped.
max_resolutionNoKeep items this fine or finer, in metres. Items missing resolution are dropped.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed18 schema fields changed
    • addedInput schema / properties / area / description
      Added value: +"Task-name substring. If it matches no task and bbox, intersects, and place are omitted, it is geocoded. With semantic, a plain-language description."
    • addedInput schema / properties / bbox / description
      Added value: +"WGS84 [min_lon, min_lat, max_lon, max_lat]. When set, place is not geocoded."
    • addedInput schema / properties / canonical / description
      Added value: +"True keeps the preferred copy of a republished collect; False keeps only the other copies. Omit to keep every item."
    • addedInput schema / properties / end / description
      Added value: +"Inclusive acquisition-date upper bound. Same grammar as start."
    • addedInput schema / properties / fuzzy / description
      Added value: +"Loose task-name match for area (word order, punctuation, typos). No model. Cannot be combined with semantic."
    • addedInput schema / properties / intersects / description
      Added value: +"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: +"Maximum cards. Default 20. The public host clamps a value above 100 to 100 and adds note."
    • 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: +"Maximum incidence angle in degrees. Items missing incidence are dropped."
    • addedInput schema / properties / max_per_task / description
      Added value: +"Maximum items per task (site). 1 is one pin per site."
    • addedInput schema / properties / max_resolution / description
      Added value: +"Keep items this fine or finer, in metres. Items missing resolution are dropped."
    • addedInput schema / properties / min_incidence / description
      Added value: +"Minimum incidence angle in degrees. Items missing incidence are dropped."
    • addedInput schema / properties / min_score / description
      Added value: +"Cosine cutoff in [0, 1] for semantic matches. Scores below it are dropped."
    • addedInput schema / properties / place / description
      Added value: +"Free-text place name. Geocoded to a bbox only when bbox is omitted."
    • addedInput schema / properties / polarizations / description
      Added value: +"Keep items exposing any listed polarization, such as VV. Missing values are dropped."
    • addedInput schema / properties / products / description
      Added value: +"Keep items that expose one of these types (GEC, CSI, SIDD, SICD, CPHD). A collection id such as umbra-gec or umbra-open-data raises; use the product type."
    • addedInput schema / properties / semantic / description
      Added value: +"Resolve area by embedding similarity. Needs a semantic index and an embedding key. Cannot be combined with fuzzy."
    • addedInput schema / properties / start / description
      Added value: +"Inclusive acquisition-date lower bound: ISO date, bare year or month, or a relative expression such as 3 months ago."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only supply readOnlyHint=true; the description goes far beyond by disclosing backend selection (on-disk index vs live S3 walk), that a Canopy token reroutes to the commercial archive with `source="canopy-archive"`, that public-host `limit` is clamped at 100 with a `note`, that SAR predicates hard-drop items missing metadata, the specific `hint` strings emitted on geocode failure/unavailability, and that weak semantic matches return empty rather than an arbitrary top hit.

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 lead sentence is front-loaded, but the body is a single sprawling semicolon-and-parenthesis run-on with deep nesting (the `intersects`/`area`/`semantic` clause alone spans dozens of lines) and RST double-backtick markup that impedes scanning. Content is repeated: fuzzy/semantic mutual exclusivity, `min_score` behavior, and the "no model call" determinism claim each appear two or three times.

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 an 18-parameter, no-required-arg tool with three resolution modes, two backends, and a token-gated archive, the description covers the decision space an agent needs: which mode to pick, what each mode costs, what errors look like, and where to go for full item metadata. An output schema exists, so the additional return-field explanation is surplus rather than a gap.

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 100%, so the baseline is 3, but the prose adds real meaning beyond the schema: the conditional `area` geocoding fallback and its returned `matched_by`/`resolved_place`/`resolved_bbox` companions, the cosine-threshold behavior of `min_score`, and the cross-parameter exclusion rules. It does not add syntax detail for every filter (e.g. accepted `products` values are only partly reconciled with the schema's list), so it falls short of a 5.

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?

Opens with a specific verb+resource: "Search Umbra's catalog and return compact context cards." It also draws the boundary against siblings by pointing to `get_item` for full STAC metadata and to `find_repeat_sites` / `fuzzy=True` for repeat-site lookups, so an agent can tell what this tool is and is not.

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?

Explicit routing rules: prefer `fuzzy=True` when `area` shares tokens with a task name; use `semantic=True` only when the description shares no tokens with the label; `fuzzy` and `semantic` are mutually exclusive; `intersects` is mutually exclusive with `bbox`/`place`; use `max_per_task=1` for a one-pin-per-site overview. It also states prerequisites (semantic index must be built, embedding key required, raises a setup error otherwise).

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.