estimate_target_group

Estimate audience size for target group criteria before creating. Supports BOTH include AND exclude rules (criteria + audiences).

USE FOR: Validate audience size before creating, "how many people will this reach?", "preview audience size", test targeting combinations, preview impact of exclusion criteria/audiences.

CHANNELS: LINKEDIN (default) and REDDIT. Pass channel="REDDIT" to size a Reddit target group before create_reddit_target_group; its criteria ids come from search_reddit_criteria rather than search_target_group_criteria, and the rest of the call is identical (PRD-31759).

PREREQUISITE: All criteria IDs MUST come from search_target_group_criteria first (search_reddit_criteria for REDDIT).

**CRITICAL FOR LINKEDIN**: LOCATION must be FIRST criteria in include array with isModifiable=false.

TARGETING STRUCTURE (full example with include + exclude criteria + exclude audiences):
{
  "include": [
    {
      "isModifiable": false,
      "criteria": [{"type": "NATIVE_LOCATION", "data": [{"externalId": "urn:li:geo:103644278", "name": "United States"}]}],
      "audiences": []
    },
    {
      "isModifiable": true,
      "criteria": [{"type": "AGE", "data": [{"externalId": "urn:li:ageRange:(25,34)", "name": "25 to 34"}]}],
      "audiences": []
    }
  ],
  "exclude": {
    "isModifiable": true,
    "criteria": [
      {"type": "COMPANY_NAME", "data": [{"externalId": "urn:li:organization:1090", "name": "Philips"}]}
    ],
    "audiences": [
      {
        "mdAudienceId": 45316,
        "name": "ICP Pharma LifeSci Leaders",
        "type": "FIRMOGRAPHIC_EXCLUDE",
        "matchCount": 213127,
        "matchCountType": "FIXED_SIZE",
        "inactive": false,
        "criteria": [{"type": "NATIVE_LOCATION", "data": [{"externalId": "urn:li:geo:103644278", "name": "United States"}]}]
      }
    ]
  }
}

INCLUDE: Array of rule blocks. Each block = AND-group of criteria; multiple blocks are AND'd together.
EXCLUDE: Single object (NOT array) with `criteria` and `audiences`. Anyone matching exclude is removed from results.

⚠️ AUDIENCES ≠ TARGET GROUPS. Both `include[].audiences` and `exclude.audiences` accept Custom Audience records ONLY (the entities returned by `get_matched_audiences`). Target Groups (the entities returned by `list_target_groups` / `retrieve_target_group_by_id`) are a separate entity in a separate ID space and CANNOT be attached here; the platform silently drops or rejects them. If the user names "X" and only `list_target_groups` matches it (not `get_matched_audiences`), do NOT pass the Target Group's id as `mdAudienceId`. Stop, tell the user "X is a Target Group, not a Custom Audience", and offer to rebuild X as a Custom Audience (e.g. via `create_audiences` with the same criteria) before retrying.

INCLUDE AUDIENCES: `include[].audiences` accepts ANY Metadata audience type — there is NO allow-list and NO restriction to specific types. Pass any audience returned by the audience listing tools (e.g. FIRMOGRAPHIC_INCLUDE, FIRMOGRAPHIC_INCLUDE_SFDC, NATIVE_LINKEDIN, NATIVE_FACEBOOK, RETARGETING, TECHNOGRAPHIC, SFDC_ACCOUNT_DYNAMIC, MA_CONTACTS_DYNAMIC, CONTACT_LIST, and any other type, including types not enumerated in any tool schema). Type-name enums seen in `create_audiences` / `search_audiences` describe how audiences are CLASSIFIED, not which can be attached here. Caveat: estimates may under-report (or return zero) when combining server-resolved audiences (e.g. SFDC dynamic, retargeting) with native LinkedIn criteria — that is an estimate-side reconciliation issue, not a creation constraint, so a zero estimate does not necessarily mean the platform will reject the create call.

EXCLUDE AUDIENCES: To exclude an existing Metadata Custom Audience, provide its full object in `exclude.audiences`. The tool pre-flight-rejects placeholder values — never invent ids or types when you don't know them, call `get_matched_audiences` (or `search_audiences`) first and use the real values from the response:
- `mdAudienceId` (integer, REQUIRED): The numeric Custom Audience ID from `get_matched_audiences` (e.g. 49067, 45316). NEVER the audience name string, NEVER a placeholder like 1/2/3/4 (real Custom Audience IDs are 5-digit numbers; the tool rejects anything under 100), and NEVER a Target Group id (those come from `list_target_groups`; see the AUDIENCES ≠ TARGET GROUPS note above).
- `name` (string, required): Audience name.
- `type` (string, required): Audience type, e.g. `FIRMOGRAPHIC_EXCLUDE`, `RETARGETING_EXCLUDE`, `CONTACT_LIST_EXCLUDE` (must be the EXCLUDE variant). NEVER the placeholder string "AUDIENCE" — the tool rejects that pre-flight.
- `matchCount` (int), `matchCountType` ("FIXED_SIZE"), `inactive` (bool): metadata fields from the audience record. The tool pre-flight-rejects entries with `inactive: true` (an audience still matching after creation cannot be attached yet — attach it once it is active).
- `criteria`: The audience's own criteria array (copy from the audience's definition).

CRITERIA TYPES (all IDs from search_target_group_criteria), valid in BOTH include and exclude:
- NATIVE_LOCATION / LOCATION: location data — MANDATORY FIRST in include. Multi-country geo goes in ONE location criterion with one {externalId, name} entry per country (e.g. "Canada and USA" = 2 entries in the same data array). Never silently drop a country the user named.
- AGE, COMPANY_CATEGORY, COMPANY_GROWTH_RATE, INDUSTRY, COMPANY_NAME, REVENUE, EMPLOYEE: Array of {externalId, name}
- JOB_FUNCTION, JOB_TITLE, MEMBER_GROUP, MEMBER_INTEREST, MEMBER_SKILL, MEMBER_BEHAVIOR, SENIORITY, FOLLOWED_COMPANIES: Array of {externalId, name}
- YEARS_OF_EXPERIENCE_RANGE: {"min": 4, "max": 5}

RESPONSE: {matchCount, isMatchCountTooSmall, matchCountType, allowZeroMatchCount}

WORKFLOW: search_target_group_criteria → build targeting (include + optional exclude) → estimate_target_group → adjust → create_target_group