Prompting patterns - Cotality developer portal

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 before calling any data tool. Never guess or fabricate a CLIP.

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.

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.

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.

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.

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

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 and MCP tool errors.

Pattern 6 — Modelled vs. recorded data

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

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:

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

Turn these patterns into ready-to-use system instructions with System prompt templates.

​Why patterns matter

​Pattern 1 — Identity before data

​Pattern 2 — Check exclusions before calling

​Pattern 3 — Structure loop

​Pattern 4 — Temporal correctness

​Pattern 5 — Envelope check

​Pattern 6 — Modelled vs. recorded data

​Pattern 7 — Multi-agent research

Why patterns matter

Pattern 1 — Identity before data

Pattern 2 — Check exclusions before calling

Pattern 3 — Structure loop

Pattern 4 — Temporal correctness

Pattern 5 — Envelope check

Pattern 6 — Modelled vs. recorded data

Pattern 7 — Multi-agent research