Create a saved Insights (Spotlight) account-journey segment: a reusable filter over the account's engaged companies, and the input of create_audience_from_segment (and of get_insights_report).
WHEN: the audience or list is defined by BEHAVIOUR or CRM STATE rather than by firmographics alone: "accounts that visited /pricing", "high engagement score and not in the CRM", "accounts we already served more than 200 LinkedIn impressions" (a saturation exclusion for a sequenced program), "open opportunities that went cold". Plain firmographic / technographic / intent asks do NOT need a segment: use those audience tools directly.
WORKFLOW:
1. search_insights_criteria_fields (omit keywords for the full catalog) for exact field names, types, operators and picklist options.
2. list_segments: reuse a segment that already expresses the ask. This tool refuses a duplicate name.
3. create_segment with a descriptive name and the criteria below. Pass lookback_window to get `accounts` counted inside the window the audience will use.
4. create_audience_from_segment(segment_id, name, lookback_window, audience_type).
REQUIRES an active Insights (Spotlight) subscription on the account: the platform gates segment creation on it, and this tool checks it before writing. A refusal naming the subscription state (expired, trial expired, no plan) is final: tell the user the subscription must be renewed, and do not retry with other criteria. Reading existing segments and building audiences from them keep working.
CRITERIA SHAPE: a group {"operator": "AND"|"OR", "match": [criterion | nested group]}, up to three nested levels. Each criterion: {"field": <NAME>, "operator": <one of the field's operators>, "type": <the field's type>, "value": ...}. Before the call every criterion is checked against the live catalog: a missing `type` is filled in, names and operators are case-normalised, and an unknown field, an operator the field does not accept, or a picklist value that is not one of its options is refused with the valid choices (nothing is created).
VALUES BY TYPE:
- NUMERIC: a number; operators EQUALS, GREATER_THAN, GREATER_OR_EQUAL, LESS_THAN, LESS_OR_EQUAL. Metrics (LINKEDIN_IMPRESSIONS, LINKEDIN_ADS_ENGAGEMENT, WEBSITE_VISITS, TOTAL_PAGE_VIEWS, FORM_SUBMISSIONS, ...) are summed over the lookback window the audience is created with, so "more than 200 impressions in the last 90 days" is {"field": "LINKEDIN_IMPRESSIONS", "operator": "GREATER_THAN", "type": "NUMERIC", "value": 200} plus lookback_window 90 on the audience.
- MULTIPICKLIST: a list of options; plain strings are accepted and matched to the catalog options by name or label; operators IN, NOT_IN.
- BOOLEAN: true or false, operator null (or omitted).
- STRING: text; EQUALS, NOT_EQUAL, LIKE (contains), NOT_LIKE. PAGE_URL LIKE "/pricing" is the page-visit filter.
- ARRAY (UTM_* and REFERRER): a list of strings; IN, NOT_IN, LIKE, NOT_LIKE.
- DATE (CRM date fields): {"days": N} with IN_THE_LAST / NOT_IN_THE_LAST / IN_THE_NEXT, or {"startDate", "endDate"} (ISO) with BETWEEN.
- CRM (dynamic) fields: {"field": "DYNAMIC", "entity": <from the catalog>, "property": <field name>, "operator", "type", "value"}.
EXAMPLE, saturation exclusion for a sequenced LinkedIn program:
{"name": "Saturated: 200+ LinkedIn impressions", "lookback_window": 90, "criteria": {"operator": "AND", "match": [{"field": "LINKEDIN_IMPRESSIONS", "operator": "GREATER_THAN", "type": "NUMERIC", "value": 200}]}}
EXAMPLE, warm accounts not yet in the CRM:
{"operator": "AND", "match": [{"field": "SCORE", "operator": "IN", "type": "MULTIPICKLIST", "value": ["High"]}, {"field": "IN_CRM", "operator": null, "type": "BOOLEAN", "value": false}]}
RETURNS: {success, id, name, status (READY | PENDING | FAILED), last_updated_date, lookback_window, accounts, criteria (as stored), notes}. PENDING means a CRM field is still being extracted: wait and re-check with get_segment_criteria before building an audience. `accounts` of 0 means an audience would be empty: loosen the criteria or widen the window.
