Response envelope - Cotality developer portal

Cotality returns two different response shapes. Which one you get depends on what you call.

You are calling	Envelope	Success signalled by
CLIP, property characteristics, risk, and market analytics MCP tools	`data` + `count`	The MCP error flag — see MCP tool errors
REST APIs, and the valuation and credit MCP tools that wrap them	`success` + `count` + `data` + `messages`	The `success` field

Do not test response.success against the CLIP, property, risk, or analytics MCP tools. Those tools never return a success field, so the check reads as missing on every call — including successful ones. Branch on the MCP error flag instead.

MCP tool envelope

The CLIP, property characteristics, climate risk, and market analytics tools return a two-field object on success.

{
  "count": 1,
  "data": [ /* tool-specific result objects */ ]
}

Field	Type	Always present	Meaning
`count`	`integer`	Yes	Number of items in `data`
`data`	`array`	Yes	Tool-specific payload. Shape differs per tool.

Failure is not expressed in this object at all. A failed call returns an MCP error whose content is a ToolError payload with code, message, and retryable. See MCP tool errors.

Fields with no value are omitted from the response rather than returned as null. Treat an absent field and a null field as the same thing — no data available for that property. Field reference tables on the tool pages list every field a tool can return, not every field it will return.

Rules for consumers

Check for an MCP error first

Your MCP client surfaces tool failures as an error result. Handle that before reading data. Read the retryable flag to decide whether a retry can help.

Treat a count of 0 as a valid answer

An unmatched CLIP, address, or geography is not an error on these tools. You get a successful response with count of 0 and an empty data array. Report “no match” — never fabricate a value.

Respect count

Iterate exactly count items from data. Do not assume a single result — parcels, properties, and geographies can return multiple records.

Example — property characteristics (abridged)

{
  "count": 1,
  "data": [{
    "clip": "123456789",
    "propertyCharacteristics": {
      "land": { "landUseCodeDescription": "Single Family Residence" },
      "structure": [{ "actualYearBuilt": 2012, "livingSquareFootage": 2450 }]
    }
  }]
}

REST envelope

Cotality REST endpoints — and the valuation and credit MCP tools that wrap them — return a four-field envelope. Parse all four before reading the payload.

{
  "success": true,
  "count": 1,
  "data": [ /* result objects */ ],
  "messages": []
}

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	Payload. Shape differs per endpoint.
`messages`	`array`	Yes	Warnings, deprecations, partial-match notices, and info. Always surface non-empty values.

Error envelope

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

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

See Error handling for the full list of codes and agent actions.

For AI agents: on REST responses, check messages before summarising results. Non-empty messages often explain why a result is partial, estimated, or about to change.

MCP tool errors — the code, message, and retryable contract
Error handling — REST status codes and message codes

​MCP tool envelope

​Rules for consumers

​Example — property characteristics (abridged)

​REST envelope

​Error envelope

​Related

MCP tool envelope

Rules for consumers

Example — property characteristics (abridged)

REST envelope

Error envelope

Related