Skip to main content
Glama

Metadata MCP Connector

by io.metadata.mcp-server
OverviewDiscussionsAdmin

Create or Update LinkedIn Document Ad

create_update_document_ad
Destructive

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

            A LinkedIn Document Ad promotes a multi-page document (a PDF — e.g. a
            whitepaper, ebook, report, or guide) natively in the LinkedIn feed.
            Members preview the first few pages inline, then unlock the full
            document (typically gated behind a lead form). It is LinkedIn-only.

            IMPORTANT: This tool is ONLY for LinkedIn Document Ads
            (channelType=LINKEDIN, adType=DOCUMENT). 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 Sponsored Messaging use
            create_update_linkedin_message_ad.

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

            CREATIVE WORKFLOW (MUST DO BEFORE CALLING):
            1. The document must already exist in the creative library as a
               DOCUMENT asset. Find it with
               `search_library_creatives_by_name(contentTypes="DOCUMENT")`, or
               confirm a specific id with `fetch_creative_details`.
            2. Pass that asset's integer id as `libraryId`. It MUST be a
               DOCUMENT-type creative — an image or video id will be rejected
               by LinkedIn. Unlike IMAGE/VIDEO ads there is NO display URL: the
               gated document is the destination, so no link field is accepted.

            CHARACTER LIMITS (mirror the LinkedIn ad limits the platform UI enforces):
            - name      <= 50   chars  (ad name in the library)
            - headline  <= 200  chars  (the headline shown with the document)
            - text      <= 3000 chars  (the introductory text)

            INPUT PARAMETERS:
            - id (optional): Existing Document Ad ID. Provide to UPDATE; omit to CREATE.
            - name (required, <= 50): Ad name in the library.
            - libraryId (required): Integer id of the DOCUMENT creative in the
              library (contentType=DOCUMENT). NOT an image/video id.
            - headline (required, <= 200): Headline shown with the document.
            - text (required, <= 3000): Introductory text shown with the document.
            - ctaType (optional, default UNLOCK_FULL_DOCUMENT): the call-to-action.
              UNLOCK_FULL_DOCUMENT is the document-gate CTA.
            - maxPreviewPages (optional, default 1): how many pages of the document
              are previewable before the unlock gate. Positive integer.
            - completionStatus (optional, default DRAFT): "DRAFT" or "COMPLETED".
              Use COMPLETED only when every required field is final.

            WHEN TO USE:
            - User asks to "create a LinkedIn Document Ad" / "whitepaper ad" /
              "promote a PDF / ebook / report on LinkedIn".
            - User wants to update an existing Document Ad.

            WHEN NOT TO USE:
            - Feed image / GIF ad -> create_update_image_ad
            - Feed video ad -> create_update_video_ad
            - Branching conversation flow -> create_update_convo_ad
            - One-shot Sponsored Message -> create_update_linkedin_message_ad

            EXAMPLE USAGE (Create):
            create_update_document_ad(
                name="Q3_Whitepaper_LI_Document",
                libraryId=15791,
                headline="The 2026 State of B2B Marketing",
                text="Download our latest research on pipeline attribution.",
                maxPreviewPages=2,
            )

            EXAMPLE USAGE (Update):
            create_update_document_ad(
                id=29144,
                name="Q3_Whitepaper_LI_Document_v2",
                libraryId=15791,
                headline="The 2026 State of B2B Marketing (Updated)",
                text="Now with fresh benchmarks.",
            )

            COMMON MISTAKES:
            - Passing an IMAGE/VIDEO libraryId — the asset must be a DOCUMENT
              (use search_library_creatives_by_name(contentTypes="DOCUMENT")).
            - Passing a display / landing URL — Document Ads have no link field.
            - Using this tool for a non-LinkedIn channel — Document Ads are LinkedIn-only.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
idNoExisting Document Ad ID — include to UPDATE; omit to CREATE.
nameYesAd name in the platform library (max 50 characters).
textYesIntroductory text shown with the document (max 3000 characters).
ctaTypeNoCall-to-action. Defaults to UNLOCK_FULL_DOCUMENT (the document-gate CTA).
headlineYesHeadline shown with the document (max 200 characters).
libraryIdYesInteger id of the DOCUMENT creative in the library (contentType=DOCUMENT). Get it from search_library_creatives_by_name(contentTypes="DOCUMENT"). NOT an image/video id.
maxPreviewPagesNoHow many document pages are previewable before the unlock gate. Defaults to 1.
completionStatusNoDefaults to DRAFT. Use COMPLETED only when every required field is final.

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?

Annotations already flag destructive/read-write behavior, but the description adds substantial non-obvious context: create-versus-update logic based on id, no display URL accepted, LinkedIn-only enforcement, rejection of image/video libraryIds, defaults for ctaType/maxPreviewPages/completionStatus, and character limits mirroring platform UI. No contradiction with annotations exists.

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?

Although long, the description is tightly organized with scannable headings, bulleted requirements, character-limit summaries, examples, and a COMMON MISTAKES list. The essential create/update behavior is front-loaded before details. Every major block earns its place for an 8-parameter tool with prerequisites and sibling alternatives.

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

Completeness4/5

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

Given the tool's complexity, the description covers prerequisites, parameter semantics, routing, examples, and failure-prone mistakes thoroughly. The only notable gap is that it does not describe the return value or response shape after create/update, and no output schema exists to fill that gap. This is a minor omission against an otherwise complete definition.

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%, yet the description still adds meaningful semantics beyond the schema: libraryId must be a DOCUMENT creative and not an image/video id, UNLOCK_FULL_DOCUMENT is the document-gate CTA, no link field exists for this ad type, and completionStatus should be COMPLETED only when required fields are final. It also gives realistic create and update examples that bind parameters to use cases.

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 names the exact verb+resource: 'Create a new or update an existing LinkedIn Document Ad on the Metadata platform.' It further narrows scope with 'LinkedIn-only', distinguishes DOCUMENT ads from IMAGE/GIF/VIDEO/CONVO/Sponsored Messaging, and makes it impossible to confuse with sibling ad-creation tools.

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 a dedicated WHEN TO USE section with concrete user-phrase triggers, a WHEN NOT TO USE section that names four specific sibling tools, and a MUST-DO creative workflow requiring the document to exist in the library first. This is explicit routing guidance, not vague inference.

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