These 62 tools call the same endpoints as the Data Platform section of the API Reference. Each tool runs with the permissions of the Whippy user who authorized the connection and the OAuth scopes they granted.
The Behavior column comes from the MCP tool annotations Whippy publishes. Treat these labels as hints, not guarantees: they may omit external effects (for example, a Write tool can send a message to a recipient), and clients are not required to ask for confirmation before running a tool.
| Tool | Behavior | Endpoint | What it does |
|---|
create_contact | Destructive | POST /v1/contacts | Creates a contact (or updates the existing one when phone or external_id already exists). |
delete_contact | Destructive | DELETE /v1/contacts/{id} | Archives a contact by ID without permanently deleting the record. Confirm the ID with show_contact or search_contacts first. |
filter_contacts | Read-only | POST /v1/contacts/filter | Filters contacts with WQL. Prefer over search_contacts for tags, messages, lists, segments, or custom objects. |
list_contact_sequences | Read-only | POST /v1/contacts/{id}/sequences | Lists the sequences a specific contact is enrolled in (and related run state). Use list_sequences to browse org sequences, or list_sequence_contacts for everyone on one sequence. |
merge_contacts | Destructive (idempotent) | POST /v1/contacts/merge_contacts | Merges two contacts into one surviving contact (to); the from contact becomes state merged and unusable. |
search_contacts | Read-only | POST /v1/contacts/search | Search contacts by name, email, phone, ids, or date ranges. |
show_contact | Read-only | GET /v1/contacts/{id} | Returns one contact by ID, including notes, communication preferences, and tags. |
update_contact | Destructive | PUT /v1/contacts/{id} | Updates fields on an existing contact by ID (name, email, phone, custom data, etc.). |
upsert_contacts | Destructive | POST /v1/contacts/upsert | Bulk creates or updates contacts, optionally opting them into channels and associating custom object records. |
| Tool | Behavior | Endpoint | What it does |
|---|
create_bulk_custom_events | Write | POST /v1/custom_events/bulk | Records many analytics custom events in one request for metrics dashboards. |
create_custom_event | Write | POST /v1/custom_events | Records one analytics custom event for metrics. Prefer create_bulk_custom_events for many events. Not for inbox messages (send_sms) or audit logs (search_audit_logs). |
| Tool | Behavior | Endpoint | What it does |
|---|
create_dashboard | Write | POST /v1/dashboards | Creates a dashboard layout referencing saved metric IDs. Build metrics with create_metric / preview_metric first. Built-in metrics belong on built-in dashboards. |
delete_dashboard | Destructive (idempotent) | DELETE /v1/dashboards/{id} | Deletes a dashboard (metrics themselves are not deleted). Built-in whippy dashboards cannot be deleted. |
list_dashboards | Read-only | GET /v1/dashboards | Lists analytics dashboards (layouts of saved metrics). Prefer list_metrics / create_metric before adding charts to a dashboard. |
show_dashboard | Read-only | GET /v1/dashboards/{id} | Returns a dashboard definition and runs its metrics over the default timeframe or provided start/end. |
update_dashboard | Destructive | PUT /v1/dashboards/{id} | Updates a dashboard (partial). metrics replaces the layout when sent. Built-in whippy dashboards cannot be updated. |
| Tool | Behavior | Endpoint | What it does |
|---|
create_lead | Destructive | POST /v1/leads | Creates a lead record (inbound lead capture). Prefer create_contact / upsert_contacts for general contact CRUD. |
| Tool | Behavior | Endpoint | What it does |
|---|
create_contact_list | Destructive | POST /v1/contacts/lists | Creates a static contact list. contacts is required — pass contacts: [] for an empty list, or contact objects to seed membership. Add/remove members later with update_contact_list_contacts. |
delete_contact_list | Destructive (idempotent) | DELETE /v1/contacts/lists/{id} | Deletes a contact list. Confirm with show_contact_list first. |
list_contact_lists | Read-only | GET /v1/contacts/lists | Lists static contact lists (manual membership), not WQL segments or tags. |
show_contact_list | Read-only | GET /v1/contacts/lists/{id} | Returns one contact list by ID. Resolve the ID with list_contact_lists first. |
update_contact_list | Destructive (idempotent) | PUT /v1/contacts/lists/{id} | Updates list metadata (name/description). To change members, use update_contact_list_contacts. |
update_contact_list_contacts | Destructive | PUT /v1/contacts/lists/{id}/contacts | Adds, removes, or overwrites contacts on a static list. |
| Tool | Behavior | Endpoint | What it does |
|---|
create_metric | Write | POST /v1/metrics | Saves a metric (chart over events). Build with list_metric_events + list_metric_event_fields; try preview_metric first. Built-in whippy metrics cannot be created this way. |
delete_metric | Destructive (idempotent) | DELETE /v1/metrics/{id} | Deletes a saved metric and removes it from dashboards. Built-in whippy metrics cannot be deleted. |
list_metric_event_fields | Read-only | GET /v1/metrics/events/fields | Lists the fields a metric event can filter, group and aggregate by, with what each supports. |
list_metric_events | Read-only | GET /v1/metrics/events | Lists events a metric can chart (whippy_event, custom_event, non_custom reports) and which chart types each supports. Call before create_metric / preview_metric. |
list_metrics | Read-only | GET /v1/metrics | Lists saved analytics metrics (charts). Prefer preview_metric to try a definition; list_metric_events + list_metric_event_fields to build events. |
preview_metric | Read-only | POST /v1/metrics/preview | Runs a metric definition without saving it. Prefer this to validate charts before create_metric. Same event-building rules as create_metric. |
show_metric | Read-only | GET /v1/metrics/{id} | Runs/returns a saved metric over a time window (start/end or default trailing weeks). Resolve the ID with list_metrics. |
update_metric | Destructive | PUT /v1/metrics/{id} | Updates a saved org metric (partial). Built-in (source: whippy) metrics cannot be updated. events replaces as a whole when sent. |
| Tool | Behavior | Endpoint | What it does |
|---|
archive_custom_object | Destructive | POST /v1/custom_objects/archive | Soft-archives custom object records matching property filters (does not delete the schema). |
create_custom_object | Destructive (idempotent) | POST /v1/custom_objects | Creates a custom object schema (type). Add properties with create_custom_property, then create records. |
delete_custom_object | Destructive | DELETE /v1/custom_objects/{id} | Deletes a custom object schema. Prefer archive_custom_object when soft-archive is intended. |
list_custom_objects | Read-only | GET /v1/custom_objects | Lists custom object schemas (types + property definitions) for the organization, including whippy_associations (contact links) and associations (object↔object hops). |
update_custom_object | Destructive | PUT /v1/custom_objects/{id} | Updates a custom object schema's metadata. Property changes use create/update/delete_custom_property. |
| Tool | Behavior | Endpoint | What it does |
|---|
list_communication_preferences | Read-only | GET /v1/contacts/communication_preferences | Lists channel opt-in/opt-out preferences across the organization, optionally filtered by channel. To inspect one contact, use show_contact. To change preferences, use opt_in_communication_preference or opt_out_communication_preference. |
opt_in_communication_preference | Destructive | POST /v1/contacts/communication_preferences/opt_in | Opts contacts into one or more channels so they can receive messages. Pair with list_channels for channel IDs. Use opt_out_communication_preference to revoke. |
opt_out_communication_preference | Destructive | POST /v1/contacts/communication_preferences/opt_out | Opts contacts out of messaging on specific channels or channel types (stops outbound). |
| Tool | Behavior | Endpoint | What it does |
|---|
create_segment | Write (idempotent) | POST /v1/contacts/segments | Creates a saved contact segment from a WQL filters payload (same shape as filter_contacts). |
delete_segment | Destructive (idempotent) | DELETE /v1/contacts/segments/{id} | Deletes a contact segment. Confirm with show_segment first. |
list_segments | Read-only | GET /v1/contacts/segments | Lists saved contact segments (named WQL audiences). Only active segments are returned. |
search_segments | Read-only | POST /v1/contacts/segments/search | Finds contact segments using WQL filters on segment metadata. Only active segments. Prefer list_segments for a simple roster; filter_contacts to evaluate an audience without saving a segment. |
show_segment | Read-only | GET /v1/contacts/segments/{id} | Returns one segment by ID including its WQL filters. Resolve the ID with list_segments / search_segments. |
update_segment | Destructive | PUT /v1/contacts/segments/{id} | Updates a segment's name, color, or WQL filters. Validate new filters with filter_contacts before saving when possible. |
| Tool | Behavior | Endpoint | What it does |
|---|
convert_tag | Destructive (idempotent) | PUT /v1/tags/{id}/convert | Converts a system tag into a standard editable tag for the organization. |
create_tag | Destructive (idempotent) | POST /v1/tags | Creates a contact tag (label). After creating, add contacts with update_tag_contacts, or find tagged contacts with filter_contacts. |
delete_tag | Destructive (idempotent) | DELETE /v1/tags/{id} | Deletes a tag. Confirm with show_tag first. |
list_tags | Read-only | GET /v1/tags | Lists organization tags (default type standard = contact tags). Use search for a name substring. Resolve tag ids here, then filter_contacts (WQL on resource tag) to find contacts with those tags — search_contacts does not filter by tag. |
show_tag | Read-only | GET /v1/tags/{id} | Returns one tag by ID. Resolve the ID with list_tags first. |
update_tag | Destructive | PUT /v1/tags/{id} | Updates tag metadata (name/color/state). To change which contacts have the tag, use update_tag_contacts. |
update_tag_contacts | Destructive | PUT /v1/tags/{id}/contacts | Adds, removes, or overwrites contacts on an active tag (action: add | remove | overwrite). Contacts are matched by phone and may be created/opted in when adding. |
