Skip to main content
Glama

stack_stats

Read-only

Measure how much a site changed across its passes, as numbers.

The quantitative counterpart to ``change_composite`` / ``timescan``: those
return a picture of *where* change is, this returns the *how much*. Pass the
STAC URLs of a site's passes (2 or more, any order); they are co-registered
onto one shared grid and reduced to a per-pass statistics series plus a net
baseline-to-latest record — mean/median/spread of each pass, the signed
decibel change against the pass before it, the fraction of ground that moved
past ``change_threshold_db``, and that fraction as an **area in km²**.

Change is always reported in decibels (a ratio of backscatter is a difference
on the log scale). The default ``crs="utm"`` puts the grid in the site's UTM
zone so every cell covers the same ground and the area figures mean
something; pass ``crs="EPSG:4326"`` for a lon/lat grid, and the areas come
back ``None`` rather than wrong. ``extent="intersection"`` (the default)
compares only ground every pass covers; ``"union"`` keeps all of it and
compares per cell where two passes overlap. ``bbox`` (lon/lat
``[min_lon, min_lat, max_lon, max_lat]``) narrows the measurement to a
sub-area, e.g. one facility inside the scene.

``blocks=N`` adds the *where* to the *how much*: the scene is cut into an
N x N grid (6 is a good default; 0, the default, skips it) and the extra
``spatial`` key reports each block's own net change, a compass label and
lon/lat centre to locate it by, and the consecutive pair of passes that
block moved most between — plus ``peak_block`` and an ASCII ``grid_text``
heat-map of the net change. Ask for it whenever the question is *where on
this site* something happened, or when a scene-wide mean looks small but the
picture from ``change_composite`` shows an obvious hot spot: a change
confined to one corner is averaged away scene-wide and stands out per block.

``block_series=True`` (which needs ``blocks``) keeps each block's *whole*
pass-to-pass sequence rather than only its peak interval, so a block that
drifted a little every pass reads differently from one that jumped once and
held. It is the largest payload this tool emits — ``blocks`` × ``blocks`` ×
(passes − 1) records — so ask for it only when the *shape* of the history is
the question, not the size of the change.

``speckle_filter="boxcar"`` or ``"lee"`` averages **speckle** down before
anything is measured. Speckle is not sensor noise: it is the interference
pattern coherent illumination makes on rough ground, and on single-look
imagery it scatters as widely as its own mean — so on a quiet site an
unfiltered per-cell decibel delta is mostly interference rather than change.
``"boxcar"`` averages every window (most variance removed, blind to the edges
it averages across); ``"lee"`` averages only where a window is no more
variable than speckle alone explains, so edges and bright points survive.
Reach for it when the change you are looking for is small, or when the
numbers look noisy against a picture that looks quiet; leave it off when the
question is about *fine* structure, because what it spends is resolution — a
``speckle_window``-cell window (odd, 5 by default) makes each cell report
ground that many cells across. The returned ``caveats`` say so, so a quoted
figure carries the trade with it.

Refuses to mix polarizations (HH and VV are not comparable). **No model is
called** — this is arithmetic over streamed COG overviews, so the numbers are
reproducible and safe to quote. Read the ``caveats`` before interpreting
them: Umbra's open products are not radiometrically calibrated, so a decibel
value is relative to the same ground on another date, and look geometry moves
backscatter too.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "urls": "<urls>"
    },
    "name": "stack_stats"
  }
}

Input Schema

