# describe_catalog > List the metrics, geographies, time coverage and per-call limits this server offers. List the metrics, geographies, time coverage and per-call limits this server offers. Call this first. Free (does not count against your plan). **Counts against your plan:** no, free. **Read-only:** yes, nothing you send is stored or changes any data. ## Inputs This tool takes no arguments. ## Caps No row or area caps apply: the response is a fixed-size summary. ## Response Every response also carries `citations`, `caveats` and `dataset_version` ([Citations](/docs/citations)). | Field | Type | Description | |---|---|---| | `citations` | `object[]` | | | `caveats` | `string[]` | | | `dataset_version` | `string` | | | `metrics` | `object[]` | | | `geographies` | `object[]` | | | `limits` | `object` | | | `how_to` | `string[]` | | **`metrics[]`** (each item) | Field | Type | Description | |---|---|---| | `id` | `string` | | | `label` | `string` | | | `description` | `string` | | | `unit` | `string` | | | `kind` | `string` | | | `spatial_aggregation` | `string` | | | `native_geographies` | `string[]` | | | `allowed_geographies` | `string[]` | | | `time_grain` | `string` | | | `time_rollups` | `object` | | | `period_format` | `string` | | | `first_period` | `string` | | | `last_period` | `string` | | | `available_ids` | `string[]` | Concrete ids for metric families | | `family_members` | `object[]` | | | `caveats` | `string[]` | | **`geographies[]`** (each item) | Field | Type | Description | |---|---|---| | `area_type` | `string` | | | `label` | `string` | | | `id_format` | `string` | | | `example` | `string` | | **`metrics.family_members[]`** (each item) | Field | Type | Description | |---|---|---| | `id` | `string` | | | `label` | `string` | | | `is_aggregate` | `boolean` | SAPS roll-up category: never add it to its component offences | ## Examples > **Fixture data** > > These responses were produced by the real tool against the synthetic test dataset (`fixture-2026.11.05`), so the numbers are illustrative, not real statistics. Production responses cite the real sources. ### Everything the server offers Request: ```json {} ``` Response: (lists shortened) ```json { "citations": [ { "source_id": "worldpop_population", "name": "[FIXTURE] WorldPop Constrained Population 100 m (R2025A)", "publisher": "WorldPop, University of Southampton", "url": "https://www.worldpop.org/", "licence": "CC-BY-4.0", "commercial_use": "yes", "attribution": "WorldPop (www.worldpop.org), University of Southampton. CC BY 4.0.", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" }, { "source_id": "mdb_wards_2026", "name": "[FIXTURE] MDB Wards 2026", "publisher": "Municipal Demarcation Board (MDB)", "url": "https://www.demarcation.org.za/", "licence": "MDB custom terms", "commercial_use": "unclear", "attribution": "Source: Municipal Demarcation Board (MDB)", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" }, { "source_id": "chirps_rainfall", "name": "[FIXTURE] CHIRPS v3.0 Monthly Rainfall", "publisher": "Climate Hazards Center, UC Santa Barbara", "url": "https://www.chc.ucsb.edu/data/chirps3", "licence": "CC-BY-4.0", "commercial_use": "yes", "attribution": "Funk et al., CHIRPS v3.0, Climate Hazards Center, UCSB.", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" }, { "source_id": "saps_crime_stats", "name": "[FIXTURE] SAPS Crime Statistics", "publisher": "South African Police Service (SAPS)", "url": "https://www.saps.gov.za/services/crimestats.php", "licence": "SAPS website copyright (no open licence)", "commercial_use": "unclear", "attribution": "Source: South African Police Service, Crime Statistics", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" }, { "source_id": "osm_geofabrik_za", "name": "[FIXTURE] OpenStreetMap South Africa (Geofabrik) facility points", "publisher": "OpenStreetMap contributors; extract by Geofabrik GmbH", "url": "https://download.geofabrik.de/africa/south-africa-latest.osm.pbf", "licence": "ODbL-1.0", "commercial_use": "yes", "attribution": "© OpenStreetMap contributors. Data under the Open Database Licence (ODbL 1.0).", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" }, { "source_id": "treasury_municipal_finance", "name": "[FIXTURE] National Treasury Municipal Money", "publisher": "National Treasury", "url": "https://municipaldata.treasury.gov.za/api/cubes", "licence": "National Treasury Municipal Money Terms of Use v1.0", "commercial_use": "unclear", "attribution": "National Treasury, Municipal Money (municipalmoney.gov.za)", "retrieved_at": "2026-11-05", "dataset_version": "fixture-2026.11.05" } ], "caveats": [ "FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.", "Licence note (mdb_wards_2026): MDB custom terms; commercial use 'unclear'. Served only as derived aggregates with attribution: Source: Municipal Demarcation Board (MDB)", "Licence note (saps_crime_stats): SAPS website copyright (no open licence); commercial use 'unclear'. Served only as derived aggregates with attribution: Source: South African Police Service, Crime Statistics", "Licence note (treasury_municipal_finance): National Treasury Municipal Money Terms of Use v1.0; commercial use 'unclear'. Served only as derived aggregates with attribution: National Treasury, Municipal Money (municipalmoney.gov.za)" ], "dataset_version": "fixture-2026.11.05", "metrics": [ { "id": "population_total", "label": "Total population", "description": "Estimated resident population of the area for a year, from WorldPop 100 m gridded population summed over the area polygon. Use for \"how many people live in X\".", "unit": "people", "kind": "count", "spatial_aggregation": "sum", "native_geographies": [ "ward", "local_municipality", "district", "province" ], "allowed_geographies": [ "ward", "local_municipality", "district", "province" ], "time_grain": "year", "time_rollups": {}, "period_format": "YYYY", "first_period": "2020", "last_period": "2025", "available_ids": [], "family_members": [], "caveats": [ "Modelled estimate (WorldPop constrained gridded population), not a census count.", "Zonal sum of 100 m cells; small wards can be off by a few percent at boundaries." ] }, { "id": "population_density_km2", "label": "Population density", "description": "Estimated people per square kilometre (population_total / area_km2). A ratio: combining several areas uses the area-weighted mean, which equals total people / total area.", "unit": "people/km2", "kind": "ratio", "spatial_aggregation": "area_weighted_mean", "native_geographies": [ "ward", "local_municipality", "district", "province" ], "allowed_geographies": [ "ward", "local_municipality", "district", "province" ], "time_grain": "year", "time_rollups": {}, "period_format": "YYYY", "first_period": "2020", "last_period": "2025", "available_ids": [], "family_members": [], "caveats": [ "Derived from a modelled population estimate divided by polygon area.", "Density over a large rural municipality hides strong local variation." ] } ], "geographies": [ { "area_type": "province", "label": "Province", "id_format": "prov:", "example": "prov:WC" }, { "area_type": "district", "label": "District / metropolitan municipality", "id_format": "dm:", "example": "dm:DC1" } ], "limits": { "max_metrics_per_call": 5, "max_areas_per_call": 25, "max_rows_per_call": 200, "compare_areas_min": 2, "compare_areas_max": 5, "max_location_candidates": 5 }, "how_to": [ "1. resolve_location('') to get an area_id (never guess ids).", "2. query_metrics(metrics=[...], area_ids=[...], year_from, year_to)." ] } ``` Provenance in this example: source `worldpop_population`, licence “CC-BY-4.0”, retrieved 2026-11-05, dataset_version `fixture-2026.11.05`. ## Errors Errors read `: . Fix: `. Shared codes are on the [Tool reference](/docs/tools) page. This tool has no input of its own to get wrong.