> ## 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](/ontology/identifiers) 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_full_address("123 Main St, Austin TX 78701") → clip
  2. pc-characteristics_by_clips_tool([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 = pc-characteristics_by_clips_tool([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](/ontology/data-freshness).

```text theme={null}
Market and HPI data → MONTHLY cadence
  Use:   { "from": { "year": 2024, "month": 1 }, "to": { "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

After every tool call, read `success`, `count`, and `messages` before reading `data`.

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

if not resp.success:
    → route to error handling; do not read data

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

if resp.messages:
    → surface messages to user (warnings, deprecations, partial matches)
```

See [Response envelope](/reference/response-envelope) and [Error handling](/reference/error-handling).

***

## 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](/reference/system-prompt-templates).
</Tip>