# For agents

> Machine-readable ways to read these docs and what the server expects of an agent.

## Read the docs as Markdown

- Every docs page is also served as clean Markdown at its path plus `.md`, for example
  `/docs/quickstart.md` and `/docs/tools/query_metrics.md`. The index is `/docs.md`.
- [`/llms.txt`](/llms.txt) lists every docs page in the llms.txt format. [`/llms-full.txt`](/llms-full.txt)
  has the full text of all pages in one file.
- Both files and the tool reference are generated at build time from these pages and the live tool
  schemas. If a page and the server disagree, the server is right and the page is a bug: tell us at
  info@groundtruthdata.co.za.

## How an agent should call the tools

1. Call `describe_catalog` first. It is free and lists metrics, geographies and limits.
2. Turn place names into ids with `resolve_location`. Never guess an `area_id`. If the status is
   `ambiguous`, ask the user, or call again with `area_type`.
3. Call `query_metrics` or `compare_areas`. Responses are capped; do not try to page through
   everything.
4. Quote the `citations` and `caveats` with every number. Use `get_provenance` for the licence
   and method behind a metric.

Errors say what went wrong and how to fix it. See the [Tool reference](/docs/tools).