> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpressbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Contacts & CRM Tools

> Search contacts, manage labels, custom fields and pipelines, and apply bulk changes.

## What is this?

These tools cover your customer records: finding contacts, reading their details, tagging them, setting custom fields, moving them through pipelines, and creating labels, fields and pipelines. `apply_as_bulk` changes many records at once from a filter, with one approval.

These tools belong to the [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md). Each tool below shows its **Mode** (**Read** runs immediately; **Write** asks your MCP client to confirm first) and the **Permission needed** for it to appear for your key — "None" means every connected key sees it.

## What can I do here?

* Search contacts and read their labels and custom fields
* Update a contact, add or remove labels, set a custom field, or move a pipeline stage
* Create labels, custom fields and pipelines
* Apply one change to many contacts or conversations and follow its progress

## Tools

### `search_contacts`

Search contacts in the user's current channel by name, phone or email, optionally filtered to one label. Returns at most 20 contacts; say so when the answer may be incomplete.

**Mode:** Read · **Permission needed:** `contacts:view`

### `get_contact`

Get one contact's details (name, phone, email, status, labels, custom fields).

**Mode:** Read · **Permission needed:** `contacts:view`

### `list_labels`

List the contact labels defined in the user's current channel (name, description). Use it before tagging a contact or filtering contacts by label: only these exact names are valid.

**Mode:** Read · **Permission needed:** `labels:view`

### `list_custom_fields`

List the custom contact fields defined in the user's current channel with their type and, for dropdowns, the allowed options. Use it before reading or setting a custom field value.

**Mode:** Read · **Permission needed:** `custom_fields:view`

### `list_pipelines`

List the sales/process pipelines of the user's current channel with their stages in board order. Use it before moving a contact to a stage or when the user asks about their pipeline setup.

**Mode:** Read · **Permission needed:** `pipeline:view`

### `update_contact`

Change a contact's name, email or status (active, blocked, unsubscribed).

**Mode:** Write · **Permission needed:** `contacts:edit`

### `set_custom_field`

Set one custom field on a contact. The field must already exist for this channel.

**Mode:** Write · **Permission needed:** `contacts:edit`

### `add_contact_label`

Add an existing label to a contact. The label must already be defined for this channel.

**Mode:** Write · **Permission needed:** `contacts:edit`

### `remove_contact_label`

Remove a label from a contact.

**Mode:** Write · **Permission needed:** `contacts:edit`

### `move_pipeline_stage`

Move a contact to another stage of a CRM pipeline in this channel.

**Mode:** Write · **Permission needed:** `pipeline:edit`

### `create_label`

Create a new contact label in the user's current channel. Check `list_labels` first — names are unique per channel (case-insensitive), so an existing label is reported instead of duplicated.

**Mode:** Write · **Permission needed:** `labels:create`

### `create_custom_field`

Create a new contact custom field in the user's current channel. Check `list_custom_fields` first — names are unique per channel. For dropdown fields, options must be supplied.

**Mode:** Write · **Permission needed:** `custom_fields:create`

### `create_pipeline`

Create a new CRM pipeline in the user's current channel, with its stages in order. Without stages it gets the standard set (New Lead, Follow-up, Converted, Not Interested). Check `list_pipelines` first to avoid a duplicate name.

**Mode:** Write · **Permission needed:** `pipeline:create`

### `add_pipeline_stage`

Add a stage to the end of one of the channel's pipelines (id from `list_pipelines`).

**Mode:** Write · **Permission needed:** `pipeline:create`

### `apply_as_bulk`

Apply one change to many contacts or conversations at once, chosen by a filter (never a list) — for example "add the label VIP to every contact whose name starts with A" or "close all conversations with no customer message for 30 days". One approval covers the whole change, which shows how many records match (up to 50,000 per change). It runs in the background; check it with `get_bulk_job`. Labels, custom fields and stages must already exist.

**Mode:** Write · **Permission needed:** The permission of the change being applied

### `get_bulk_job`

Progress of a bulk change started with `apply_as_bulk`: status, how many records are done, succeeded and failed.

**Mode:** Read · **Permission needed:** None

## Troubleshooting / Technical Notes

* **A tool I expect isn't offered.** The MCP server only offers tools whose required permission your API key's owner holds, re-checked on every call. Grant the permission shown on the tool — see [Team](https://docs.xpressbot.org/workspace/team.md).
* **A Write tool never seems to run.** Your MCP client asks you to approve every Write tool call. Check for a pending approval prompt.
* **A call returns an error.** See [MCP errors](https://docs.xpressbot.org/api-reference/mcp/errors.md).

## Related docs

* [Workspace MCP tool catalog](https://docs.xpressbot.org/api-reference/mcp/workspace/tools/overview.md)
* [Workspace MCP](https://docs.xpressbot.org/api-reference/mcp/workspace/overview.md)
* [Overview](https://docs.xpressbot.org/workspace/contacts/overview.md)
* [Labels](https://docs.xpressbot.org/workspace/contacts/labels.md)
* [Custom Fields](https://docs.xpressbot.org/workspace/contacts/custom-fields.md)
* [Pipelines](https://docs.xpressbot.org/workspace/contacts/pipelines.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.