Skip to main content
Glama

Metadata MCP Connector

Create LinkedIn Engagement Retargeting Audience

create_linkedin_engagement_retargeting_audience

Create a LinkedIn Engagement Retargeting audience: people who already engaged with the advertiser's LinkedIn ads, company page, or website. STEP 3 of the flow.

            This is NOT create_retargeting_audience, which imports an audience the ad account
            already has. This builds a NEW LinkedIn DMP segment from the engagement rule defined
            here. Once built it is a normal Metadata audience and can be attached to campaigns.

            **REQUIRED WORKFLOW — do not call this tool first:**
            1. get_linkedin_engagement_source_types → choose `source_platform` + `engagement_trigger`
            2. For every source type EXCEPT WEBSITE: search_linkedin_engagement_sources with that
               trigger and lookback → collect each chosen result's `id` into
               `engagement_source_urns`
            3. Call this tool
            Source types, triggers and URNs are LinkedIn's own values, and only steps 1 and 2
            can supply them. Do not invent, guess or reuse one from another account: a value
            that did not come from those steps either fails outright or, worse, is accepted and
            builds an audience that never populates.

            **TWO SHAPES, MUTUALLY EXCLUSIVE — mixing them is rejected:**

            A) NON-WEBSITE (VIDEO_ADS, SINGLE_IMAGE_ADS, DOCUMENT_ADS, CONVERSATION_ADS,
               LEAD_GEN_FORMS, ORGANIZATION_PAGES):
               pass `engagement_source_urns`. Do NOT pass page_set_name or url_match_groups.

            B) WEBSITE:
               pass `page_set_name` and `url_match_groups`. Do NOT pass engagement_source_urns.
               Metadata creates the LinkedIn page set from those URL rules for you.

            URL MATCH RULES (WEBSITE only) are a LIST OF GROUPS. Rules inside a group are ANDed;
            the groups are ORed. Each rule is {matchType, matchValue}, matchType being EXACT
            ("URL equals"), STARTS_WITH, or CONTAINS.
              [[A, B], [C]]  means  (A AND B) OR C
            Worked example — "anyone who hit pricing or any demo page":
              [[{"matchType": "STARTS_WITH", "matchValue": "https://example.com/pricing"}],
               [{"matchType": "CONTAINS",    "matchValue": "/demo"}]]
            Use one rule per group for a simple OR list, which is what most requests mean. Reach
            for a multi-rule group only for a genuine AND, e.g. a path that also carries a
            campaign parameter.

            WHEN TO USE:
            - "Retarget everyone who watched our video ads in the last 90 days"
            - "Build an audience from people who submitted the lead form"
            - "Create an audience of visitors to our pricing and demo pages"
            - "Retarget people who visited our LinkedIn company page"
            - "Make a warm audience from last quarter's ad engagement"

            PARAMETERS:
            - name: audience name (required). Give it something descriptive of the rule, e.g.
              "Video 50% viewers 90d", so it is recognisable in the audience list later.
            - source_platform: the chosen `engagementSourceType` (required)
            - engagement_trigger: a trigger listed for THAT source type (required). NOTHING
              VALIDATES THE PAIRING — see the warning below.
            - lookback_window_days: 30, 60, 90, 180 or 365 — WEBSITE caps at 180 (required)
            - engagement_source_urns: LinkedIn URNs from search_linkedin_engagement_sources,
              copied verbatim. Required for every source type except WEBSITE. Several are
              normal: the audience is everyone who engaged with ANY of them.
            - page_set_name: internal label for the URL rule set (WEBSITE only, required there).
              Only ever seen inside LinkedIn, so a plain descriptive label is fine.
            - url_match_groups: the OR-of-ANDs URL expression (WEBSITE only, required there)

            RETURNS:
            Confirmation with the new audience `id` and name, the `criteria` that define it
            (source, trigger, lookback, how many sources), the channel, and a `note` on when it
            becomes usable.

            **WHAT TO TELL THE USER AFTER IT SUCCEEDS:**
            It is created but not yet populated. LinkedIn takes up to 48 hours to build the
            audience and a further 24 hours before it delivers, so it will show NO match count
            and NO contact or company numbers immediately. That is expected and correct, not a
            failure. Say so plainly rather than reporting the audience as empty or broken.

            IMPORTANT NOTES:
            - **THE TRIGGER MUST BELONG TO THE SOURCE TYPE, AND NOTHING CHECKS THAT FOR YOU.**
              A mismatched pair (e.g. VIDEO_ADS with LEAD_FORM_SUBMIT) is accepted by this tool,
              by the platform and by LinkedIn, with no error at any layer — it just builds an
              audience that can never populate, because the engagement it describes cannot
              happen. Verified on stage. Always take the trigger from the source type's own
              `triggers` list in step 1; never carry one over from another source type.
            - Requires a connected LinkedIn channel on the account.
            - **NEVER re-create the audience because it shows no members.** Zero right after
              creation is the normal state; creating it again just makes a duplicate.
            - This audience type NEVER reports contact or company counts the way a firmographic
              audience does. It lives on LinkedIn, so only LinkedIn's own match count applies.
            - WEBSITE additionally requires the LinkedIn Insight Tag installed and active on the
              pages the URL rules match. Without it the audience stays empty indefinitely, no
              matter how long you wait — mention this whenever you build a WEBSITE audience.
            - The lookback window doubles as the retention window: it sets both how far back
              engagement counts and how long someone stays in the audience.
            - Building from sources with no engagement produces an empty audience. If step 2
              showed zeros everywhere, raise that with the user instead of creating anyway.
            - The rule cannot be edited afterwards. A different trigger or lookback means a new
              audience, so confirm the choice before creating when the user was vague.

            COMMON ERRORS AND WHAT THEY MEAN:
            - "engagement_source_urns is required" — you skipped step 2, or passed a WEBSITE-style
              payload for a non-website source type.
            - "must be one of [30, 60, 90, 180]" — WEBSITE was given a 365-day lookback.
            - "page_set_name / url_match_groups is required" — WEBSITE needs the URL rules, not URNs.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
