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

# Prompting patterns

> Reliable patterns for orchestrating Cotality tools from an LLM agent — identity-first, exclusion-aware, and envelope-checked.

## Why patterns matter

LLMs call tools accurately when workflows are **explicit and constrained**. These patterns
encode the rules that keep Cotality tool calls correct and prevent common agent failures
like hallucinated CLIPs, invalid temporal queries, and fabricated values on 404.

***

## Pattern 1 — Identity before data

Always resolve an address to a [CLIP](https://develop.cotality.com/ontology/identifiers.md) before calling any data tool.
Never guess or fabricate a CLIP.

```text theme={null}
User: "What's the roof condition at 123 Main St, Austin TX 78701?"

Agent:
  1. clip-find_property_by_address("123 Main St, Austin TX 78701") → clip
  2. pd-get_property_characteristics([clip]) → structure[]
  3. Report universalRoofCoverCode + roof age; note if yearBuiltModeledIndicator = 1 (estimate)
```

***

## Pattern 2 — Check exclusions before calling

Every data tool page has an **Exclusions** row. Check it before calling. Do not send
commercial or non-U.S. queries to U.S. residential tools.

```text theme={null}
if property_type == "commercial":
    → use commercial-capable products, not residential analytics tools
if country != "US":
    → stop and explain scope to user
```

***

## Pattern 3 — Structure loop

A parcel can have multiple buildings. Check before assuming a single structure.

```text theme={null}
chars = pd-get_property_characteristics([clip])
buildings = chars.data[0].propertyCharacteristics.structure

if len(buildings) > 1:
    → ask user: "This parcel has {n} structures. Which building?"
    → or iterate all and summarise
else:
    → proceed with buildings[0]
```

***

## Pattern 4 — Temporal correctness

Set date ranges to the asset's cadence. See [Data freshness](https://develop.cotality.com/ontology/data-freshness.md).

```text theme={null}
Market and HPI data → MONTHLY cadence
  Use:   { "startDate": { "year": 2024, "month": 1 }, "endDate": { "year": 2024, "month": 12 } }
  Avoid: requesting daily or real-time values

Climate Risk scores → ANNUAL model updates
  Use:   latest available; do not request intra-year delta
```

***

## Pattern 5 — Envelope check

The CLIP, property, risk, and analytics MCP tools return only `data` and `count`. Check for a
tool error first, then check `count`, before reading `data`.

```text theme={null}
resp = call_tool(...)

if resp.is_error:
    err = parse(resp)            # { code, message, retryable }
    → retry only if err.retryable; otherwise route to error handling
    → do not read data

if resp.count == 0:
    → report no results; never fabricate
```

> [!WARNING]
>
> Do not test `resp.success` on these tools — there is no `success` field, so the check never
> becomes true. "No match" is a successful response with `count` of `0`, not an error.

See [Response envelope](https://develop.cotality.com/reference/response-envelope.md) and [MCP tool errors](https://develop.cotality.com/reference/mcp-errors.md).

***

## Pattern 6 — Modelled vs. recorded data

Some fields are statistical estimates, not county records. Always check indicator fields
before presenting data as authoritative.

```text theme={null}
if yearBuiltModeledIndicator == 1:
    → present actualYearBuilt as "estimated" not "recorded"

Age of Roof:
    → always a model estimate; present with confidence rank
    → never present as a county-recorded value
```

***

## Pattern 7 — Multi-agent research

For complex workflows, coordinate specialized agents against one MCP source:

```text theme={null}
Portfolio analysis:
  - Research agent   → batch-resolves addresses to CLIPs
  - Risk agent       → scores climate perils per CLIP
  - Market agent     → pulls HPI and trend data per geography
  - All share the same response envelope and CLIP identity spine
```

> [!TIP]
>
> Turn these patterns into ready-to-use system instructions with
> [System prompt templates](https://develop.cotality.com/reference/system-prompt-templates.md).
