Skip to main content
Glama

Metadata MCP Connector

by io.metadata.mcp-server
OverviewDiscussionsAdmin

Create or Update LinkedIn Conversation Ad

create_update_convo_ad
Destructive

Create or update a LinkedIn Conversation Ad ("convo ad") — a branching in-message chat where each step contains a message bubble and a list of button actions that drive the conversation forward.

            BEHAVIOR:
            - If `id` is provided → UPDATES the existing convo ad with that ID.
            - If `id` is omitted → CREATES a new convo ad.

            PREREQUISITES (MUST DO BEFORE CALLING):
            1. Call get_linkedin_senders to get a valid (senderId, senderName) pair.
               These are LinkedIn-issued IDs — do NOT invent them.
            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.

            THE STEP GRAPH:
            A convo is a directed graph of message "steps". Each step has:
            - `stepId` — unique integer; stepId=1 is ALWAYS the entry message.
            - `message` — the bubble text; HTML allowed (e.g.,
              '<p style="margin:0">Hi!</p>').
            - `actions` — the buttons under the bubble (1 to 5).

            ACTIONS — each action has a `type` from this enum:
            - NEXT_STEP   → click jumps to another step by `nextStepId`. Use this to
                            build branches ("Interested? YES / NO").
            - WEBSITE_URL → click opens an external URL given in `link`. Use this for
                            "learn more" / external resources.
            - MAIN_CTA    → click opens the offer attached at campaign launch (either
                            a lead-gen form OR a landing page, depending on the offer).
                            DO NOT set `link` or `nextStepId` on a MAIN_CTA — they
                            are resolved by the campaign builder later.

            WARNING: STRUCTURAL RULES (validated client-side before POST):
            1. Every action.type MUST be one of NEXT_STEP / WEBSITE_URL / MAIN_CTA.
            2. NEXT_STEP MUST have `nextStepId` pointing to an existing stepId, and
               cannot point at itself.
            3. WEBSITE_URL MUST have a non-empty `link`.
            4. MAIN_CTA needs neither `link` nor `nextStepId`.
            5. The flow MUST terminate — any step with NO NEXT_STEP action must
               include at least one MAIN_CTA or WEBSITE_URL so the user has an exit.
            6. `stepId=1` MUST exist — it is the entry point.
            7. stepIds must be unique.

            A single step CAN mix action types — e.g., step 1 can offer "Tell me
            more" (NEXT_STEP), "Visit site" (WEBSITE_URL), and "Book demo"
            (MAIN_CTA) all at once.

            INPUT PARAMETERS:
            - name (required, max 50 chars): Ad name in the platform library.
            - senderId (required): From get_linkedin_senders.
            - senderName (required): Matching display name from get_linkedin_senders.
            - headlineText (required): Subject line shown above the message thread.
            - bannerCreativeLibraryId (optional): imageLibraryId for the banner image
              above the chat. Omit to skip the banner.
            - completionStatus (optional, default "DRAFT"): "DRAFT" or "COMPLETED".
            - flowId (optional, default 7): LinkedIn convo flow version ID.
            - templateId (optional, default 1): LinkedIn convo template ID.
            - id (optional): For UPDATE only — existing ad ID.
            - steps (required, ≥1): The step graph (see schema).

            EXAMPLE — TWO-STEP BRANCH WITH MULTI-ACTION FIRST STEP:
            create_update_convo_ad(
                name="DemoConvo_Q4",
                senderId="fQdRPtecbv",
                senderName="Josh Desmarais",
                headlineText="Quick question about your marketing stack",
                completionStatus="DRAFT",
                steps=[
                    {
                        "stepId": 1,
                        "message": "<p style=\"margin:0\">Want a 15-min demo?</p>",
                        "actions": [
                            {"type": "NEXT_STEP", "text": "Tell me more", "nextStepId": 2},
                            {"type": "WEBSITE_URL", "text": "Visit site", "link": "https://metadata.io"},
                            {"type": "MAIN_CTA", "text": "Book demo"}
                        ]
                    },
                    {
                        "stepId": 2,
                        "message": "<p style=\"margin:0\">More info — ready to book?</p>",
                        "actions": [
                            {"type": "MAIN_CTA", "text": "Yes, book"}
                        ]
                    }
                ]
            )

            SUCCESS RESPONSE:
            {
                "success": true,
                "id": 21241,
                "ad_url": "https://platform.metadata.io/hub/library/ads?adId=21241",
                "name": "DemoConvo_Q4",
                "channelType": "LINKEDIN",
                "adType": "CONVO",
                "completionStatus": "DRAFT",
                "request": { "convo": { ... } }
            }

            COMMON MISTAKES:
            - Inventing a senderId — IDs MUST come from get_linkedin_senders.
            - Putting `link` on a MAIN_CTA — the offer link is set at campaign launch.
            - Putting `nextStepId` on a MAIN_CTA / WEBSITE_URL — only NEXT_STEP uses it.
            - Forgetting the terminator — every leaf must end with MAIN_CTA or WEBSITE_URL.
            - Skipping stepId=1 — the entry must exist and be exactly 1.

            NOTES:
            - Convo ads are LinkedIn-only. channelType is fixed to "LINKEDIN".
            - `message` supports HTML; preserve the user's markup verbatim.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoExisting convo ad ID — include to UPDATE; omit to CREATE.
