Skip to main content
Glama
ghl-mcp-server-v2

ghl-mcp-server-v2

by zackscriven

ghl_ad_fb_ad_upsert

Idempotent

Create or update a Facebook ad by submitting campaign, ad set, and creative details to the ad publishing endpoint.

Instructions

Upsert ad Create or update a Facebook ad Endpoint: PUT /ad-publishing/facebook/ads (Version header: v3; source: v3/ad-publishing-v3.json) OAuth scopes: adPublishing.write

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "body": "<body>"
    },
    "name": "ghl_ad_fb_ad_upsert"
  }
}

Input Schema

NameRequiredDescriptionDefault
bodyYesRequest body (schema carried verbatim from the official OpenAPI spec).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed10 schema fields changedv2.1.0
    • changedInput schema / properties / body / properties / cta / description
      Previous value: -"Call to action type"New value: +"Call-to-action button. Valid values depend on the parent campaign objective (and, for sales, the ad set `conversionLocation`) — OUTCOME_LEADS: `APPLY_NOW`, `DOWNLOAD`, `GET_OFFER`, `GET_QUOTE`, `LEARN_MORE`, `SIGN_UP`, `SUBSCRIBE`; OUTCOME_TRAFFIC: `APPLY_NOW`, `BOOK_TRAVEL`, `BUY_NOW`, `CONTACT_US`, `GET_OFFER`, `GET_PROMOTIONS`, `GET_QUOTE`, `LEARN_MORE`, `NO_BUTTON`, `ORDER_NOW`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`; OUTCOME_ENGAGEMENT: `APPLY_NOW`, `BOOK_TRAVEL`, `CONTACT_US`, `GET_PROMOTIONS`, `GET_QUOTE`, `INQUIRE_NOW`, `LEARN_MORE`, `MESSAGE_PAGE`, `ORDER_NOW`, `SEND_UPDATES`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`; OUTCOME_SALES with `conversionLocation: messaging`: `APPLY_NOW`, `BOOK_TRAVEL`, `CONTACT_US`, `GET_QUOTE`, `LEARN_MORE`, `MESSAGE_PAGE`, `ORDER_NOW`, `PLAY_GAME`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`; OUTCOME_SALES with `conversionLocation: website`: `APPLY_NOW`, `BOOK_TRAVEL`, `BUY_TICKETS`, `CONTACT_US`, `GET_OFFER`, `GET_QUOTE`, `GET_SHOWTIMES`, `LEARN_MORE`, `LISTEN_NOW`, `ORDER_NOW`, `PLAY_GAME`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`, `WATCH_MORE`. Note `BOOK_TRAVEL` is the \"Book now\" button. Not validated server-side, so values outside this set are forwarded to Facebook and may be rejected there."
    • changedInput schema / properties / body / properties / description / description
      Previous value: -"Ad description text"New value: +"Single ad description. SINGLE (image and video) ads take their description from the `descriptions` array, and carousel cards from `media[].description`."
    • addedInput schema / properties / body / properties / descriptions
      Added value: +{
      +  "description": "Description variants. Applies to SINGLE (image and video) ads only — carousel ads take their per-card description from `media[].description`. Supply more than one to run Facebook text variations.",
      +  "example": [
      +    {
      +      "text": "Automation Test Description"
      +    }
      +  ],
      +  "items": {
      +    "properties": {
      +      "text": {
      +        "description": "Description variant",
      +        "example": "Automation Test Description",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / body / properties / headline / description
      Previous value: -"Ad headline text"New value: +"Ad-level headline for CAROUSEL ads — used for any card that does not set its own `media[].headline`. SINGLE (image and video) ads take their headline from the `headlines` array instead."
    • addedInput schema / properties / body / properties / headlines
      Added value: +{
      +  "description": "Headline variants. Applies to SINGLE (image and video) ads only — carousel ads take their per-card headline from `media[].headline`, falling back to the singular `headline`. Supply more than one to run Facebook text variations.",
      +  "example": [
      +    {
      +      "text": "Automation Test Headline"
      +    },
      +    {
      +      "text": "Automation Test Headline1"
      +    }
      +  ],
      +  "items": {
      +    "properties": {
      +      "text": {
      +        "description": "Headline variant",
      +        "example": "Automation Test Headline",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • changedInput schema / properties / body / properties / media / items / properties / type / example
      Previous value: -"IMAGE"New value: +"image"
    • addedInput schema / properties / body / properties / media / items / title
      Added value: +"MediaDTO"
    • changedInput schema / properties / body / properties / primaryText / description
      Previous value: -"Ad primary text"New value: +"Single primary text. Normalised into `primaryTexts` when that array is empty, so send `primaryTexts` instead unless you have exactly one variant."
    • addedInput schema / properties / body / properties / primaryTexts
      Added value: +{
      +  "description": "Primary text variants. Used by every media type. Supply more than one to run Facebook text variations; with a single entry it becomes the ad message. Prefer this over the singular `primaryText`.",
      +  "example": [
      +    {
      +      "text": "Automation Test Primary Text"
      +    }
      +  ],
      +  "items": {
      +    "properties": {
      +      "text": {
      +        "description": "Primary text variant",
      +        "example": "Automation Test Primary Text",
      +        "type": "string"
      +      }
      +    },
      +    "required": [
      +      "text"
      +    ],
      +    "type": "object"
      +  },
      +  "type": "array"
      +}
    • addedInput schema / properties / body / title
      Added value: +"UpsertAdDTO"
  2. First observedv2.0.0

TDQS

B3.4/5.0
Behavior3/5

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false, openWorldHint=true). The description adds one genuinely useful behavioral fact beyond that: the required OAuth scope adPublishing.write. The remaining content (endpoint path, version header, spec source) is plumbing rather than agent-relevant behavior, and nothing is said about side effects like sending data to Facebook or how the ad transitions to active.

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?

Four short lines, front-loaded with the action and its one-line explanation. The endpoint/version/source lines are marginally useful for debugging but are metadata rather than task guidance; nothing is bloated, though.

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

Completeness3/5

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

For a nested 17-property mutation body with no output schema, the description is thin: it does not explain what an upsert response yields (e.g. the ad id needed for pause/publish), nor the lifecycle around publishing. The rich schema compensates for field-level gaps, but lifecycle context is absent.

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

Parameters3/5

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

Schema description coverage is 100% and the single `body` object is documented exhaustively inline (cta validity per objective, headline vs headlines rules, media type semantics). The description adds no parameter meaning whatsoever, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb and resource: 'Create or update a Facebook ad'. The 'Facebook ad' qualifier distinguishes it from the many sibling adset/campaign/audience tools in the same family. It does not explicitly contrast with ghl_ad_fb_ad_duplicate, ghl_ad_fb_ad_pause, or ghl_ad_fb_ad_resume, so sibling differentiation is only partial.

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

Usage Guidelines3/5

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

'Create or update' implies the upsert semantics (use this whether the ad exists or not), which is implicit guidance. However, there is no statement of when to prefer this over the duplicate/pause/resume/delete siblings, no prerequisites, and no note that the ad may need a separate publish step.

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

Deploy Server

Other Tools