# Filter catalogue

> list_filters: Lists every filterable field of the audience definition (mydatahub.audience/1) with its group, type, operators, value count and default, plus the datasets.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/list_filters

Lists every filterable field of the audience definition (mydatahub.audience/1) with its group, type, operators, value count and default, plus the datasets. Use it first to learn field names such as company.employee_band or site.town before building an audience by hand. Free and needs no account; the same catalogue is the mydatahub://catalogue resource. Call search_filter_values to find the codes for one field. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

| Property | Value |
| --- | --- |
| Tool name | `list_filters` |
| Position in tools/list | 3 of 22 |
| Cost | Free |
| Scope | None. Works without an account. |
| Annotations | readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false |
| Kind | Read only; idempotent, not destructive, closed world |
| REST equivalent | [`GET /v1/catalogue/filters`](https://emailmovers.com/mydatahub/docs/reference/rest/list-filters.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## Input

The schema sets `additionalProperties` to false, so a member that is not listed is refused.

| Member | Type | Required | Description |
| --- | --- | --- | --- |
| `dataset` | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | no | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |

## Example call

The `params` of a `tools/call` request:

```json
{
  "name": "list_filters",
  "arguments": {}
}
```

## Output

The result carries `structuredContent` that matches this schema, and one line of text that leads with the number.

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `dataset` | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | yes | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |
| `dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `fields` | array of `FilterDimension` | yes |  |
| `fields[].field` | string | yes | The field name, also the dimension slug. |
| `fields[].group` | enum: `company`, `site`, `contact`, `email`, `phone`, `signal` | yes |  |
| `fields[].type` | enum: `enum`, `text`, `number`, `date`, `geo`, `hashed_list`, `boolean`, `band` | yes |  |
| `fields[].label` | string | yes |  |
| `fields[].description` | string | yes |  |
| `fields[].operators` | array of enum: `in`, `between`, `gte`, `lte`, `matches`, `within_radius`, `in_list`, `since` | yes |  |
| `fields[].facet` | boolean | yes | Usable in breakdown_by. |
| `fields[].value_count` | integer (0 or more) or null | yes | Distinct values in this dataset version; null for free text and numbers. |
| `fields[].default` | string or null | yes |  |
| `fields[].examples` | array of string or number or boolean | yes |  |
| `fields[].values_url` | string or null | yes | Where to search the values, or null when the field has none to list. |
| `operators` | array of `OperatorInfo` | yes |  |
| `operators[].op` | enum: `in`, `between`, `gte`, `lte`, `matches`, `within_radius`, `in_list`, `since`, and 3 more | yes |  |
| `operators[].applies_to` | string | yes |  |
| `operators[].description` | string | yes |  |
| `datasets` | array of `Dataset` | yes |  |
| `datasets[].id` | enum: `uk_contacts`, `ie_contacts`, `global_contacts` | yes | The dataset an audience draws from. uk_contacts is live; ie_contacts and global_contacts are listed but not yet served. |
| `datasets[].name` | string | yes |  |
| `datasets[].status` | enum: `live`, `planned`, `through_our_team` | yes | live is served; planned is not yet served; through_our_team is sold through the bespoke service only. |
| `datasets[].owner` | string | yes |  |
| `datasets[].source` | string | yes |  |
| `datasets[].licence` | string | yes |  |
| `datasets[].refresh` | string | yes |  |
| `datasets[].residency` | string | yes |  |
| `datasets[].regulator` | string | yes |  |
| `datasets[].warranty` | string | yes |  |
| `datasets[].credits_per_record` | number (0 or more) | yes | 1 for owned UK and Irish data. |
| `datasets[].credits_status` | enum: `confirmed`, `proposed` | yes |  |
| `datasets[].current_version` | string or null | yes |  |
| `datasets[].versions_available` | integer (0 or more) | yes | Immutable weekly versions still queryable (the last 52). |

## Errors

A failed call returns `isError` true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with `code`, `detail`, `next_step` and `did_you_mean`. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See [Errors](https://emailmovers.com/mydatahub/docs/errors.md).