NameRequiredDescriptionDefault
crsNoutm (default) grids in the site UTM zone so areas are km². EPSG:4326 returns areas as null.utm
bboxNoOptional WGS84 [min_lon, min_lat, max_lon, max_lat] sub-area inside the scene.
urlsYesSTAC JSON URLs or item ids of at least two passes. Any order. Mixed polarizations are refused.
assetNoProduct to measure. Default GEC.GEC
blocksNoN cuts the scene into an N by N grid of where change sits. 0 (default) skips it.
extentNointersection (default) keeps ground every pass covers. union keeps the full footprint.intersection
max_sizeNoOverview size cap in pixels for the co-registered grid. Default 512.
block_seriesNoWith blocks, return every pass-to-pass record per block, not only the peak. Default false.
speckle_filterNoboxcar or lee, to average speckle before measuring. Omit to leave pixels unfiltered.
speckle_windowNoCell window for speckle_filter. Default 5. When a filter is set, an even value or one below 3 raises.
change_threshold_dbNoAbsolute decibel change that counts as moved ground. Default 3.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changed
    • addedInput schema / properties / asset / description
      Added value: +"Product to measure. Default GEC."
    • addedInput schema / properties / bbox / description
      Added value: +"Optional WGS84 [min_lon, min_lat, max_lon, max_lat] sub-area inside the scene."
    • addedInput schema / properties / block_series / description
      Added value: +"With blocks, return every pass-to-pass record per block, not only the peak. Default false."
    • addedInput schema / properties / blocks / description
      Added value: +"N cuts the scene into an N by N grid of where change sits. 0 (default) skips it."
    • addedInput schema / properties / change_threshold_db / description
      Added value: +"Absolute decibel change that counts as moved ground. Default 3."
    • addedInput schema / properties / crs / description
      Added value: +"utm (default) grids in the site UTM zone so areas are km². EPSG:4326 returns areas as null."
    • addedInput schema / properties / extent / description
      Added value: +"intersection (default) keeps ground every pass covers. union keeps the full footprint."
    • addedInput schema / properties / max_size / description
      Added value: +"Overview size cap in pixels for the co-registered grid. Default 512."
    • addedInput schema / properties / speckle_filter / description
      Added value: +"boxcar or lee, to average speckle before measuring. Omit to leave pixels unfiltered."
    • addedInput schema / properties / speckle_window / description
      Added value: +"Cell window for speckle_filter. Default 5. When a filter is set, an even value or one below 3 raises."
    • addedInput schema / properties / urls / description
      Added value: +"STAC JSON URLs or item ids of at least two passes. Any order. Mixed polarizations are refused."
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations only supply readOnlyHint, and the description adds substantially beyond that: no model is called (arithmetic over streamed COG overviews), results are reproducible and safe to quote, polarizations are refused when mixed, payload size for block_series is quantified, and Umbra products are flagged as not radiometrically calibrated so decibel values are only relative. It also states that areas become null rather than wrong under EPSG:4326, which is exactly the kind of silent-failure disclosure annotations cannot carry.

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?

Well front-loaded — the one-line thesis precedes all detail, and each paragraph is scoped to one parameter family with backticked names as anchors. It is nonetheless long (~700 words), and the speckle physics explanation and the restated caveats passage could be trimmed without losing decision-relevant information.

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 11-parameter tool with a real output schema, the description covers the parts that schema cannot: cross-parameter dependencies (block_series requires blocks), failure modes, interpretability limits, and payload trade-offs. Nothing an agent needs to call this correctly or to warn a user about the numbers is missing.

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

Parameters5/5

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

Schema coverage is already 100%, so the baseline is 3, but the description adds real meaning on top: why crs='utm' matters (equal-area cells make km² figures meaningful), how extent intersection vs union differ in comparison semantics, what blocks=N actually produces (spatial key, compass label, centre, peak pair, peak_block, grid_text), and the resolution cost of speckle_window. This goes well past restating field descriptions.

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 and resource ('Measure how much a site changed across its passes, as numbers') and immediately positions itself against named siblings: change_composite/timescan return 'where', this returns 'how much'. An agent can route between them without opening either 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?

Explicit when-to-use guidance for every optional branch: ask for blocks 'whenever the question is where on this site', block_series 'only when the shape of the history is the question', speckle_filter 'when the change you are looking for is small' and leave it off for fine structure. It also states the refusal case (mixed polarizations) and the interpretation precondition (read caveats first).

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.