# Expand job titles

> expand_job_titles: Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to.

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

Expands title keywords into every matching title (plurals, department synonyms, ampersands, abbreviations such as CEO), each with a count, or shows what a bundle such as sdm resolves to. Use it before counting so the user can see and edit which titles a keyword covers; nothing is expanded silently. Free and needs no account. Put the returned filter into the audience, then call count_audience. 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 | `expand_job_titles` |
| Position in tools/list | 5 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 | [`POST /v1/job-titles/expand`](https://emailmovers.com/mydatahub/docs/reference/rest/expand-job-titles.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 |
| --- | --- | --- | --- |
| `terms` | array of string | no | Title keywords to expand, such as marketing manager. |
| `bundle` | enum: `sdm`, `manager_and_above`, `owner_managed` | no | A title bundle to show: sdm, manager_and_above or owner_managed. |
| `mode` | enum: `contains`, `starts_with`, `exact` | no | contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion. |
| `expand` | array of enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations` | no | Expansion sets to apply, each once. Left out, the four default sets apply. |
| `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": "expand_job_titles",
  "arguments": {
    "terms": ["marketing manager"],
    "mode": "contains"
  }
}
```

## 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_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `mode` | enum: `contains`, `starts_with`, `exact` | yes | contains (the default) matches titles containing a term, starts_with matches titles beginning with it, exact takes verbatim titles with no expansion. |
| `expand` | array of enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations` | yes |  |
| `terms` | array of `ExpandedTerm` | yes |  |
| `terms[].term` | string | yes | A matched title. |
| `terms[].from_term` | string | yes | The input term it came from. |
| `terms[].expansion_set` | enum: `plural_singular`, `department_synonyms`, `ampersand_and`, `abbreviations`, `permutations` or `input` | yes | The expansion set that produced it, or input for the term itself. |
| `terms[].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. |
| `terms[].excluded` | boolean | no | True when exclude_terms removed it from the audience. |
| `total_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. |
| `bundle` | object or null | yes |  |
| `bundle.id` | enum: `sdm`, `manager_and_above`, `owner_managed` | yes |  |
| `bundle.label` | string | yes |  |
| `bundle.status` | enum: `confirmed`, `proposed`, `to_confirm` | yes |  |
| `bundle.resolves_to` | `WhereNode` | yes | A group (all, any, not), a title bundle or a filter. Groups nest up to 32 deep, and a where tree holds up to 1,000 filters, groups and bundles. |
| `filter` | `Filter` or null | yes | A ready matches filter for the terms, or null for a bundle. |
| `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).