Skip to main content
Glama

NASA Earthdata MCP

by io.github.nasa
OverviewDiscussionsAdmin

get_granules

Read-onlyIdempotent

Search NASA CMR granules for a specific parent collection and return up to 10 lightweight normalized results.

Key return fields in each item:

  • concept_id: CMR granule concept ID

  • native_id: native ID of the granule record

  • revision_id: revision ID of the granule metadata

  • provider_id: provider ID of the granule

  • granule_ur: primary granule identifier

  • time_start / time_end: temporal coverage bounds

  • access_urls: actionable data access URLs

  • cloud_cover: cloud cover percentage

  • day_night_flag: DAY, NIGHT, BOTH, or UNSPECIFIED

  • size_mb: file size in megabytes

  • data_format: file format (e.g., NetCDF-4, GeoTIFF)

  • bounding_box: [West, South, East, North] Minimum Bounding Rectangle (MBR) footprint. Note: for swath data or irregular polygons, this bounding box fully encloses the data but may contain empty space at the corners.

IMPORTANT — data availability checks: Without temporal and/or spatial filters, results represent ALL granules ever archived in the collection, which may span decades and the entire globe. total_hits without filters tells you the full archive size, NOT whether data exists for a specific area or time period. To verify availability for a specific region and/or period, apply the corresponding spatial or temporal filters. Single-filter queries (e.g., temporal-only) are completely valid and should be used when the user only specifies one constraint, but combining both provides the most precise availability answer.

Key parameters:

  • collection_concept_id: required parent collection concept ID

  • temporal_start_date / temporal_end_date: filter to granules overlapping this time window — always set when the user specifies a time period

  • spatial_wkt_geometry: filter to granules intersecting this area — always set when the user specifies a geographic region

  • cloud_cover_min / cloud_cover_max: filter optical imagery by cloud cover percentage (0–100). Only set for optical/visible imagery collections (Landsat, MODIS, VIIRS, Sentinel-2 via CMR). Do NOT set for non-optical data (SAR, altimetry, model output, etc.)

Iteration & Refinement:

  • Results are strictly capped at 10 items to optimize context window usage.

  • If total_hits exceeds 10 and you lack the necessary results, do not attempt to page. Refine your query by adding tighter spatial or temporal constraints.

Tips:

  • For the most precise availability check, provide both temporal and spatial filters if the user specifies both; otherwise, apply whichever constraint they provided

  • total_hits in the response reflects the filtered count — zero means no data for that combination

  • When users ask for "clear" or "cloud-free" imagery, set cloud_cover_max to a low value (e.g., 10 or 20)

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of results to return (default 10, max 50). Keep this small to avoid context window bloat. When using limit > 10, always specify the fields parameter.
cursorNoPagination token for the next page of results. Pass the exact next_cursor string returned by the previous tool call. Cursors are query-scoped: they lock in the original search parameters and cannot be reused across different tools or different queries. If you need to change any search parameter, start a new search without a cursor.
fieldsNo
sort_keyNoSort key for granule results. e.g., '-start_date' (newest first), 'start_date' (oldest first). CMR default is relevance score. For ongoing or near-real-time (NRT) missions where the user wants the most recent data, always use '-start_date' — CMR's default relevance scoring may return historical data first if sort_key is not explicitly set.
day_night_flagNoFilter granules by day/night acquisition flag. Values: 'DAY', 'NIGHT', 'UNSPECIFIED'.
cloud_cover_maxNoMaximum cloud cover percentage (0–100, inclusive). Use with cloud_cover_min to filter optical/visible imagery granules by cloud cover. For example, set cloud_cover_max=20 to find mostly clear scenes. Only applicable to collections that report cloud cover (e.g., Landsat, MODIS, etc). Omit for non-optical data (SAR, altimetry, etc.).
cloud_cover_minNoMinimum cloud cover percentage (0–100, inclusive). Use with cloud_cover_max to filter optical/visible imagery granules by cloud cover. Only applicable to collections that report cloud cover (e.g., Landsat, MODIS, etc). Omit for non-optical data (SAR, altimetry, etc.).
temporal_end_dateNoEnd of temporal filter in ISO 8601 format (e.g., 2024-01-31T23:59:59Z). Finds granules whose temporal extent overlaps this window. Set this whenever the user specifies a time period — omitting it returns granules from the entire collection archive regardless of date.
temporal_start_dateNoStart of temporal filter in ISO 8601 format (e.g., 2024-01-01T00:00:00Z). Finds granules whose temporal extent overlaps this window. Set this whenever the user specifies a time period — omitting it returns granules from the entire collection archive regardless of date.
spatial_wkt_geometryNoSpatial filter as WKT geometry. Supported types: POLYGON((lon lat, ...)), POINT(lon lat), or LINESTRING(lon lat, ...).Finds granules with spatial extent intersecting this area. CMR returns any granule that touches this shape, so precise geometries are preferred to prevent false positives. Set this whenever the user specifies a geographic region — omitting it returns granules from the entire globe regardless of location.
collection_concept_idYesParent collection concept ID (format: C<number>-<PROVIDER>, e.g., C2723758340-GES_DISC). Required to scope granule search.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
statusYesStatus of the tool execution
granulesNoNormalized granule results mapped from UMM-G
total_hitsNoTotal number of matching items
next_cursorNoPagination token for the next page of results
error_messageNoError details when status is error

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds substantial behavior beyond them: the 10-item cap, the total_hits semantics ('full archive size, NOT whether data exists'), and filter-interaction rules. However, 'Results are strictly capped at 10 items... do not attempt to page' sits awkwardly against the schema's limit parameter (max 50) and cursor parameter, creating ambiguity about actual paging behavior.

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 purpose, then organized under clear headers (return fields, parameters, iteration, tips), so it is scannable. It is nonetheless long and repeats schema content, e.g., the temporal filter explanation appears both in the body and in temporal_start_date's schema description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers filters, limits, availability semantics, and refinement strategy, which is more than enough for an 11-parameter tool. Since an output schema exists, the enumerated return fields are somewhat redundant, and the cap-versus-limit/cursor tension leaves a small gap about how to legitimately retrieve more than 10 results.

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 91%, so the baseline is 3, but the description adds intent-to-parameter mapping the schema lacks: which filters to set given what the user specified, the temporal+spatial combination rule, and the practical tip to set cloud_cover_max to 10-20 for 'clear' imagery requests. Much of the per-parameter text overlaps the schema, limiting it to a 4.

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 specific verb and resource ('Search NASA CMR granules for a specific parent collection') and the scope ('up to 10 lightweight normalized results'). It is clearly distinguishable from siblings like get_collections, which operate at the collection rather than granule level.

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 throughout: always set temporal/spatial filters when the user specifies those constraints, single-filter queries are valid, cloud_cover filters must NOT be set for non-optical data, and refinement (not paging) is prescribed when total_hits exceeds 10. Alternatives and exclusions are named rather than implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All NASA Earthdata MCP toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources