The registry is data-driven (config/catalogs.yaml): today it contains
    Element84 Earth Search over AWS Open Data
    (https://earth-search.aws.element84.com/v1) with its searchable
    modalities, curated collections and topic keywords.

    Usage: Call once to see where EO data can be discovered from before
    using `search_eo_datasets` / `search_eo_scenes`.

    Returns:
    --------
    Dictionary containing:
        - catalogs: Registered catalogs with id, name, URL, description,
          modalities, common collections and supported topics.
    

    Performs collection-level search on the Earth Search STAC API
    (AWS Open Data). Queries hit the topics map first ('flood' -> Sentinel-1
    + Sentinel-2, 'dem' -> Copernicus DEM...), then fall back to keyword
    matching against live collection metadata; every hit is classified by
    sensor modality (optical / radar / elevation).

    Usage: Start here for dataset-level discovery ("find me flood/burn
    scar/terrain datasets"). Then use the returned collection ids with
    `search_eo_scenes`, or jump straight to `create_geocroissant_from_stac`
    to get GeoCroissant metadata.

    Returns:
    --------
    Dictionary containing:
        - matched_topics: Topic-map hits for the query.
        - count: Number of matching collections found.
        - collections: Matches with catalog, collection id, title,
          description snippet, modality, license and temporal extent.
    

    Executes a real STAC item search (pystac-client) against
    https://earth-search.aws.element84.com/v1 filtered by spatial extent,
    time range and cloud cover. Scenes are the individual acquisitions
    (tiles/granules) that become records of a GeoCroissant dataset.

    Usage: Use after `search_eo_datasets` (or directly with known
    collections) to check actual data availability for an area of interest.
    Feed promising results into `create_geocroissant_from_stac`.

    Returns:
    --------
    Dictionary containing:
        - scene_count and scenes: Per-scene id, collection, acquisition
          datetime, platform, cloud cover, native EPSG and asset keys.
    

    Runs the official MLCommons ``mlcroissant`` validator: JSON syntax check,
    JSON-LD expansion, structure-graph construction (FileObjects/FileSets,
    RecordSets, Fields, sources & joins) and full schema conformance checks.

    Usage: Call this tool whenever a dataset description is created or edited,
    BEFORE publishing it, and after any modification of an existing file.
    Works for both plain Croissant documents and documents using the
    GeoCroissant extension (`geocr:` properties).

    Returns:
    --------
    Dictionary containing:
        - valid: True when the document passes validation.
        - errors: Blocking errors reported by the library (empty when valid).
        - warnings: Non-blocking recommendations (e.g. missing license).
        - is_geospatial: Whether GeoCroissant conformance is declared.
        - conforms_to / dataset_name: Extracted metadata when loadable.
    

    Parses the document through the ``mlcroissant`` library (which also acts as
    a strict syntax/schema check - invalid documents are rejected) and returns
    a structured digest: core metadata, GeoCroissant extension properties
    (CRS, resolutions, band configuration, spectral bands, record endpoint...),
    distribution entries (FileObjects/FileSets with URLs, formats, hashes),
    and every RecordSet with its Fields (data types, array shapes,
    source/extract/transform chains).

    Usage: Use this tool to READ and UNDERSTAND a dataset description before
    consuming it, comparing datasets, or planning how to load records.

    Returns:
    --------
    Dictionary containing:
        - name/description/license/version/conformsTo and other core metadata.
        - geospatial: All declared `geocr:` extension properties.
        - distribution: FileObject/FileSet entries.
        - record_sets: RecordSets with nested fields and geo properties.
    

    Builds the directed multigraph that ``mlcroissant`` uses internally for
    static analysis: nodes are Metadata / FileObject / FileSet / RecordSet /
    Field objects and edges connect fields to their data sources, record sets
    to their fields, files to archives they are contained in, and referenced
    (foreign-key) fields.

    Usage: Use this tool to reason about dataset lineage and dependencies,
    e.g. "which files feed this field?", "what does this join look like?",
    or to explain a dataset's architecture before writing loading code.

    Returns:
    --------
    StructureGraph containing:
        - nodes: Every node with @id, type, name and parent @id.
        - edges: Directed edges as {source, target} @id pairs.
    

    A RecordSet is a collection of records (rows/examples) produced by
    applying the declared extraction pipeline to the distribution. This tool
    returns each RecordSet's @id, name, description, key fields, enumeration
    flag, number of inline records/examples and its Fields with their data
    types and source chains.

    Usage: Call this tool to discover what data a dataset exposes and which
    RecordSet names to pass to `get_records_preview`.

    Returns:
    --------
    List of dictionaries, one per RecordSet, each including:
        - @id: The RecordSet identifier used by other tools.
        - fields: Nested field summaries (dataType, isArray/arrayShape,
          source extract/transform chain, geo band properties).
    

    This tool runs the real ``mlcroissant`` operation graph: it downloads (or
    resolves locally) the declared FileObjects/FileSets, applies extracts and
    transforms, and yields actual records - exactly what
    ``Dataset.records(record_set)`` yields in Python.

    Usage: Use it to preview/sample a dataset's actual data before writing
    training code, or to sanity-check that a generated Croissant description
    produces the expected columns and values.

    IMPORTANT: For remote distributions this may download data; keep `limit`
    small on large datasets. Datasets with inline `cr:data` return those rows
    directly without downloads.

    Returns:
    --------
    RecordsPreview containing:
        - record_set: The RecordSet @id that was read.
        - columns: Column names found across returned records.
        - rows: List of records keyed by fully-qualified field ids.
        - truncated: True if more records exist beyond `limit`.
    

    Collects the `contentUrl` of every FileObject together with its encoding
    formats, sizes and checksums, plus FileSet include patterns and archive
    containers. These are the direct access points for the dataset bytes.

    Usage: Use this tool to obtain concrete download links (e.g. GeoTIFF /
    COG / ZIP assets) for ingestion code without parsing the JSON manually.

    Returns:
    --------
    DistributionUrls containing:
        - urls: One entry per distribution item (name, type, contentUrl,
          encodingFormat, md5/sha256, includes/containedIn when present).
        - count: Number of distribution items with at least one URL.
    

    Produces a standards-conformant starting point modeled on the official
    GeoCroissant example: correct @context (including the `geocr` prefix),
    dual conformance (`croissant/1.1` + `geocr`), schema.org spatial/temporal
    coverage, GeoCroissant properties (CRS, resolutions, band configuration,
    spectral bands), distribution entries and a RecordSet wired to them via
    proper cr:source/cr:extract declarations.

    The generated document is then parsed and checked by the real
    ``mlcroissant`` validator, so `valid=True` means the scaffold already
    passes the official library checks.

    Usage: Call FIRST when creating new dataset metadata, then edit the
    returned JSON-LD for domain specifics and re-check with
    `validate_croissant`. Use `inspect_geocroissant` afterwards to review it.

    Returns:
    --------
    ScaffoldResult containing:
        - valid: Whether the scaffold passed mlcroissant validation.
        - json_ld: The generated document.
        - errors/warnings: Library messages when not fully clean.
        - path: Output file path when output_filename was given.
    

    This is the flagship end-to-end pipeline of this server:

    1. Runs a real STAC search (bbox + collections + datetime + cloud cover).
    2. Derives GeoCroissant properties from the results: schema.org spatial/
       temporal coverage, CRS (EPSG:4326), record endpoint, band
       configuration and spectral band metadata from `eo:bands`
       (micrometers converted to nanometers), distribution FileObjects for
       direct asset URLs, and a RecordSet with one inline row per scene.
    3. Validates the document through the official `mlcroissant` library
       before returning it.

    Usage: THE tool for turning discovered EO data into GeoCroissant.
    After generation use `inspect_geocroissant`, `get_records_preview`
    and `extract_distribution_urls` on the output.

    Returns:
    --------
    Dictionary containing:
        - valid/errors/warnings: mlcroissant validation outcome.
        - json_ld: The generated GeoCroissant document.
        - path: Output file path when output_filename was given.
        - search_summary: What was searched and how many scenes matched.
    

    Provides the vocabulary cheat sheet distilled from the official GeoCroissant
    specification: namespace IRIs and prefixes, conformance declarations, every
    `geocr:` property with expected types/domains/cardinality, the canonical
    JSON-LD @context, a full sample document, and Python snippets for the
    ``mlcroissant`` API (load, validate, iterate records).

    Usage: Read this ONCE before authoring or editing GeoCroissant documents so
    property names, types and cardinalities match the specification exactly.
    Then use `create_geocroissant_scaffold` and `validate_croissant`.

    Returns:
    --------
    Markdown-formatted reference documentation for the requested topic.