# Attio People Agent Rules

## Attio Profile

The profile at ``./documents/connections/[service-name].md`` shows:

- **People attributes** — which attributes exist and how populated they are
- **Linked objects** — what other objects (companies, etc.) are connected to people
- **Data patterns** — common job titles, sample values

Check the profile before querying to know which attributes are actually populated in this workspace. Don't filter on attributes with 0% population.

## Interpret Intent, Not Just Words

Users say "people at Stripe" not `{"company": {"$contains": "rec_abc"}}`. They say "engineers" not `{"job_title": {"$contains": "Engineer"}}`.

**The pattern:** Understand what they want → construct filters → run the query → present results clearly.

## Query Mapping

Translate natural language to Attio filters:

| User says                  | Filter                                              |
| -------------------------- | --------------------------------------------------- |
| "at [company]"             | `{"company": {"$contains": "..."}}`\*               |
| "with email"               | `{"email_addresses": {"$not_empty": true}}`         |
| "without email"            | `{"email_addresses": {"$is_empty": true}}`          |
| "engineers" / "developers" | `{"job_title": {"$contains": "Engineer"}}`          |
| "CEOs" / "founders"        | Use `$or` with multiple title patterns              |
| "added recently" / "new"   | `{"created_at": {"$gt": "date"}}`                   |
| "@domain.com emails"       | `{"email_addresses": {"$contains": "@domain.com"}}` |

\*For company filters, you'd need the company record ID. If unknown, note this limitation.

## Presenting Results

**Lead with what matters.** For people: name, email, job title, company.

**Keep it scannable.** For small results (≤10), list each person. For larger results, summarize with counts and offer to show details.

**Format consistently:**

```
👤 Jane Smith
   Senior Engineer at Acme Corp
   jane@acme.com

👤 John Doe
   CEO at Startup Inc
   john@startup.io
```

## Pagination

The code handles pagination automatically. For large result sets:

- Report total count: "Found 150 people matching your criteria"
- Show a sample: first 5-10 results
- Offer options: "Want me to show more, or narrow the search?"

## Limitations

**No company lookup by name.** Company filters need record IDs. If user asks for "people at Acme Corp" and you don't have the ID, explain: "I'd need to look up Acme Corp's record ID first. For now, I can search by job title, email domain, or other attributes."

**Read-only.** This skill queries people, it doesn't create or modify records.

## Error Handling

- **No results:** "No people found matching those criteria. Want to broaden the search?"
- **API error:** Report the issue clearly, suggest retrying
- **Invalid filter:** Explain what went wrong with the filter syntax

## When Results Are Exported

Full query results are saved to the session folder. Mention this when relevant: "Full results saved if you need the raw data."