Tool reference
The bounded tools the GroundTruthData MCP server exposes.
Five read-only tools, generated from the live MCP tool schemas. Recommended order: describe_catalog, then resolve_location, then query_metrics or compare_areas, then get_provenance. Never guess an area_id.
| Tool | Purpose | Counts against your plan |
|---|---|---|
describe_catalog | List the metrics, geographies, time coverage and per-call limits this server offers. | no (free) |
resolve_location | Turn a place name or a lat/lon point into canonical area_ids (max 5 candidates). | yes |
query_metrics | Get aggregated, cited metric values for up to 25 areas (max 200 rows). | yes |
compare_areas | Compare 2-5 areas on up to 5 metrics: value, rank among them (1 = highest) and the national percentile among all areas of the same type. | yes |
get_provenance | Where a metric comes from: publisher, licence, retrieval date, dataset version, method and lineage. | no (free) |
Bounds on every response
Responses are aggregated and capped. There is no bulk export. Maximums: 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. See Plans and limits.
Errors shared by all tools
| Code | Meaning | Fix |
|---|---|---|
UNAUTHENTICATED | No valid credential on the request (or the account no longer exists). | Send the header Authorization: Bearer YOUR_KEY with a current API key, or reconnect with OAuth. |
SUBSCRIPTION_REQUIRED | 402. The account has no active plan, so no call is allowed. | Choose a plan on the pricing page. |
RATE_LIMITED | 429. Too many calls in a short burst, a plan quota is used up, or too many failed calls today. The message says which, and when it resets. | Wait for the time given, space out calls, or upgrade. |
LIMIT_EXCEEDED | The request is over a per-call cap (areas or rows) of your plan. | Split the request, narrow the years or set time_grain to year. |
UNKNOWN_TOOL | The tool name is not one of the five tools. | Use a name from this page. |
INVALID_ARGUMENT | An input is missing, malformed or inconsistent. | Read the message: it names the argument and the correction. |
UNKNOWN_METRIC | The metric id is not in the catalogue. | Call describe_catalog for valid ids. |
UNKNOWN_AREA | The area_id is not known. | Call resolve_location with a place name; never guess ids. |
GEOGRAPHY_NOT_ALLOWED | The metric is not published for that type of area. | Use an area type the message lists, for example via resolve_location with area_type. |
NO_DATA | The metric has no data loaded. | Call describe_catalog to see which metrics have coverage. |
UNAVAILABLE | The data store is not available right now. | Retry in a few minutes. |
PROVENANCE_MISSING | A value could not be cited, so none was returned. This is a server-side data issue. | Report it to info@groundtruthdata.co.za. |
Each tool page lists its own errors with the exact text the server returns.