Skip to main content
Glama

pick_change_interval

Read-only

Scan a site's whole series and name the two passes worth narrating.

The deterministic first half of the "watch a site over time" story, and the
step that turns a wall of passes into an answer. Given the STAC URLs of a
site's passes (2 or more, any order), it co-registers them into a
``to_stack`` cube, reduces it with ``stack_stats``, and returns the *one*
consecutive pass-pair whose measured change stands **furthest clear of the
speckle detection floor** — the pair a reader should look at first. No model
is called: a number picks the frames (the determinism boundary applied to
frame selection), so the choice is reproducible and safe
to quote.

Why this exists as its own tool: ``narrate_change`` reads a *pair* of passes,
but a site has many, and "which two?" is a measurement question, not a model
one — a picture past three dates encodes nothing a model can separate, so the
pair has to be chosen before the model is called. This answers it. The
returned ``urls`` are the two chosen passes in time order, ready to hand
straight to ``narrate_change`` (or ``change_composite`` to see them): the
two tools chain into scan → narrate with no server and no model in the
selection.

Returns ``selected_interval`` (the interval's ``earlier_id`` / ``later_id``,
their datetimes, the ``changed_fraction`` and signed ``mean_delta_db``, the
cube's ``false_alarm_fraction`` speckle floor, the ``excess`` of the change
over that floor, and ``stands_clear`` — whether the change cleared the floor
by a usable margin), ``urls`` (the earlier then the later pass's STAC URL),
and the license/attribution. When ``stands_clear`` is false the series' own
largest change is still inside the speckle, so the pair is offered but the
reader is warned the difference may be interference rather than change.

``selected_interval`` is ``None`` (and ``urls`` empty) when the series has
fewer than two comparable passes or no interval reported any change — there
is no pair to narrate. ``crs="utm"`` (the default) grids the cube in the
site's UTM zone so the change fractions weigh equal ground; ``max_size`` and
``change_threshold_db`` match ``stack_stats``. Refuses to mix polarizations
(HH vs VV are not comparable). Requires the ``load`` extra.

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

Input Schema

NameRequiredDescriptionDefault
crsNoutm (default) grids in the site UTM zone so change fractions weigh equal ground.utm
urlsYesSTAC JSON URLs or item ids of at least two passes. Any order. Mixed polarizations are refused.
assetNoProduct to measure. Default GEC.GEC
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.
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. Changed6 schema fields changed
    • addedInput schema / properties / asset / description
      Added value: +"Product to measure. Default GEC."
    • 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 change fractions weigh equal ground."
    • 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 / 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.2/5.0
Behavior3/5

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

The readOnlyHint=true annotation already covers the safety profile, so the description is not contradicted and supports it by declaring no model is called and that selection is deterministic and reproducible. It further discloses the polarization refusal, the load-extra requirement, and the stands_clear warning path. However, much of this behavioral detail (return fields, None conditions) sits in territory the output schema could carry, so the marginal behavioral value over structured fields is moderate rather than exceptional.

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 definition is front-loaded with a one-line purpose and organized into rationale, chaining, returns, and edge cases, which is easy to scan. It is on the long side, with several sentences re-describing return fields already present in the output schema and some repetition of the 'no model / determinism' idea. Most sentences earn their place, but trimming the returns section would sharpen 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 six-parameter analysis tool with an output schema and only a readOnlyHint annotation, the description covers inputs, selection logic, failure modes (fewer than two passes, no change reported, mixed polarizations), and the meaning of stands_clear. Nothing an agent needs in order to call it correctly and interpret the result is missing. The return-value detail is somewhat redundant given the output schema but does not detract from completeness.

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%, including documented defaults for crs, asset, extent, max_size, and change_threshold_db, so the baseline is 3. The description adds a little meaning by stating that max_size and change_threshold_db match stack_stats and that crs='utm' exists so change fractions weigh equal ground, but it largely restates what the schema already says. This is a modest addition, not a substantial one.

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: 'Scan a site's whole series and name the two passes worth narrating.' It then explicitly positions the tool against siblings, explaining that narrate_change reads a pair while this tool answers which pair, and pointing to change_composite for viewing. An agent can distinguish it from narrate_change, change_composite, and 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?

The description gives explicit routing: use this when a site has many passes and the pair must be chosen before a model is called, then hand the returned urls to narrate_change. It names the alternative (change_composite) for seeing the frames and states the precondition (two or more comparable passes) plus the outcome when it fails. The chaining relationship is spelled out rather than inferred.

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.