Contacts

Tools in the contacts scope, callable over space-mcp (tools/call) or space-api (REST) with a wks_live_* key that grants contacts.

add_contact_note

Scope: contacts:write

Add a short note to a contact's Memory — the running log a human reads to remember a person. One plain sentence per note. Preferred way to 'remember X about' or 'log a call/message on' a contact.

add_social_identity

Scope: contacts:write

Attach a social identity (Instagram/X/LinkedIn/Facebook/TikTok/etc.) to a contact. Provide handle (no leading @) and/or external_id. This is what powers inbound DM matching — prefer it over the legacy social_media JSONB.

bulk_tag_contacts

Scope: contacts:write

Add and/or remove tags across many contacts in ONE call. Pass contact_ids plus add_tag_ids and/or remove_tag_ids. Prefer this over looping tag_contact.

count_contacts

Scope: contacts:read

Count contacts matching structured filters (search/company/location/relationship_type/tag_ids/has_email/has_phone/auto_created/created_after/created_before). Cheaper than listing when you only need a number.

create_audience

Scope: contacts:write

Create a static (list) audience, optionally seeded with contact ids. Audiences target both email and SMS campaigns.

create_contact

Scope: contacts:write

Create a new contact in the space. Only name is required (email is optional — social-DM/walk-in contacts have none). Name is split into first/last automatically; pass first_name/last_name explicitly for precise splitting. tags are matched/created by name.

create_contact_section

Scope: contacts:write

Add a content section to a contact (documents/links/custom boxes). For simple 'remember X' notes prefer add_contact_note. section_type: notes | documents | links | insights | custom.

create_tag

Scope: contacts:write

Create a new contact tag. Colors: gray, red, orange, amber, yellow, green, teal, blue, indigo, purple, pink.

delete_contact

Scope: contacts:write

Permanently delete ONE contact by its id (cascades to its tags, notes, sections, and social identities). Destructive and irreversible — only call with an explicit contact_id the user unambiguously asked to delete. There is no bulk/filter delete; delete one id at a time.

delete_contact_section

Scope: contacts:write

Permanently delete a contact section. Destructive.

delete_tag

Scope: contacts:write

Permanently delete a tag from this space (removes it from every contact). Destructive.

get_contact

Scope: contacts:read

Fetch ONE contact by id with everything attached: all columns, tags, social identities, and recent sections. Use this to read a contact's full profile before editing.

list_audiences

Scope: contacts:read

List audiences (saved contact groups used to target email and SMS campaigns).

list_contact_notes

Scope: contacts:read

List a contact's Memory notes, newest first.

list_contact_sections

Scope: contacts:read

List the content sections (notes/documents/links/insights/custom) attached to a contact.

list_contacts

Scope: contacts:read

List contacts in the space. Supports search and pagination.

list_tags

Scope: contacts:read

List the contact tags in this space (id, name, color, description). Call before tagging to resolve tag names → ids.

merge_contacts

Scope: contacts:write

Merge two duplicate contacts: fold source_contact_id into target_contact_id. All threads, tags, sections, and social identities move to the target, then the source row is deleted. Prefer this over delete for de-duplication. Destructive — confirm before merging curated contacts.

remove_social_identity

Scope: contacts:write

Delete a social identity row from a contact.

tag_contact

Scope: contacts:write

Attach one tag to one contact.

untag_contact

Scope: contacts:write

Detach one tag from one contact.

update_audience

Scope: contacts:write

Rename an audience or add/remove member contacts.

update_contact

Scope: contacts:write

Update fields on an existing contact. Only supplied fields change (pass null to clear one). Pass tag_ids to REPLACE the entire tag set (omit to leave tags unchanged). Get the contact first to resolve its id.

update_contact_section

Scope: contacts:write

Update an existing contact section's title, content, type, metadata, or sort_order.

update_social_identity

Scope: contacts:write

Update an existing social identity row (handle, external_id, profile_url, display_name).

update_tag

Scope: contacts:write

Rename or restyle an existing tag.