# Search filter values

> search_filter_values: Searches the values of one field by text, such as towns matching leeds, and returns each code with its contact and company counts plus did_you_mean for near misses.

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

Searches the values of one field by text, such as towns matching leeds, and returns each code with its contact and company counts plus did_you_mean for near misses. Use the returned code in a filter rather than guessing one. Free and needs no account; results are paged with next_cursor. Call count_audience once the filters are chosen. 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 | `search_filter_values` |
| Position in tools/list | 4 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/{dimension}/values`](https://emailmovers.com/mydatahub/docs/reference/rest/search-filter-values.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 |
| --- | --- | --- | --- |
| `dimension` | string | yes | A field name from list_filters, such as site.town or company.sic_2007. |
| `q` | string | no | Text to search for. |
| `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. |
| `limit` | integer (1 to 100) | no | Items per page, 1 to 100. Default 25. Default `25`. |
| `cursor` | string | no | An opaque cursor from next_cursor. Pass it back unchanged. |

## Example call

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

```json
{
  "name": "search_filter_values",
  "arguments": {
    "dimension": "site.town"
  }
}
```

## Output

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

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `field` | string | yes |  |
| `dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `data` | array of `FilterValue` | yes |  |
| `data[].code` | string or number or boolean | yes | The value to use in a filter. |
| `data[].label` | string | yes |  |
| `data[].contacts` | integer (0 or more) or `under 10` or `suppressed` | yes | A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5. |
| `data[].companies` | integer (0 or more) or `under 10` or `suppressed` | yes | A whole number; "under 10" when disclosure control withholds a small cell; or "suppressed" when secondary suppression hides a cell of 10 or more in a cross-tab or breakdown, so totals cannot be differenced. Anonymous and trial callers see cells rounded to the nearest 5. |
| `data[].parent` | string or null | no | The parent code for hierarchical fields, such as SIC division 62 under J. |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |
| `did_you_mean` | array of string | no |  |
| `disclosure` | `Disclosure` | yes | Whether these numbers are exact or protected: "under 10" cells, rounding to 5 and secondary suppression for anonymous and trial callers. |
| `disclosure.level` | enum: `exact`, `rounded` | yes | exact for authenticated paid callers; rounded for anonymous and trial callers, whose counts under 100 and every cell are rounded to the nearest 5. |
| `disclosure.rounded_to` | integer or null | yes | 5 when numbers are rounded; null when they are exact. |
| `disclosure.secondary_suppression` | boolean | yes | True when cross-tab or breakdown cells of 10 or more were hidden as "suppressed" so totals cannot be differenced. |
| `disclosure.notes` | array of string | yes |  |

## 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).