Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    stac for llm agents

    1

    A collection id written as `sentinel2` instead of `sentinel-2-l2a`: **0 scenes, no error**.

    $2

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    stac for llm agents

    stac for llm agents

    Example session with this skill installed

    My LangGraph agent has a stac_search tool over Earth Search, but users keep getting "no Sentinel-2 scenes found" for places and dates that definitely have imagery, and when it does find scenes the conversation hits the context limit after a couple of searches. Here's the tool, can you fix it?

    import json, urllib.request
    
    def stac_search(bbox, datetime, collections):
        body = {"bbox": bbox, "datetime": datetime, "collections": collections, "limit": 10}
        req = urllib.request.Request("https://earth-search.aws.element84.com/v1/search",
                                     data=json.dumps(body).encode(),
                                     headers={"Content-Type": "application/json"})
        try:
            return json.dumps(json.load(urllib.request.urlopen(req, timeout=30)))
        except Exception as e:
            return json.dumps({"error": str(e)})
    
    • Read your context and instructions
    • Compiled the stac for llm

    Summary

    Your tool has three silent-failure paths and one context-size problem. All four show up only against the live catalog, which is why your tests pass. I reproduced each one against Earth Search over Rome ([12.35, 41.8, 12.6, 41.99]), then fixed the tool and re-ran the same queries.

    What the model sendsBeforeAfter
    datetime="2024-01-15"HTTP Error 400: Bad Request3 scenes: a bare date becomes the whole day
    datetime="2024-01-01T00:00:00Z"0 scenes, no errorstill an instant, passed through as-is, but the schema now asks for a day or an interval, so the model stops sending one
    collections=["sentinel2"]0 scenes, HTTP 200Unknown collection(s) 'sentinel2'. Available: landsat-c2-l2, sentinel-1-grd, sentinel-2-l2a
    datetime="2024-06-01/2024-01-01"opaque 400 Bad RequestThe datetime interval ... ends before it starts. Write it as start/end.
    January 2024, sentinel-2-l2a10 scenes, 230,646 bytes10 scenes, 8,351 bytes (27.6× smaller)

    Why

    Dates: STAC requires RFC 3339. A bare date is rejected outright, and a timestamp sent as a single instant matches only scenes acquired at exactly that second. Expand days to full-day intervals; the interval end is inclusive.

    Collections: the real id is sentinel-2-l2a, and a STAC API answers an unknown collection with an empty result, not an error. Your model read that as "no imagery exists". Validate locally, and put the valid ids in the schema so the first call is right.

    Size: each Sentinel-2 item carries 35 assets (every band as COG and JP2) plus a full footprint polygon. The model needs asset names, not 35 hrefs, and cannot use the polygon at all.

    Errors: json.dumps({"error": ...}) hides why. Raise ValueError for bad input and RuntimeError for the catalog, and let your graph turn them into errored tool_results the model can act on.

    The fixed tool

    import json, urllib.error, urllib.request
    from stac_helpers import (collections_description, normalize_datetime,
                              summarize_item, validate_bbox, validate_collections)
    
    SEARCH_URL = "https://earth-search.aws.element84.com/v1/search"
    ALLOWED_COLLECTIONS = ["sentinel-1-grd", "sentinel-2-l2a", "landsat-c2-l2"]
    DEFAULT_LIMIT, MAX_LIMIT = 10, 50
    
    def stac_search(bbox, datetime=None, collections=None, max_cloud_cover=None,
                    limit=DEFAULT_LIMIT):
        body = {"bbox": validate_bbox(bbox), "limit": max(1, min(int(limit), MAX_LIMIT))}
        if datetime:
            body["datetime"] = normalize_datetime(datetime)
        if collections:
            body["collections"] = validate_collections(collections, ALLOWED_COLLECTIONS)
        if max_cloud_cover is not None:
            body["query"] = {"eo:cloud_cover": {"lt": float(max_cloud_cover)}}
    
        req = urllib.request.Request(SEARCH_URL, data=json.dumps(body).encode(),
                                     headers={"Content-Type": "application/json"})
        try:
            with urllib.request.urlopen(req, timeout=30) as resp:
                features = json.load(resp)["features"]
        except urllib.error.HTTPError as e:
            raise RuntimeError(f"Catalog rejected the search (HTTP {e.code}): {e.read()[:300]!r}") from e
        except (urllib.error.URLError, TimeoutError) as e:
            raise RuntimeError(f"Catalog unreachable: {e}") from e
    
        items = [summarize_item(f) for f in features]   # geometry stripped for the model
        return {"count": len(items), "limit": body["limit"], "items": items}
    

    The schema the model sees

    {
      "name": "stac_search",
      "description": "Search a STAC catalog for satellite scenes over an area and period.",
      "input_schema": {
        "type": "object",
        "properties": {
          "bbox": {"type": "array", "items": {"type": "number"}, "minItems": 4, "maxItems": 4,
                   "description": "[west, south, east, north] in degrees. west > east crosses the antimeridian."},
          "datetime": {"type": "string",
                       "description": "A day 'YYYY-MM-DD' or an interval 'start/end'; '..' leaves an end open."},
          "collections": {"type": "array", "items": {"type": "string"},
                          "description": "Collection ids to search. Available: landsat-c2-l2, sentinel-1-grd, sentinel-2-l2a. Use these exact ids."},
          "max_cloud_cover": {"type": "number", "description": "Maximum cloud cover, percent."}
        },
        "required": ["bbox"]
      }
    }
    

    One item, as the model now receives it:

    {
      "id": "S2B_33TTG_20240130_0_L2A",
      "collection": "sentinel-2-l2a",
      "datetime": "2024-01-30T10:09:09.601000Z",
      "cloud_cover": 1.578528,
      "platform": "sentinel-2b",
      "bbox": [11.355, 41.408, 12.723, 42.429],
      "asset_keys": ["aot", "blue", "green", "nir", "red", "scl", "thumbnail", "visual", "...35 names"],
      "assets": {"thumbnail": "https://sentinel-cogs.s3.us-west-2.amazonaws.com/.../thumbnail.jpg"}
    }
    

    Next steps

    • Generate the collections description from ALLOWED_COLLECTIONS with collections_description(), so the schema and the check can't drift.
    • If you draw footprints on a map, call summarize_item(f, include_geometry=True) for the UI and keep the model's copy without it.
    • Save one real search response as a test fixture, and re-run these five queries live whenever you change the request shape or the prompt.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    The problem

    When an AI agent searches a STAC catalog with a slightly wrong query, the catalog often doesn't return an error. It returns zero results. A person looking at an empty map would suspect the query; an agent takes the empty answer at face value and tells your user "there is no Sentinel-2 imagery over Rome in January", which is false.

    We measured it on Earth Search. A collection id written as sentinel2 instead of sentinel-2-l2a: 0 scenes, no error. A date sent as a single timestamp (2024-01-01T00:00:00Z): 0 scenes, no error. And where the catalog does reject a query, a plain date like 2024-01-15 gets an HTTP 400 whose message the agent can't act on.

    When it does work, a single Sentinel-2 L2A item carries 35 assets plus a full geometry: 10 scenes are 230 KB of JSON dumped into your context window.

    None of this shows up in an offline test suite. Every rule in this skill was found against a live catalog while building eo-rag, a production tool-calling assistant over STAC catalogs.

    What the skill teaches your agent

    Each rule is written as symptom → cause → fix, so the agent can also diagnose an existing tool:

    1. Datetimes: complete bare dates to RFC 3339, make a day mean the whole day and an interval end inclusive, keep open ends (..), and reject backwards intervals with a clear message.
    2. Collections: validate ids against an allowlist before the request, list the valid ids in the error, and name them in the tool schema's description (not an enum, and here's why).
    3. Bounding boxes: validate [W, S, E, N], allow west > east for the antimeridian, and split fallback polygons into a MultiPolygon.
    4. Context-window projection: what to keep per item (asset names, preview hrefs only), what to strip (geometry goes to your map, not your model). Measured: ~28× smaller.
    5. s3:// hrefs (Sentinel-1 on Earth Search): the virtual-hosted rewrite that works in every region, and why path style 301s with no Location.
    6. Errors as tool results: validation and upstream failures come back as messages the model can act on, never a 500.
    7. Caller-side parameters stay out of the schema, with a test that keeps the schema in sync with the function.
    8. Testing: captured real fixtures and the five live checks to run whenever the request shape changes.

    What's in the ZIP

    • SKILL.md: the rules. They work on their own with any SKILL.md-compatible agent.
    • reference/stac_helpers.py: a standard-library Python implementation of rules 1–5 (normalize_datetime, validate_bbox, validate_collections, collections_description, bbox_to_geojson, fetchable_href, summarize_item), with a built-in self-test (python stac_helpers.py). No framework dependency: drop it into LangChain, LangGraph, the Anthropic or OpenAI SDKs, an MCP server, or plain code.

    Who it's for

    Anyone giving an LLM access to Earth Observation data: EO scientists building assistants over Sentinel-1/2 and Landsat, GIS developers adding a chat interface to a STAC catalog, teams writing MCP servers for imagery search.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.

    • Rules and examples were verified against Earth Search (Element 84). Other STAC APIs share the spec but may differ in error behaviour, e.g. some 400 on a backwards interval while others return an empty result.
    • Covers the STAC Item Search endpoint (POST /search) and item summaries. It does not cover CQL2 filtering, pagination beyond the first page, or downloading and processing COG rasters.
    • The reference helpers are Python only; the rules themselves are language-agnostic.
    • The collection allowlist is yours to maintain: the skill shows how to enforce and advertise it, not which ids a given catalog offers.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 21 days ago

    Accounts
    Element84Stacspec

    Permissions

    Terminal / Shell
    Network Access
    Read Files
    Write Files

    Allowed Hosts

    earth-search.aws.element84.com
    stacspec.org

    File Scopes

    **/*.py

    Read/Write Files: to review and fix the user's own STAC tool code. Terminal: to run the reference self-test (python stac_helpers.py). Network Access: only for the optional live checks against a public STAC API; the skill makes no requests on its own and needs no credentials.

    Listed21 days ago

    What's inside

    Frequently Asked Questions

    The skill is about the tool function and its schema, which every framework wraps the same way. The reference helpers are plain Python with no framework imports.

    No. Earth Search is public and needs no credentials; the same rules apply to any STAC API you point it at.

    Mostly the queries that fail silently: a bare date, a misspelled collection, a single-instant datetime, an antimeridian bbox. Those return empty results that the model reports as facts. Plus a ~28× smaller tool result, which delays context-limit truncation in long conversations.

    No. Sentinel-2 is the running example because its items are the heaviest (35 assets). The s3:// rule exists specifically for Sentinel-1, and the rules apply to Landsat and any other collection.

    When you ask it to review or fix a STAC tool, your agent applies the rules to your code, as in the demo. It doesn't run on its own or touch anything else.

    New in APIs & Backend