MCP tools — Contacts

The Contacts tool group covers the full lifecycle: discovery, lookup, mutation, and bulk operations.

Tool	Annotation	Purpose
list_contacts	IsReadOnly, IsIdempotent	Search/list with pagination and filters
get_contact	IsReadOnly, IsIdempotent	Fetch one with tags + recent messages
create_contact	IsDestructive(false)	New contact (E.164 phone)
update_contact	IsDestructive(false), IsIdempotent	Update name/email/phone
tag_contact	IsDestructive(false), IsIdempotent	Add or remove tags
delete_contact	IsDestructive	Permanent delete
import_contacts	IsDestructive(false)	Bulk upsert from a list of records

list_contacts

Search and list contacts. Supports filtering by name/phone/email, tag, and opt-in status.

Input	Type	Default	Notes
search	string	—	Substring match against name/phone/email
tag	string	—	Exact tag name
opted_in_only	boolean	true	Skip opted-out contacts
page	integer	1
per_page	integer	25	Capped at 100

Returns { data: Contact[], meta: { current_page, last_page, per_page, total } }.

get_contact

Get detailed contact info with tags and recent messages.

Input	Type	Notes
id	UUID	Required if phone/email not provided
phone	string	E.164
email	string

Returns the contact + tag list + last N messages in both directions.

create_contact

Create a new contact. Phone number should be in E.164 format.

Input	Type	Required
phone	string	yes
name	string	no
email	string	no
tags	string[]	no
metadata	object	no
locale	string	no
source	string	no

Upserts on (tenant_id, phone).

update_contact

Update contact fields such as name, email, or phone.

Input	Type
id	UUID (required)
name, email, phone, locale, metadata	optional

Only provided fields are written. metadata is merged shallowly.

tag_contact

Add or remove tags on a contact.

Input	Type	Notes
id	UUID	required
add_tags	string[]	tags to attach (created on the fly)
remove_tags	string[]	tags to detach (the tag definition stays)

delete_contact

Permanently delete a contact.

IsDestructive — the agent client will prompt every time.

import_contacts

Bulk import or upsert contacts from a list of records. Each record must have a phone number; matched on tenant_id + phone. Existing contacts are updated, missing ones created. Tags are added without removing existing ones. Returns counts: imported / updated / skipped, plus per-row errors.

Input	Type
contacts	array of {phone, name?, email?, tags?, metadata?} records

Returns { imported, updated, skipped, errors: { row, message }[] }. No CSV file needed — pass the records directly. Practical limit: a few thousand per call. For very large imports, break into batches client-side.