Skip to main content
Glama

download_asset

Destructive

Download one asset of an item to local disk, gated by a size check.

SAR products can be multiple GB, so this is a two-step handshake: call it
first with ``confirm=False`` (the default) to get the byte size without
downloading, then again with ``confirm=True`` to fetch it. On a
local or stdio server, ``confirm=True`` returns ``{asset, path, bytes}``.
``confirm=False`` returns a size-and-hint object and does not write a file.

On a public host (``umbra serve --public``, COG streaming off),
``confirm=True`` does not transfer the file. It returns a link plan:
``mode`` ``"link"``, ``downloaded`` false, ``asset``, ``filename`` (a
basename), the direct public ``href``, ``bytes``, and ``how_to_fetch``.
When the href is https on the public open-data bucket, ``how_to_fetch``
is ``curl -L -C - -o <filename> <href>`` and
``umbra download ITEM --asset ASSET --dest DIR``. ``bytes`` is the STAC
``file:size`` or ``size`` when that is a non-negative integer; otherwise
the host HEADs that href for ``Content-Length``, with no redirects and
no retries. A href that is not on that bucket is not requested:
``how_to_fetch.curl`` and ``how_to_fetch.umbra`` are null, ``bytes`` is
null, and ``note`` says the commands were omitted. A 404 or 410 from
an allowlisted HEAD raises. Any other HEAD failure, including a full
quick-request slot, leaves ``bytes`` null and still returns the plan.
The hosted server never transfers the file. A local
``uvx --from 'umbra-py[mcp]' umbra-mcp`` server downloads to your own
disk. ``confirm=False`` on this host returns the same size-and-hint
object and does not write a file. It HEADs for ``Content-Length`` only
when the href is https on the public open-data bucket, with no retries,
and it does not follow redirects. A 404 or 410 raises, and so does any
other non-redirect HEAD error. A redirect leaves ``bytes`` null. A href
outside the bucket is not requested; ``bytes`` is the STAC ``file:size``
or ``size`` when that is a non-negative integer, otherwise null. A local
server still HEADs the href and follows redirects.

On a local server, ``dest_dir`` is unchanged unless ``UMBRA_MCP_DOWNLOAD_ROOT``
is set. When that variable is set, ``dest_dir`` must resolve inside it.
The argument itself is unchanged.

``url`` is a STAC JSON URL, or a product filename
(``2025-05-17-17-43-46_UMBRA-08_GEC.tif``) or acquisition stem
(``2025-05-17-17-43-46_UMBRA-08``). A filename or stem is resolved through
the catalog index the same way as ``get_item``. The hosted server already
has that index. A local server needs ``umbra index fetch``.

``asset`` selects the file. All of these work:

- a product type, any case: ``GEC``, ``gec``, ``SICD``
- a schema v2 key, including a collision suffix: ``gec``, ``gec_2``,
  ``csi``, ``sidd``, ``csi_sidd``, ``sicd``, ``cphd``, ``metadata``,
  ``stac_metadata``, ``di_gif``, ``file``, ``file_tif``
- the original filename (the asset's ``umbra-py:filename``)

``GEC`` and ``gec`` are the primary file. ``gec_2`` is the second GEC,
not the primary. A name that matches nothing raises with the item's v2
keys listed (``gec, sicd, cphd``, …), not the uppercase product types.

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

Input Schema

NameRequiredDescriptionDefault
urlYesSTAC JSON URL, product filename, or acquisition stem. A filename or stem is resolved through the catalog index.
assetNoFile to fetch: a product type (GEC), a schema v2 key (gec, gec_2), or the original filename. Default GEC.GEC
confirmNoFalse (default) returns the byte size and writes nothing. True downloads on a local server, or returns a link plan on the public host.
dest_dirNoLocal download directory. Default '.'. Must stay inside UMBRA_MCP_DOWNLOAD_ROOT when that is set. On the public host it is only named in the link plan..

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changed
    • addedInput schema / properties / asset / description
      Added value: +"File to fetch: a product type (GEC), a schema v2 key (gec, gec_2), or the original filename. Default GEC."
    • addedInput schema / properties / confirm / description
      Added value: +"False (default) returns the byte size and writes nothing. True downloads on a local server, or returns a link plan on the public host."
    • addedInput schema / properties / dest_dir / description
      Added value: +"Local download directory. Default '.'. Must stay inside UMBRA_MCP_DOWNLOAD_ROOT when that is set. On the public host it is only named in the link plan."
    • addedInput schema / properties / url / description
      Added value: +"STAC JSON URL, product filename, or acquisition stem. A filename or stem is resolved through the catalog index."
  2. First observed

TDQS

A4.5/5.0
Behavior5/5

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

Annotations only say readOnlyHint=false and destructiveHint=true; the description goes far beyond by disclosing that confirm=False writes nothing, that the public host never transfers files and instead returns a link plan with how_to_fetch commands, HEAD semantics (no redirects, no retries, 404/410 raises, quick-request slot exhaustion degrades to null bytes), and that dest_dir must resolve inside UMBRA_MCP_DOWNLOAD_ROOT. This is exactly the kind of side-effect and failure-mode detail 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.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose and the two-step handshake are front-loaded well, but the hosted-vs-local paragraphs are long and repeat the same HEAD/redirect/no-redirect rules twice with slightly different wording, and 'does not write a file' is restated several times. The content is mostly earned, but the duplication makes it harder to scan than it needs to be.

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 tool with multi-mode behavior across hosted/local servers, the description covers confirmation flow, both host modes, size resolution sources, HEAD failure handling, download-root restrictions, and asset-name resolution. Output schema exists so return-value explanation is optional, yet the key shapes are still signaled, leaving nothing an agent needs before calling.

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 baseline is 3, but the description adds real meaning: url accepts a STAC JSON URL, product filename, or acquisition stem resolved through the catalog index; asset accepts product types case-insensitively, schema v2 keys including collision suffixes, or original filename, with 'GEC is primary, gec_2 is the second GEC'; and failure lists v2 keys rather than uppercase types. It also clarifies that dest_dir itself is unchanged when the download root constrains it.

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?

First sentence gives a specific verb and resource ('Download one asset of an item') plus the defining constraint ('gated by a size check'). No sibling tool in the list downloads assets, so the function is unambiguous without needing explicit differentiation.

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?

Gives explicit procedural guidance: call with confirm=False first to size the file, then confirm=True to fetch, with the rationale that SAR products can be multiple GB. It explains host-dependent behavior (local vs public host) but never names an alternative tool or states when not to use this one (e.g., preview via quicklook), so it stops short of full routing guidance.

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.