Skip to main content
Glama

stack_provenance

Read-only

Check whether a site's passes are one measurement, before measuring them.

``stack_stats`` refuses a selection whose rasters were made by *different*
``umbra convert`` settings — a calibrated pass differenced against an
uncalibrated one puts the difference between two conversions on the time
axis and reports it as change on the ground. This is the question that
refusal answers, asked ahead of it: it reads each acquisition's ``UMBRA_*``
conversion record straight from its raster header (kilobytes per pass, no
pixels, no co-registration) and groups the selection by what its pixel
values *are*.

Returns ``agrees`` (whether ``stack_stats`` would accept the selection),
``groups`` largest-first — each with the conversion ``record`` its members
share, their ``item_ids`` and the ``hrefs`` to re-run on — plus ``shared``
(the record they all agree on) when they agree, ``refusal`` (verbatim the
error ``stack_stats`` would raise) when they do not, and ``unreadable`` for
any source that could not be opened at all, which is an incomplete answer
rather than a mixed one.

Reach for it in two situations. **After** a ``stack_stats`` call fails with
a provenance refusal: ``groups[0]["hrefs"]`` is the largest set of passes
that *do* agree, so re-running ``stack_stats`` on those is a measurement
rather than a guess — the refusal itself cannot name that subset. And
**before** measuring a long series you did not assemble yourself, since the
check costs a header read per pass and saves the whole cube when the answer
is no.

A series of Umbra's published products as they ship (the common case) agrees
trivially: every pass reads as ``"(unrecorded)"``, which is one value, so
``agrees`` is true and ``shared`` is empty. **No model is called.**

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_provenance"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlsYesSTAC JSON URLs or item ids of at least two passes whose raster headers are compared.
assetNoProduct whose raster header is read. Default GEC.GEC

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / properties / asset / description
      Added value: +"Product whose raster header is read. Default GEC."
    • addedInput schema / properties / urls / description
      Added value: +"STAC JSON URLs or item ids of at least two passes whose raster headers are compared."
  2. First observed

TDQS

A4.2/5.0
Behavior3/5

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

Annotations declare readOnlyHint=true and the description is consistent, adding real context: header-only reads (kilobytes per pass, no pixels, no co-registration), no model invoked, and the unreadable-vs-mixed distinction. However, the return-shape prose largely restates what the output schema already documents, and the cost claim ('a header read per pass') is the main non-annotation behavioral detail.

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?

Front-loaded with a one-sentence purpose, then refusal rationale, then return shape, then the two usage cases. Dense and well ordered, though the reStructuredText double-backtick markup adds visual noise and the return-value paragraph could be trimmed given an output schema exists.

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 moderately complex grouping tool it covers purpose, the failure mode it prevents, the meaning of agrees/shared/refusal/unreadable, cost, and the important edge case that published products trivially agree as '(unrecorded)'. An agent has everything needed to call and interpret it correctly.

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 coverage is 100%, so both urls and asset are already documented in the schema, including the GEC default. The description clarifies that URLs are what gets grouped and that hrefs are re-run targets, but never explains the asset parameter's effect on which header is read — baseline 3 applies.

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 concrete verb and resource ('Check whether a site's passes are one measurement') and immediately scopes it as a pre-flight for stack_stats. The relationship to the sibling — it answers the same question the refusal answers, but ahead of time — makes the tool distinguishable at a glance.

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?

Two explicit trigger situations are named: after a stack_stats provenance refusal, and before measuring a long series you did not assemble yourself. It even explains why the alternative (reading the refusal) is insufficient — the refusal cannot name the agreeing subset — which is genuinely routing information.

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.