nameYesName for the new audience. Prefer something that describes the rule (e.g. 'Video 50% viewers 90d') so it is recognisable later.
page_set_nameNoWEBSITE only: internal label for the URL rule set created on LinkedIn (e.g. 'Pricing and demo pages'). Required when source_platform is WEBSITE.
source_platformYesThe `engagementSourceType` chosen from get_linkedin_engagement_source_types — e.g. VIDEO_ADS, SINGLE_IMAGE_ADS, DOCUMENT_ADS, CONVERSATION_ADS, LEAD_GEN_FORMS, ORGANIZATION_PAGES, or WEBSITE. WEBSITE switches this tool to the URL-rule shape.
url_match_groupsNoWEBSITE only: OR-of-ANDs URL expression. The outer list is ORed, rules inside a group are ANDed. For a plain 'any of these pages' list, use one rule per group. Required when source_platform is WEBSITE.
engagement_triggerYesAn `engagementTrigger` listed for THAT source type (e.g. FIRST_QUARTILE for VIDEO_ADS, LEAD_FORM_SUBMIT for LEAD_GEN_FORMS, VISIT for WEBSITE). A trigger from a DIFFERENT source type is accepted without error and silently builds an audience that never populates, so take it from this source type's own trigger list.
lookback_window_daysYesHow far back engagement counts, and how long a member is retained. WEBSITE accepts 30/60/90/180 only; every other source type also accepts 365.
engagement_source_urnsNoLinkedIn URNs to retarget, taken verbatim from the `id` of each chosen search_linkedin_engagement_sources result. Required for every source type EXCEPT WEBSITE, and must be omitted for WEBSITE. Multiple URNs union their audiences.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond annotations (readOnlyHint=false, destructiveHint=false), the description discloses numerous behavioral traits: 'It is created but not yet populated... up to 48 hours to build... 0 more 24 hours before it delivers', 'The rule cannot be edited afterwards', 'a mismatched pair is accepted without error at any layer', and 'WEBSITE additionally requires the LinkedIn Insight Tag'. It also discloses that the audience never reports contact/company countscedented and that lookback acts as retention. This far exceeds what annotations alone communicate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with bolding, numbered steps, headers, and a common-errors section. Every major block earns its place (workflow, shapes, URL rules, user messaging). Some redundancy exists (the trigger-pairing warning appears in both the parameter notes and IMPORTANT NOTES, and the 'zero match count' point appears twice), but this reinforces rather than bloats. It is appropriately sized for a tool with this much pre-requisite nuance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for an agent to call this tool correctly: it states pre-requisite workflow, parameter constraints, return value shape (audience id, name, criteria, channel, note), expected post-creation behavior, and common errors with meanings. Since there is no output schema, the description carries the full burden for return semantics, and it does so explicitly. Nothing an agent needs to know to invoke and interpret the result is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description adds critical semantic content: the two mutually exclusive payload shapes (A: engagement_source_urns vs B: page_set_name + url_match_groups), the OR-of-ANDs interpretation of url_match_groups with a worked example, and the warning that triggers from a different source type are accepted silently. It also tells the agent to copy URNs 'verbatim' from search_linkedin_engagement_sources. These details are not in the schema's structured descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Create a **LinkedIn Engagement Retargeting** audience: people who already engaged with the advertiser's LinkedIn ads, company page, or website.' It then explicitly contrasts with create_retargeting_audience ('This is NOT create_retargeting_audience... This builds a NEW LinkedIn DMP segment'), which distinguishes it from its closest sibling. An agent can tell exactly what this tool does without reading any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit workflow prerequisites ('REQUIRED WORKFLOW — do not call this tool first' with three numbered steps), a explicit 'WHEN TO USE' list of natural-language example requests, and a direct exclusion ('This is NOT create_retargeting_audience...'). It also states when not to use it (e.g., never re-create because zero members is normal). This is textbook usage guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources