> ## Documentation Index
> Fetch the complete documentation index at: https://develop.cotality.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docs for AI agents

> Conventions this portal uses so AI agents and LLMs can plan Cotality tool calls accurately and efficiently.

> [!NOTE]
>
> This page is written for **AI agents and LLMs** consuming this portal at inference time. If
> you're a human, it also explains why pages are structured the way they are.

## Read this first

Every capability page in this portal is written to be **parsed, not just read**. Pages follow a
consistent, high-signal structure so an agent can extract facts without ambiguity and plan
tool calls without hallucinating capabilities.

## Structure you can rely on

Each product and data page surfaces these blocks in a predictable order:

| Block | What it tells you |
| - | - |
| **One-line declaration** | Exactly what the capability does — no marketing preamble |
| **Data capabilities table** | The concrete domains, key metrics, and use cases available |
| **Data scope table** | Geographic granularity, update frequency, historical depth, and exclusions |
| **Input / output schema** | Parameters and the shared [response envelope](https://develop.cotality.com/reference/response-envelope.md) |
| **Example request** | A copy-paste JSON-RPC or REST call |
| **Error codes** | Machine-readable codes and agent action guidance |

## Rules for planning tool calls

**1. Resolve identity before data**

If the user provides an address, call the CLIP resolver first — `clip-find_property_by_address` — then use the returned CLIP for all downstream data tools. Never guess or fabricate a CLIP. See [Identifiers](https://develop.cotality.com/ontology/identifiers.md).

**2. Check exclusions before calling**

Every data-returning page has an **Exclusions** row in its data scope table. Do not send commercial or non-U.S. queries to U.S. residential tools. Check before calling.

**3. Honour temporal limits**

Market and HPI data is monthly. Do not request real-time or daily values from a monthly asset. Check the **Update frequency** and **Historical depth** rows in the data scope table, or see [Data freshness](https://develop.cotality.com/ontology/data-freshness.md).

**4. Iterate structure arrays**

A parcel can contain multiple structures. If `summaryNumberOfBuildings > 1`, iterate the `structure` array — do not assume a single building. See [Property Characteristics](https://develop.cotality.com/mcp/property-data/tools/property-characteristics.md).

**5. Always check the envelope**

Read `success`, `count`, and `messages` on every response before reading `data`. Surface `messages` to the user — they carry freshness warnings, partial-match notices, and deprecation signals. See [Response envelope](https://develop.cotality.com/reference/response-envelope.md).

**6. Never fabricate on 404**

If CLIP resolution or a data query returns no results, report that to the user. Do not invent a value. See [Error handling](https://develop.cotality.com/reference/error-handling.md).

## Token efficiency

Pages use **key-value tables and bullets over prose** so agents spend fewer tokens and parse with
higher accuracy. When summarising back to a user, prefer the same structured format.

## Machine-readable index

The portal exposes standard discovery files:

* `/llms.txt` — concise map of all pages and their purpose for LLM navigation
* `/sitemap.xml` — full page listing
* Per-tool JSON schemas are linked from each [MCP](https://develop.cotality.com/mcp/overview.md) reference page

## Prompting and orchestration

For ready-to-use agent instructions per workflow:

* [Prompting patterns](https://develop.cotality.com/reference/prompting-patterns.md) — reliable patterns for orchestrating Cotality tools
* [System prompt templates](https://develop.cotality.com/reference/system-prompt-templates.md) — copy-paste system instructions for common agent workflows