nameYesAd name in the platform library (max 50 chars).
stepsYesOrdered list of conversation steps. MUST include stepId=1 as the entry.
flowIdNoLinkedIn convo flow version. Defaults to 7 — keep the default unless told otherwise.
senderIdYesLinkedIn sender ID. MUST come from get_linkedin_senders.
senderNameYesDisplay name matching senderId from get_linkedin_senders.
templateIdNoLinkedIn convo template ID. Defaults to 1 — keep the default unless told otherwise.
headlineTextYesSubject line shown above the message thread.
completionStatusNoDefaults to DRAFT.
bannerCreativeLibraryIdNoOptional: imageLibraryId of the banner image. Upload first via upload_image_creative.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A5/5.0
Behavior5/5

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

The description discloses extensive behavior beyond annotations: the step graph structure, action types and their rules, structural validation rules, the requirement for stepId=1, termination conditions, and mixing action types. It also includes a success response example and notes about HTML preservation. Annotations declare destructiveHint=true and readOnlyHint=false, which align with the create/update nature; no contradiction.

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

Conciseness5/5

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

The description is long but well-structured with headings like BEHAVIOR, PREREQUISITES, THE STEP GRAPH, ACTIONS, WARNING, INPUT PARAMETERS, EXAMPLE, SUCCESS RESPONSE, COMMON MISTAKES, and NOTES. It front-loads the purpose and core behavior, then systematically details rules and examples. Every section earns its place given the tool's complexity.

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?

For a complex tool with 10 parameters, nested steps, and multiple validation rules, the description is exceptionally complete. It includes a full example, success response format, common mistakes, and notes on HTML and channelType. An agent has everything needed to invoke the tool correctly, including edge cases like termination and entry step requirements.

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?

The description adds meaning beyond the schema's 100% coverage. For each parameter, it explains source (senderId from get_linkedin_senders), defaults (completionStatus, flowId, templateId), and relationships (bannerCreativeLibraryId from upload_image_creative). It also clarifies which fields are required for each action type. The schema descriptions are helpful, but the description enriches them with workflow context.

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 description explicitly states the verb 'Create or update' and the resource 'LinkedIn Conversation Ad', then defines the branching in-message chat concept. It clearly distinguishes between create and update based on the presence of `id`, and differentiates from sibling ad-creation tools by focusing on the convo ad structure. The title reinforces this but the description adds specific behavioral detail.

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 prerequisites: 'Call get_linkedin_senders to get a valid (senderId, senderName) pair' and 'upload it via upload_image_creative' for banners. It explicitly states when to use create vs update (id provided vs omitted). It also lists common mistakes that guide against misuse, effectively telling the agent what NOT to do. This is comprehensive usage guidance.

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