Skip to main content
Glama

Metadata MCP Connector

by io.metadata.mcp-server
OverviewDiscussionsAdmin

Create or Update LinkedIn Message Ad

create_update_linkedin_message_ad
Destructive

Create a new or update an existing LinkedIn Message Ad on the Metadata platform.

            A LinkedIn Message Ad is a Sponsored Messaging asset: a one-shot direct
            message delivered to a member's LinkedIn inbox from a specific sender,
            with a subject line, a body, an optional banner image, and a single
            call-to-action button. It is NOT a Conversation Ad — there is no
            branching step graph. Use create_update_convo_ad for multi-step convos.

            IMPORTANT: This tool is ONLY for LinkedIn Sponsored Messaging
            (channelType=LINKEDIN, adType=MESSAGE). For IMAGE/GIF ads use
            create_update_image_ad; for VIDEO ads use create_update_video_ad; for CONVO
            use create_update_convo_ad; for Google Ads text ads use
            create_update_google_ads_ad; for DOCUMENT ads use
            create_update_document_ad. SPOTLIGHT / FOLLOWER are not yet
            covered by the dedicated tools; LinkedIn CTV (Connected TV) ads use
            create_update_ctv_ad.

            BEHAVIOR:
            - If `id` is NOT provided → creates a new Message Ad.
            - If `id` IS provided → updates the existing Message Ad with that ID.

            PREREQUISITES (MUST DO BEFORE CALLING):
            1. Call get_linkedin_senders to fetch a valid (senderId, senderName) pair.
               Message Ads share LinkedIn's sponsored-messaging sender allow-list
               with Conversation Ads — both pull from the same endpoint. Do NOT
               invent sender IDs.
            2. If using a banner image: upload it via upload_image_creative and
               pass the returned imageLibraryId as `bannerCreativeLibraryId`. The
               banner is OPTIONAL — omit the field to skip it. LinkedIn requires
               an IMAGE creative ≤ 2 MB; oversize banners are rejected upstream.

            CHARACTER LIMITS (enforced by the platform; mirror the UI validator at
            metadata-ui-v3/.../li/message/edit/validation.ts):
            - name           ≤ 50   chars  (ad name in the library)
            - headlineText   ≤ 60   chars  (the message subject line)
            - messageText    ≤ 2000 chars  (the message body)
            - actionText     ≤ 20   chars  (the CTA button label)

            PERSONALIZATION MACROS IN messageText:
            The body supports LinkedIn personalization macros. Pass them verbatim
            inside `%...%` — the platform substitutes at send time. The validator
            accepts ONLY these five macros (any other %...% token is rejected):
              %FIRSTNAME%
              %LASTNAME%
              %COMPANYNAME%
              %JOBTITLE%
              %INDUSTRY%
            Do not use `{firstName}` or any other syntax — only `%MACRO%`.

            USAGE INSTRUCTIONS FOR LLM:
            Use this tool when users want to:
            - Create a new LinkedIn Sponsored Message ad
            - Update an existing Message Ad (subject, body, CTA, sender, or banner)

            WHEN TO USE:
            - User asks "create a LinkedIn Message Ad" / "InMail ad" /
              "Sponsored Messaging ad"
            - User wants a one-shot LinkedIn DM with subject + body + CTA
            - User wants to update an existing Message Ad

            WHEN NOT TO USE:
            - User wants a branching conversation flow → use create_update_convo_ad
            - User wants a feed image / GIF ad → use create_update_image_ad
            - User wants a feed video ad → use create_update_video_ad
            - User wants a Google Ads text ad → use create_update_google_ads_ad

            INPUT PARAMETERS:
            - id (optional): Existing Message Ad ID. Provide to UPDATE; omit to
              CREATE.
            - name (required, ≤ 50): Ad name in the library.
            - senderId (required): LinkedIn sender ID from get_linkedin_senders.
            - senderName (required): Display name matching senderId.
            - headlineText (required, ≤ 60): Subject line shown in the inbox.
            - messageText (required, ≤ 2000): Message body. Supports the five
              %MACRO% tokens listed above.
            - actionText (required, ≤ 20): CTA button label.
            - bannerCreativeLibraryId (optional): imageLibraryId of the banner
              image. Upload first via upload_image_creative. Omit to skip the
              banner.
            - completionStatus (optional, default DRAFT): "DRAFT" or "COMPLETED".
              Use COMPLETED only when every required field is final.

            EXAMPLE USAGE (Create):
            create_update_linkedin_message_ad(
                name="Q1_Demo_Outreach_LI_Message",
                senderId="fQdRPtecbv",
                senderName="Josh Desmarais",
                headlineText="Quick question about your marketing stack",
                messageText="Hi %FIRSTNAME%, as a %JOBTITLE% at %COMPANYNAME% you know how hard pipeline attribution is. Want a 15-min walkthrough?",
                actionText="Book a demo",
                bannerCreativeLibraryId=482931,
            )

            EXAMPLE USAGE (Update):
            create_update_linkedin_message_ad(
                id=29144,
                name="Q1_Demo_Outreach_LI_Message_v2",
                senderId="fQdRPtecbv",
                senderName="Josh Desmarais",
                headlineText="Following up — quick demo?",
                messageText="Hi %FIRSTNAME%, circling back…",
                actionText="Book a demo",
            )

            SUCCESS RESPONSE (mirrors create_update_convo_ad):
            {
                "success": true,
                "id": 29144,
                "ad_url": "https://platform.metadata.io/hub/library/ads?adId=29144",
                "name": "Q1_Demo_Outreach_LI_Message",
                "channelType": "LINKEDIN",
                "adType": "MESSAGE",
                "completionStatus": "DRAFT",
                "request": { "message": { ... } }
            }

            COMMON MISTAKES:
            - Inventing a senderId — IDs MUST come from get_linkedin_senders.
            - Passing a banner URL instead of an imageLibraryId — upload first.
            - Using `{firstName}`-style macros — LinkedIn uses `%FIRSTNAME%`.
            - Using an unsupported macro (anything outside the five listed) —
               the platform/UI validator rejects it.
            - Using this tool for a multi-step flow — use create_update_convo_ad.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoExisting Message Ad ID — include to UPDATE; omit to CREATE.
