Skip to main content
Glama

get_item

Read-only

Return the full context card for one item.

``url`` is the JSON URL of an open-data STAC sidecar, a GEC/SICD (or other
product) filename such as ``2025-05-17-17-43-46_UMBRA-08_GEC.tif``, or the
acquisition stem ``2025-05-17-17-43-46_UMBRA-08``. A filename or stem is
resolved through the local catalog index: the stem is matched against
asset hrefs, which is what distinguishes ``sar-data/tasks/``,
``sar-data/task-data/``, and ``open-data/`` — the name itself does not.
Zero matches is an error. More than one match lists the candidate STAC
URLs; pass one of those. The hosted server resolves a filename or stem
with the catalog index it already loaded. A local server does the same
after ``umbra index fetch``.

When the index contains a STAC URL, the indexed snapshot is returned —
the same document ``search_catalog`` already answered from — rather than
a live re-fetch that can disagree on asset filenames or product types.
When the server is configured with a token (``$UMBRA_CANOPY_TOKEN``) and
``url`` is a bare acquisition id (no ``://``, and not a filename or stem),
it is instead looked up in Umbra's authenticated commercial archive by a
keyed STAC search — the retrieval complement to ``search_catalog`` over
the paid catalog, since archive cards carry an ``id`` (not a fetchable
sidecar URL) as their hand-off pointer. A filename or stem still resolves
from the local open-data index when a token is set.

On the public host a URL is fetched only when it is https on Umbra's
public open-data bucket. Any other URL is refused before a request.
A bare id that is not in the local index is refused the same way.

The card (:meth:`UmbraItem.to_llm_context`) carries the id, ISO datetime,
place, bbox, resolution, polarization *with the change-detection caveat*,
the per-product-type explanations and asset URLs, and the mandatory
attribution line — everything a model needs to reason about the scene.

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": {
      "url": "<url>"
    },
    "name": "get_item"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlYesSTAC JSON URL, product filename, acquisition stem, or — when a Canopy token is set — a bare commercial-archive id.

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / url / description
      Added value: +"STAC JSON URL, product filename, acquisition stem, or — when a Canopy token is set — a bare commercial-archive id."
  2. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the readOnlyHint annotation, the description discloses important behavior: indexed snapshots are preferred over live re-fetches, token-authenticated archive lookups are used for bare ids, public-host requests are restricted to https public-bucket URLs, and zero or multiple matches have defined outcomes.

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 description is front-loaded and organized by concern, moving from accepted input forms to resolution behavior, token behavior, host restrictions, and returned card contents. It is dense and somewhat repetitive about local-index resolution and token handling, but most sentences carry operational 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 a one-parameter retrieval tool with an output schema and readOnlyHint, the description covers the remaining gaps: input resolution, ambiguity errors, authentication-dependent behavior, public-host restrictions, and the contents of the returned card. Nothing essential for correct invocation is missing.

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 description coverage is already 100%, so the baseline is 3, but the description adds real meaning by explaining how a filename or stem is resolved through the catalog index and when a bare id is treated as an authenticated archive lookup. It also clarifies that filenames and stems still resolve locally when a token is set.

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 sentence states a specific verb and resource: returning the full context card for one item. It also distinguishes the tool from search_catalog by explaining that get_item returns the indexed snapshot already used by search_catalog and serves as the paid-catalog retrieval complement.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives detailed conditions for filename/stem resolution, bare acquisition ids with a Canopy token, public-host URL restrictions, and multi-match handling. It relates get_item to search_catalog but does not give a crisp explicit directive such as 'use search_catalog first, then call get_item for the full card.'

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.