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

# CRM Cleaning from your AI assistant

> The CRM Cleaning MCP tools, their parameters, the API call behind each one, and example prompts

The [Clustr MCP server](https://docs.clustr-ai.com/mcp-server.md) lets an AI assistant such as Claude run CRM
Cleaning for you: read the queue, apply or dismiss changes, work the findings report,
start scans and change settings. Set it up once from the [MCP server page](https://docs.clustr-ai.com/mcp-server.md),
with sign-in or an API key. The tools below need the CRM Cleaning add-on.

MCP server v1.44.1 or later has every tool below. When each tool arrived:

| Version | Added |
| - | - |
| v1.37.0 | `get_crm_cleaning_queue`, `apply_crm_cleaning_group`, `dismiss_crm_cleaning_group`, `list_crm_cleaning_findings`, `dismiss_crm_cleaning_findings`, `merge_crm_duplicates`, `get_crm_completeness`, `get_crm_cleaning_summary` |
| v1.39.0 | `start_crm_cleaning_scan`, `list_crm_cleaning_runs`, `get_crm_cleaning_run`, `start_crm_enrichment`, `get_crm_enrichment_budget`, `list_crm_cleaning_changes`, `accept_crm_cleaning_change`, `dismiss_crm_cleaning_change`, `list_crm_cleaning_history`, `revert_crm_cleaning_change`, `retry_crm_cleaning_change`, `get_crm_cleaning_settings`, `update_crm_cleaning_settings`, `list_crm_cleaning_templates`, `get_crm_cleaning_capabilities`, `get_crm_health_score` |
| v1.40.0 | `revert_crm_cleaning_batch`, `get_crm_cleaning_suggestions` |
| v1.41.0 | `export_crm_cleaning_history`, `export_crm_cleaning_findings`, `find_crm_record_duplicates`, `get_crm_property_insights`, `refresh_crm_property_insights`. Also the match rate on `get_crm_enrichment_budget`, and `realtime_duplicates`, the alert fields, `primary_rules` and `match_rules` on `update_crm_cleaning_settings` |
| v1.43.0 | The progress (`counted`, `toCount`, `etaSeconds`), `recordsWithoutValue`, `fillBands`, `history` and `previous` on `get_crm_property_insights` |
| v1.44.0 | `list_crm_field_values`, `set_crm_value_mapping`, `delete_crm_value_mapping`; the history filters (`decided_by`, `decided_by_kind`, `action`, `object_type`, `object_id`, `property`, `from`, `to`) on `list_crm_cleaning_history` and `export_crm_cleaning_history` |
| v1.44.2 | `limit` on `export_crm_cleaning_history` and `export_crm_cleaning_findings`, and the 60 KB cap |
| v1.44.1 | Dropdown labels (`label`, `canonical_label`, `mapped_to_label`, `to_label`), the dropdown's `options`, and `skipped` on mappings a scan did not apply, on `list_crm_field_values` |
| v1.45.1 | No new tools. `duplicate_spike_alert`, `completeness_drop_alert` and `duplicate_spike_threshold` now shape the weekly summary's highlights, and property insights are recounted monthly |
| v1.45.2 | No new tools. `enrichment_when_different` on `update_crm_cleaning_settings`; `records_filled`, `records_already_complete`, `records_not_found` and `match_by_object` on `get_crm_enrichment_budget`, where `records_matched` now counts what the provider found |
| v1.45.3 | No new tools. `enrichment_when_different` defaults to `suggest` for contacts |
| v1.45.5 | No new tools. `effective_when_different` on `get_crm_cleaning_settings` |

Your assistant asks before it does anything that writes to your CRM or spends budget:
starting a scan or an enrichment pass, applying or accepting changes, merging records,
reverting or retrying a change, and turning on a rule, enrichment or the schedule.

## The tools

### The queue

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `get_crm_cleaning_queue` | none | The queue, grouped by kind, with counts | `GET /api/crm/cleaning/queue` |
| `list_crm_cleaning_changes` | `action`, `object_type`, `property`, `bucket` (`auto` or `confirm`), `q`, `limit` (default 50, at most 200), `offset` | One page of waiting changes, with before and after values, a link to each record and, for a merge, both records side by side | `GET /api/crm/cleaning/queue/changes` |
| `apply_crm_cleaning_group` | `action` and `object_type` (required), `property`, `bucket` | Apply every waiting change of one kind. For merges, leave `property` empty; only certain merges are applied in bulk, and Likely merges must be accepted one at a time. | `POST /api/crm/cleaning/queue/apply` |
| `dismiss_crm_cleaning_group` | `action` and `object_type` (required), `property`, `suppress` (default `true`) | Dismiss every waiting change of one kind, and by default stop suggesting it | `POST /api/crm/cleaning/queue/dismiss` |
| `accept_crm_cleaning_change` | `change_id` (required) | Apply one waiting change, including a Likely merge | `POST /api/crm/cleaning/changes/{change_id}/accept` |
| `dismiss_crm_cleaning_change` | `change_id` (required) | Dismiss one waiting change or one finding. It is not suggested again for that record. | `POST /api/crm/cleaning/changes/{change_id}/dismiss` |

### History

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `list_crm_cleaning_history` | `state` (`pending`, `accepted`, `applied`, `reverted`, `dismissed`, `failed`, `conflict`, `stale`), `bucket` (`auto`, `confirm`, `flag`), `q`, `decided_by`, `decided_by_kind` (`person`, `automatic`), `action` (rules, comma-separated), `object_type`, `object_id`, `property`, `from` and `to` (RFC 3339), `limit` (default 50, at most 200), `offset` | Every change across all scans, with `revertable` and the reason a change failed | `GET /api/crm/cleaning/history` |
| `export_crm_cleaning_history` | The same filters, plus `limit` (default 200, max 2,000) | The history as CSV text, as **Export CSV** downloads it. At most `limit` rows and about 60 KB of text, cut at a whole row, with a note when there are more. | `GET /api/crm/cleaning/history/export` |
| `revert_crm_cleaning_change` | `change_id` (required) | Put back the old value of an applied change, within 30 days. A field edited in the CRM since is left as it is (conflict). Phone repairs and deal merges can never be reverted. | `POST /api/crm/cleaning/changes/{change_id}/revert` |
| `revert_crm_cleaning_batch` | `action` (required), `run_id`, `object_type` (`contact` or `company`), `property`, `since`, `until` (RFC 3339), `cursor` | Revert every applied change of one rule. Merges and phone repairs are left out. At most 1,000 per call: when `has_more` is true, call again with `cursor` set to `next_cursor`. | `POST /api/crm/cleaning/revert-batch` |
| `retry_crm_cleaning_change` | `change_id` (required) | Queue a failed or conflict change again. On a conflict this overwrites the edit made in the CRM. | `POST /api/crm/cleaning/changes/{change_id}/retry` |

### Findings and duplicates

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `list_crm_cleaning_findings` | `kind`, `detail_kind`, `object_type`, `q`, `limit` (default 50, at most 200), `offset` | The findings report, counted by kind, with a link to each record | `GET /api/crm/cleaning/findings` |
| `export_crm_cleaning_findings` | `kind`, `detail_kind`, `object_type`, `q`, `limit` (default 200, max 2,000) | The open findings as CSV text. At most `limit` rows and about 60 KB of text, cut at a whole row, with a note when there are more. | `GET /api/crm/cleaning/findings/export` |
| `dismiss_crm_cleaning_findings` | `kind` (required), `object_type`, `suppress` (default `false`) | Dismiss every open finding of one kind. `suppress: true` stops reporting it. | `POST /api/crm/cleaning/findings/dismiss` |
| `merge_crm_duplicates` | `change_id` (required): a duplicate finding whose `mergeable` is true | Merge one duplicate group (HubSpot only). Duplicate deals merge only when they share a company and are still open, and a deal merge cannot be reverted. | `POST /api/crm/cleaning/duplicates/{change_id}/merge` |
| `find_crm_record_duplicates` | `object_type` (required): `contact` or `company`; `object_id` (required): the CRM record id | The possible duplicates of one record, why they matched, and whether the match is certain. It reads the stored findings of the last scan or of the [new record check](https://docs.clustr-ai.com/crm-cleaning/checks.md#new-records); it does not match the record again. Read-only. | Internal only |

### Scans and enrichment

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `start_crm_cleaning_scan` | none | Start a scan now. Changes whose rule is on Do it are written to your CRM. | `POST /api/crm/cleaning/scan` |
| `start_crm_enrichment` | none | Run only the enrichment checks, inside the monthly budget (Enrich all). Does nothing while enrichment is off. | `POST /api/crm/cleaning/enrich` |
| `list_crm_cleaning_runs` | `limit` (default 20, at most 100) | Recent runs, newest first, scheduled and enrichment runs included | `GET /api/crm/cleaning/runs` |
| `get_crm_cleaning_run` | `run_id` (required) | One run and its counts: what is waiting, applied, failed or in conflict | `GET /api/crm/cleaning/runs/{run_id}` and `/counts` |
| `get_crm_enrichment_budget` | none | The enrichment budget for this month: cap, used, remaining, reset date, and the match rate (records sent, found, filled, already complete, not found, per object type, and fills per field) | `GET /api/crm/cleaning/budget` |

### Settings

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `get_crm_cleaning_settings` | none | The settings, with `effective_modes`: the mode each rule resolves to, and `effective_when_different`: what enrichment does with a value your CRM already has | `GET /api/crm/cleaning/settings` |
| `update_crm_cleaning_settings` | See below | Change some settings. Only the fields you pass change; everything else, exclusions included, is kept. | `PUT /api/crm/cleaning/settings` |
| `list_crm_cleaning_templates` | none | The ready-made recipes and the settings each applies | `GET /api/crm/cleaning/settings/templates` |
| `get_crm_cleaning_suggestions` | none | Rules on Ask me that your team always accepts, with a message such as "You accepted 48 of 48 formatting fixes. Switch this rule to Do it?" | `GET /api/crm/cleaning/settings/suggestions` |
| `get_crm_cleaning_capabilities` | none | Which checks can fix things on your CRM and which only report | `GET /api/crm/cleaning/capabilities` |

`update_crm_cleaning_settings` takes:

| Parameter | Values |
| - | - |
| `rule_modes` | An object with a mode per rule: `format_normalize`, `canonicalize_domain`, `canonicalize_linkedin_url`, `associate_company`, `merge_contacts`, `merge_companies`, `standardize_value`, `enrichment_fill`. Each is `off`, `review` (Ask me) or `auto` (Do it). Rules you leave out keep their mode. |
| `default_mode` | `off`, `review` or `auto`, for every rule with no mode of its own. `auto` never reaches `standardize_value`, which only its own mode sets to `auto` |
| `merge_enabled` | `false` stops every merge until it is turned back on |
| `realtime_duplicates` | `false` stops checking [new records](https://docs.clustr-ai.com/crm-cleaning/checks.md#new-records) for duplicates as they are created; on by default while merges are on |
| `enrichment_enabled` | `true` lets scans and `start_crm_enrichment` spend the monthly budget |
| `enrichment_audience` | `active` (default), `open_deals` or `everyone` |
| `enrichment_when_different` | What enrichment does when your CRM already has a different value, per object type: `{ "contact": "suggest", "company": "keep" }`. `keep` leaves your value alone; `suggest` proposes the new value as a change that always waits for a person. Unset, contacts suggest and companies keep. Object types you leave out keep their setting. |
| `schedule_enabled` | `true` runs scans automatically |
| `schedule_cadence` | `weekly` (default), `daily`, `monthly` or `hourly` |
| `schedule_day_of_week`, `schedule_day_of_month`, `schedule_hour`, `schedule_minute` | 0 (Sunday) to 6; 1 to 31; 0 to 23; 0 to 59 |
| `schedule_timezone` | An IANA time zone such as `Europe/London`. Default UTC. |
| `escalation_recipients` | Who gets the weekly summary email. Replaces the list; an empty list sends it to the workspace admins. |
| `duplicate_spike_alert`, `completeness_drop_alert` | `false` leaves that [highlight](https://docs.clustr-ai.com/crm-cleaning/health-and-summary.md#weekly-summary-highlights) out of the weekly summary email; both are on by default. Neither is an email of its own: one summary a week, plus an immediate email only when changes fail to write to your CRM. |
| `duplicate_spike_threshold` | The fewest new groups of possible duplicates in a week for the weekly summary to highlight them, up to 100,000. 0 means the default, 25. |
| `primary_rules` | The [Record to keep](https://docs.clustr-ai.com/crm-cleaning/queue-and-findings.md#which-record-is-kept) rules in order, up to 10. Each `kind` is `has_owner`, `lifecycle_stage_rank`, `oldest_created`, `newest_updated`, `most_complete` or `property_equals` (with `property` and `value`). For example `[{ "kind": "has_owner" }, { "kind": "property_equals", "property": "lead_status", "value": "Qualified" }]`. Replaces the list; an empty list goes back to the default. |
| `match_rules` | [Your own match rules](https://docs.clustr-ai.com/crm-cleaning/queue-and-findings.md#your-own-match-rules), such as `{ "contact": [{ "fields": ["first_name", "last_name", "company"] }] }`. Up to 5 rules per object type. Contact fields: `first_name`, `last_name`, `email`, `phone`, `mobile_phone`, `job_title`, `company`, `linkedin_url`, `city`, `state`, `postal_code`, `country`. Company fields: `name`, `domain`, `phone`, `industry`, `linkedin_url`, `city`, `state`, `postal_code`, `country`. Each object type you pass replaces its rules; an empty list removes them. |

The tool does not edit exclusions, enrichment fields or the rest of survivorship. Use
the [API](https://docs.clustr-ai.com/crm-cleaning/api.md#replace-settings) for those.

### Progress

| Tool | Parameters | What it does | API |
| - | - | - | - |
| `get_crm_completeness` | `weeks` (1 to 52, default 12) | Field completeness, with the weekly trend. This is what the Overview shows. | `GET /api/crm/cleaning/completeness` |
| `get_crm_cleaning_summary` | `days` (1 to 90, default 7) | What cleaning did over the last few days, with the time it saved | `GET /api/crm/cleaning/summary` |
| `get_crm_property_insights` | `object_type` (`contact`, `company` or `deal`), `issue` (`flagged` by default, `empty`, `rarely_used` or `all`), `limit` (default 100, at most 500) | Every property with how many records fill it and how many have no value, the custom ones with no data or rarely filled, how filled each object's properties are, and the change since the last count. While a count runs, how far it is and the time left. HubSpot only. | `GET /api/crm/cleaning/property-insights` |
| `refresh_crm_property_insights` | none | Recount the [property insights](https://docs.clustr-ai.com/crm-cleaning/property-insights.md) now, once an hour. Counting starts within a minute and runs in the background at one search a second; the monthly count runs at night on its own. Nothing is written to your CRM. | `POST /api/crm/cleaning/property-insights/refresh` |
| `list_crm_field_values` | `object_type` (`contact` or `company`), `field`, `all` (default false), `limit` (default 50, at most 500) | The [spellings of one field's values](https://docs.clustr-ai.com/crm-cleaning/standardise-values.md), grouped, with the saved mappings. A spelling marked `suggested` is only close to the others: confirm it before mapping it. On a HubSpot dropdown, option values carry their `label` and `options` lists the choices; the mapping keeps the option value. A mapping the latest full scan did not apply carries `skipped` with the record count and the reason. Without `field`, the fields you can standardise. Only groups with more than one spelling unless `all` is true. | `GET /api/crm/cleaning/values` |
| `set_crm_value_mapping` | `object_type`, `field`, `from` (the spellings to replace), `to` (the value to keep) | Save a mapping; the one with the same `to` is replaced. The Standardise values rule applies it, asking you first by default. Confirm with the user first. | `POST /api/crm/cleaning/values/mappings` |
| `delete_crm_value_mapping` | `object_type`, `field`, `to` | Delete the mapping to `to`. Applied rewrites are not undone. | `DELETE /api/crm/cleaning/values/mappings` |
| `get_crm_health_score` | `trend` (default 30) | The older health grade of the last scan, by category, with its trend. The Overview shows completeness instead. | `GET /api/crm/cleaning/health` |

The [API page](https://docs.clustr-ai.com/crm-cleaning/api.md) describes each call's answers and errors.

## Example prompts

### "Clean my CRM phone numbers, but ask me first"

1. `get_crm_cleaning_settings` to read the current mode of `format_normalize`.
2. `update_crm_cleaning_settings` with `rule_modes: { format_normalize: "review" }`
   (Ask me).
3. `start_crm_cleaning_scan` to find the phone numbers to fix, after you confirm.
4. `get_crm_cleaning_run` until the scan is done.
5. `list_crm_cleaning_changes` with `action: format_normalize` and `property: phone` to
   show you a few before and after values.
6. `apply_crm_cleaning_group` with `action: format_normalize`, `object_type: contact`
   and `property: phone` once you say yes.

The formatting rule covers every format fix, not only phones, so emails, websites,
names, countries and states wait in the queue too. Apply those groups whenever you are ready.

### "What is waiting for me, and apply the safe ones"

1. `get_crm_cleaning_queue` to list the groups and counts.
2. The assistant summarises them and proposes the groups in the `auto` bucket.
3. `apply_crm_cleaning_group` with `bucket: auto` for each group you approve.
4. `dismiss_crm_cleaning_group` with `suppress: false` for the ones you want to clear
   for now.

### "Merge my duplicate companies"

1. `get_crm_cleaning_capabilities` to check your CRM can merge (HubSpot only).
2. `get_crm_cleaning_queue` for the merges waiting in the queue, then
   `apply_crm_cleaning_group` with `action: merge_companies` and `object_type: company`
   to apply the certain ones.
3. `list_crm_cleaning_changes` with `action: merge_companies` to show you the Likely
   pairs side by side, and `accept_crm_cleaning_change` for each pair you approve.
4. `list_crm_cleaning_findings` with `kind: duplicate_companies` for groups that are
   only reported, and `merge_crm_duplicates` with a finding's id for each one you
   approve.
5. `list_crm_cleaning_history` later, to show the merges that were applied.

### "Fill missing data, and tell me what it will cost"

1. `get_crm_enrichment_budget` to show the cap and what is left this month.
2. `get_crm_completeness` to show which fields are most often empty.
3. `update_crm_cleaning_settings` with `enrichment_enabled: true`, after you confirm.
4. `start_crm_enrichment` to run the enrichment pass.
5. `get_crm_cleaning_summary` after the next scan, to report the fields filled. The fills land on the scan after the enrichment pass.

### "Undo every phone format change from last Tuesday's scan"

1. `list_crm_cleaning_runs` to find last Tuesday's scan and its id.
2. The assistant tells you which rule and run it will revert, and asks you to confirm.
3. `revert_crm_cleaning_batch` with `action: format_normalize`, `property: phone` and
   that `run_id`.
4. While the answer says `has_more: true`, the same call again with `cursor` set to
   `next_cursor`.
5. The assistant adds up `reverted`, and reports the changes it left: expired ones,
   and conflicts where someone had edited the phone in your CRM since.

### "Can any of my rules run on their own?"

1. `get_crm_cleaning_suggestions` to list the rules your team always accepts.
2. The assistant shows each suggestion and asks which ones to switch.
3. `update_crm_cleaning_settings` with `rule_modes: { format_normalize: "auto" }` for
   each rule you approve.

### "Undo what cleaning did to Northwind yesterday"

1. `list_crm_cleaning_history` with `state: applied` and `q: Northwind`.
2. The assistant lists the changes and which ones can still be reverted.
3. `revert_crm_cleaning_change` for each one you pick.


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