nameYesAd name in the platform library (max 50 characters).
senderIdYesLinkedIn sender ID. MUST come from get_linkedin_senders. Do not invent.
actionTextYesCall-to-action button label (max 20 characters).
senderNameYesDisplay name matching senderId, also from get_linkedin_senders.
messageTextYesMessage body (max 2000 characters). Supports LinkedIn personalization macros — ONLY %FIRSTNAME%, %LASTNAME%, %COMPANYNAME%, %JOBTITLE%, %INDUSTRY%. Any other %...% token is rejected by the platform validator.
headlineTextYesMessage subject line shown in the recipient's inbox (max 60 characters).
completionStatusNoDefaults to DRAFT. Use COMPLETED only when every required field is final.
bannerCreativeLibraryIdNoOptional: imageLibraryId of the banner image shown above the message. Upload the image first via upload_image_creative and pass the returned ID. Omit to skip the banner.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.8/5.0
Behavior5/5

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

Annotations declare readOnlyHint=false, destructiveHint=true, and openWorldHint=true, and the description both confirms and enriches this: it specifies id-based dispatch ('If id is NOT provided → creates; If id IS provided → updates'), mandates calling get_linkedin_senders first with a warning against inventing sender IDs, details the upload_image_creative → bannerCreativeLibraryId flow, and discloses platform-enforced character limits mirroring a UI validator file path. The destructive update semantics are consistent with destructiveHint=true, and the description adds far more behavioral context than annotations alone provide.

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 rigorously organized with scannable section headers (BEHAVIOR, PREREQUISITES, CHARACTER LIMITS, WHEN TO USE/NOT, COMMON MISTAKES) and is front-loaded with purpose. Nearly every section carries operational value — the two worked examples (create and update) and the COMMON MISTAKES list earn their space. It loses a point because the INPUT PARAMETERS section largely duplicates the 100%-covered schema descriptions rather than only adding the workflow context that the schema lacks.

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?

Despite having no output schema, the description provides a SUCCESS RESPONSE block with concrete fields (success, id, ad_url, channelType, adType, completionStatus). Given the tool's real complexity — dual create/update behavior, two external prerequisites (sender fetch and banner upload), five macro constraints, four character limits, and 9 parameters — the description covers everything needed for correct invocation: both invocation paths are exemplified, failure modes are anticipated in COMMON MISTAKES, and sibling routing is complete. Nothing an agent needs is missing.

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

Parameters4/5

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

Schema coverage is 100%, setting a baseline of 3. The description adds genuine meaning beyond the schema: it explains that senderId/senderName must be a valid pair fetched from get_linkedin_senders (with the shared allow-list note for Conversation Ads), it gives the upload-then-pass workflow for bannerCreativeLibraryId, it ties character limits to a specific validator, and it explains the create vs update dispatch of id. The macro whitelist in messageText is also reinforced with the anti-pattern {firstName}. Slight redundancy with schema text prevents a 5.

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?

The opening sentence states a specific verb-resource pair ('Create a new or update an existing LinkedIn Message Ad on the Metadata platform') and defines the asset precisely as a one-shot Sponsored Messaging direct message with subject, body, optional banner, and single CTA. It explicitly differentiates from Conversation Ads ('no branching step graph') and later names each sibling (create_update_convo_ad, create_update_image_ad, create_update_video_ad, create_update_google_ads_ad) so an agent can disambiguate without opening their schemas.

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 contains dedicated WHEN TO USE and WHEN NOT TO USE sections with concrete user-intent triggers ('User asks create a LinkedIn Message Ad / InMail ad / Sponsored Messaging ad') and explicit exclusions for branching flows, feed image/GIF, video, Google Ads text, DOCUMENT, SPOTLIGHT/FOLLOWER, and CTV ads with the correct sibling tool named for each. This is as explicit as usage guidance gets.

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

All Metadata MCP Connector toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources