# 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`](/docs/tools/describe_catalog) | List the metrics, geographies, time coverage and per-call limits this server offers. | no (free) |
| [`resolve_location`](/docs/tools/resolve_location) | Turn a place name or a lat/lon point into canonical area_ids (max 5 candidates). | yes |
| [`query_metrics`](/docs/tools/query_metrics) | Get aggregated, cited metric values for up to 25 areas (max 200 rows). | yes |
| [`compare_areas`](/docs/tools/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`](/docs/tools/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](/docs/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.