MCP tool errors - Cotality developer portal

Cotality MCP tools signal failure with a structured ToolError rather than a success: false envelope. The CLIP, property characteristics, risk, and market analytics tools all use the same shape, so an agent can handle them with one code path.

Retryable means the request could succeed if you send it again unchanged — a transient upstream fault, not a problem with your input. A non-retryable error will fail identically every time until you change something.

This page covers the MCP tool error contract. For the REST APIs and their HTTP status codes, see Error handling.

Error shape

A failed tools/call returns an error whose content is a JSON object with three fields:

{
  "code": "UPSTREAM_TIMEOUT",
  "message": "The upstream data service timed out. Retry shortly.",
  "retryable": true
}

Field	Type	Description
`code`	`string`	Stable, machine-readable error class. Branch on this, never on `message`.
`message`	`string`	Human-readable explanation. Safe to surface to a user; wording may change.
`retryable`	`boolean`	Whether re-issuing the identical request could succeed.

Error codes

Code	`retryable`	Cause	What to do
`INVALID_INPUT`	`false`	Input failed validation — wrong type, out-of-range value, too many items, or a malformed identifier	Correct the arguments. The same request will always fail.
`NOT_FOUND`	`false`	CLIP tools only. The upstream lookup service explicitly reported no match for the CLIP or address	Report no match to the user. Never fabricate a value.
`UPSTREAM_ERROR`	`true`	A downstream Cotality data service returned an error	Retry with exponential backoff, capped at 3 attempts.
`UPSTREAM_TIMEOUT`	`true`	A downstream Cotality data service did not respond in time	Retry with exponential backoff, capped at 3 attempts.
`INTERNAL_ERROR`	`false`	An unexpected server-side failure	Do not retry. Escalate to Cotality support if it persists.

NOT_FOUND is raised only by clip-find_property_by_clip and clip-find_property_by_address. The property characteristics, risk, and analytics tools have no “not found” error at all. On those tools an unmatched CLIP or an uncovered geography comes back as a successful response with count of 0 and an empty data array. An agent that waits for an error will silently treat “no data” as “still loading”. Always check count.

Using the `retryable` flag

retryable is the single most actionable field for an agent. It removes the need to maintain a list of which codes are transient.

result = call_tool(name, arguments)

if result.is_error:
    err = parse(result)
    if err.retryable and attempt < 3:
        wait = min(base * (2 ** attempt) + jitter, max_wait)
        sleep(wait); retry()
    else:
        surface_to_user(err.message); stop()

Never retry a retryable: false error. INVALID_INPUT and NOT_FOUND are deterministic — a retry loop burns your rate limit without any chance of success.

Input limits

Most INVALID_INPUT errors come from these constraints. Validate against them before calling.

CLIP inputs

Applies to pd-get_property_characteristics, at-get_property_analytics, at-get_property_roof_age, and at-get_property_climate_risk.

Constraint	Value
`clips` minimum items	1
`clips` maximum items	50 per request
Item format	Non-empty numeric string — digits only (`^\d+$`)

For clip-find_property_by_clip, the single clip argument follows the same digit-only rule.

Batch up to 50 CLIPs in one call rather than issuing 50 single-CLIP calls. It is one request against your quota instead of 50.

Analytics filter inputs

Applies to all five market and trend analytics tools.

Constraint	Value
`geographyTypeValues` minimum items	1
`geographyTypeValues` maximum items	50 per request
Item format	Non-empty alphanumeric string (`^[a-zA-Z0-9]+$`) — no spaces, hyphens, or punctuation
`year`	Integer, 1900–2100
`month`	Integer, 1–12
`timeRange`	Omit entirely for the latest period. If present, both `startDate` and `endDate` are required.

A partial timeRange — one of startDate or endDate — is rejected with INVALID_INPUT. Omit the whole object to get the latest available data.

Scope failures

A tool called without its required scope fails before the tool executes. Treat it as permanently non-retryable and contact your account team to request the missing entitlement.

Rate limits — quota and 429 back-off
Error handling — REST API status codes

​Error shape

​Error codes

​Using the retryable flag

​Input limits

​CLIP inputs

​Analytics filter inputs

​Scope failures

​Related

Error shape

Error codes

Using the `retryable` flag

Input limits

CLIP inputs

Analytics filter inputs

Scope failures

Related