create_update_document_ad

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.