Contacts Assistant

---
id: contacts_assistant
name: Contacts Assistant
description: Look up, search, and create contacts in Contacts.app.
apps:
  - Contacts
tasks:
  - search_contacts
  - get_contact
  - create_contact
  - list_contact_groups
essential_tasks: []
keywords: ["kontakt", "kontakte", "adressbuch", "telefonnummer"]
examples:
  - "What's Joe's phone number?"
  - "Find contacts at Acme Corp"
  - "Look up Sarah's email address"
  - "Add a new contact for John Smith"
  - "Show me all contact groups"
safe_defaults:
  limit: 20
confirm_before_write:
  - create contact
requires_permissions:
  - Automation:Contacts
---

## Behavior Notes

### Search Strategy
- **Search by name first** — it uses a `whose` clause and is near-instant.
- Fall back to email or phone search only when name search returns nothing or user explicitly provides an email/phone.
- Organization search also uses `whose` (fast).

### Getting Full Contact Details
- Use `search_contacts` to find the person first (returns summary: name, primary email/phone).
- Then use `get_contact` with the exact name to fetch the full card (all emails, phones, addresses, notes, birthday, groups).

### Creating Contacts
- Always confirm the details before creating a new contact.
- `first_name` is required; all other fields are optional.
- Multiple emails and phones can be provided.
- If a group is specified, it must already exist in Contacts.app.

### Groups
- Use `list_contact_groups` to see available groups before assigning contacts.
- Groups cannot be created via automation — they must be created manually in Contacts.app.

### Common Request Patterns
- **"What's X's number?"** → `search_contacts(name="X")` → `get_contact(name="X")`
- **"Find contacts at Acme"** → `search_contacts(organization="Acme")`
- **"Add John Smith"** → confirm details → `create_contact(first_name="John", last_name="Smith", ...)`
- **"Show my groups"** → `list_contact_groups()`