> ## 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.

# Response envelope

> The common response wrapper returned by every Cotality MCP tool and REST API — success, count, data, and messages.

## One shape for every response

Every Cotality MCP tool and REST endpoint returns the same top-level envelope. Parse these
four fields on every call, before reading tool-specific payload.

```json theme={null}
{
  "success": true,
  "count": 1,
  "data": [ /* tool-specific result objects */ ],
  "messages": []
}
```

## Fields

| Field      | Type      | Always present | Meaning                                                                                   |
| ---------- | --------- | -------------- | ----------------------------------------------------------------------------------------- |
| `success`  | `boolean` | Yes            | Whether the call completed successfully. Gate all `data` reads on this.                   |
| `count`    | `integer` | Yes            | Number of items in `data`.                                                                |
| `data`     | `array`   | Yes            | Tool-specific payload. Shape differs per tool.                                            |
| `messages` | `array`   | Yes            | Warnings, deprecations, partial-match notices, and info. Always surface non-empty values. |

## Rules for consumers

<Steps>
  <Step title="Gate on success">
    If `success` is `false`, do not read `data`. Route to [error handling](/reference/error-handling).
  </Step>

  <Step title="Respect count">
    Iterate exactly `count` items from `data`. Do not assume a single result — parcels, properties, and geographies can return multiple records.
  </Step>

  <Step title="Read messages on every call">
    `messages` carries freshness notes, partial-match warnings, and deprecation notices. An empty array is normal. A non-empty array always contains something the user or agent should know about.
  </Step>
</Steps>

## Error envelope

When `success` is `false`, the error detail is in `messages`:

```json theme={null}
{
  "success": false,
  "count": 0,
  "data": [],
  "messages": [
    { "code": "ENTITLEMENT_DENIED", "message": "Asset not licensed for this token." }
  ]
}
```

See [Error handling](/reference/error-handling) for the full list of codes and agent actions.

## Example — property characteristics (abridged)

```json theme={null}
{
  "success": true,
  "count": 1,
  "data": [{
    "clip": "123456789",
    "propertyCharacteristics": {
      "land": { "landUseCodeDescription": "Single Family Residence" },
      "structure": [{ "actualYearBuilt": 2012, "livingSquareFootage": 2450 }]
    }
  }],
  "messages": []
}
```

<Tip>
  For AI agents: after every tool call, check `messages` before summarising results.
  Non-empty messages often explain why a result is partial, estimated, or about to change.
</Tip>