Skip to main content
Glama

Adapt an image ad

steal_ad
Idempotent

Makes one new image ad for a brand by adapting (remixing) a source image ad. Spends credits only after explicit confirm: true. Two steps: without confirm it returns a cost preview with idempotency_key, as quote_steal_ad does, and spends nothing; the same ad_id, brand_id and notes with confirm: true and that key start the ad and reserve credits. Returns a job reference for get_ad_status; an ad usually takes a few minutes and can fail its quality check, with refunded credits reported there. notes are guidance: the product image is chosen automatically and on-image wording can differ, while create_campaign takes a product image and prompt. Confirmed jobs prepare an unprepared source; source_preparation_usd is its maximum preparation cost. Does not publish ads. Pass language as a BCP-47 tag from the user’s requested output language (including requests in notes/prompt); use regional tags such as es-MX. The quote has no generated copy: never invent proposed copy. Copy is written after approval. Unsupported tags use site language, disclosed in the quote. Echo language unchanged on confirmation. Pass language as a BCP-47 tag from the user’s requested output language (including requests in notes/prompt); use regional tags such as es-MX. The quote has no generated copy: never invent proposed copy. Copy is written after approval. Unsupported tags use site language, disclosed in the quote. Echo language unchanged on confirmation.

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": {
      "ad_id": "<ad_id>",
      "brand_id": "<brand_id>"
    },
    "name": "steal_ad"
  }
}

Input Schema

NameRequiredDescriptionDefault
ad_idYesSource ad id from a search or list result or get_ad: an image ad from this account or the Ad Library. A video source gets no cost preview; image alternatives and a web link come back instead.
notesNoOptional direction in plain words, such as an offer, message or tone (up to 2,000 characters). Guidance, not a specification: it does not choose the product image, and the on-image headline can differ. The preview key is tied to these exact notes.
confirmNotrue starts the ad shown in the cost preview; absent or false returns the preview and reserves no user credits.
brand_idYesBrand id from list_brands: the brand the new ad is for.
languageNoRequested output language as a BCP-47 tag, e.g. es-MX. Unsupported tags fall back to site language. Repeat unchanged on confirmation.
max_creditsNoOptional credit ceiling the user approved: the max_credits value from the cost preview. When absent, the previewed price is the ceiling.
idempotency_keyNoidempotency_key from the cost preview, needed with confirm: true and valid for 15 minutes. A repeat with the same key returns the first result without a second charge.
offer_resolutionNoUser-selected offer and storage scope from a preceding offer check; requires its signed offer_choice_token.
offer_choice_tokenNoSigned offer_choice_token from the preceding offer check for this same request, valid for 15 minutes.
offer_contract_hashNoEcho this field from the quote on confirmation when returned. It binds the displayed saved offer; brand changes need a new quote.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / language
      Added value: +{
      +  "description": "Requested output language as a BCP-47 tag, e.g. es-MX. Unsupported tags fall back to site language. Repeat unchanged on confirmation.",
      +  "type": "string"
      +}
  2. Changed1 schema field changed
    • changedInput schema / properties / offer_resolution / properties / value / description
      Previous value: -"Exact offer text selected by the user, up to 160 characters."New value: +"Advisory offer text selected by the user; the signed offer remains authoritative, up to 160 characters."
  3. Changed1 schema field changed
    • changedOutput schema / (root)
      Previous value: -{
      -  "$schema": "https://json-schema.org/draft/2020-12/schema",
      -  "additionalProperties": false,
      -  "properties": {
      -    "_references": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "description": "Opaque action references accepted by subsequent tool calls.",
      -          "properties": {
      -            "job_id": {
      -              "anyOf": [
      -                {
      -                  "description": "job id value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "job id value in this response."
      -            }
      -          },
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Opaque action references accepted by subsequent tool calls."
      -    },
      -    "approved_terms": {
      -      "anyOf": [
      -        {
      -          "description": "approved terms value in this response.",
      -          "items": {
      -            "description": "approved terms value in this response.",
      -            "type": "string"
      -          },
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "approved terms value in this response."
      -    },
      -    "balance_credits": {
      -      "anyOf": [
      -        {
      -          "description": "balance credits value in this response.",
      -          "type": "number"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "balance credits value in this response."
      -    },
      -    "billing_url": {
      -      "anyOf": [
      -        {
      -          "description": "billing url value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "billing url value in this response."
      -    },
      -    "choices": {
      -      "anyOf": [
      -        {
      -          "description": "choices value in this response.",
      -          "items": {
      -            "description": "choices value in this response.",
      -            "type": "string"
      -          },
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "choices value in this response."
      -    },
      -    "code": {
      -      "anyOf": [
      -        {
      -          "description": "code value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "code value in this response."
      -    },
      -    "confirmation_required": {
      -      "description": "True for a cost preview awaiting explicit approval.",
      -      "type": "boolean"
      -    },
      -    "cost_credits": {
      -      "anyOf": [
      -        {
      -          "description": "Credits quoted or charged by this operation.",
      -          "type": "number"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Credits quoted or charged by this operation."
      -    },
      -    "enough_credits": {
      -      "anyOf": [
      -        {
      -          "description": "enough credits value in this response.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "enough credits value in this response."
      -    },
      -    "idempotency_key": {
      -      "anyOf": [
      -        {
      -          "description": "Key binding confirmation to this preview and preventing duplicate work.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Key binding confirmation to this preview and preventing duplicate work."
      -    },
      -    "image_ads": {
      -      "anyOf": [
      -        {
      -          "description": "At most three usable image alternatives for a video source.",
      -          "items": {
      -            "additionalProperties": false,
      -            "description": "At most three usable image alternatives for a video source.",
      -            "properties": {
      -              "ad_library_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "ad library url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "ad library url value in this response."
      -              },
      -              "body_text": {
      -                "anyOf": [
      -                  {
      -                    "description": "body text value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "body text value in this response."
      -              },
      -              "body_text_truncated": {
      -                "anyOf": [
      -                  {
      -                    "description": "body text truncated value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "body text truncated value in this response."
      -              },
      -              "confirmation_stale": {
      -                "anyOf": [
      -                  {
      -                    "description": "confirmation stale value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "confirmation stale value in this response."
      -              },
      -              "cta": {
      -                "anyOf": [
      -                  {
      -                    "description": "cta value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "cta value in this response."
      -              },
      -              "end_date": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider end date (YYYY-MM-DD); null if still running or unknown.",
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider end date (YYYY-MM-DD); null if still running or unknown."
      -              },
      -              "facebook_page_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "facebook page id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "facebook page id value in this response."
      -              },
      -              "filters": {
      -                "anyOf": [
      -                  {
      -                    "additionalProperties": false,
      -                    "description": "filters value in this response.",
      -                    "properties": {
      -                      "angle": {
      -                        "anyOf": [
      -                          {
      -                            "description": "angle value in this response.",
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "angle value in this response."
      -                      },
      -                      "industry_slug": {
      -                        "anyOf": [
      -                          {
      -                            "description": "Industry filter value, when known.",
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "Industry filter value, when known."
      -                      }
      -                    },
      -                    "type": "object"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "filters value in this response."
      -              },
      -              "first_seen": {
      -                "anyOf": [
      -                  {
      -                    "description": "first seen value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "first seen value in this response."
      -              },
      -              "for": {
      -                "anyOf": [
      -                  {
      -                    "description": "for value in this response.",
      -                    "maxLength": 40,
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "for value in this response."
      -              },
      -              "format": {
      -                "anyOf": [
      -                  {
      -                    "description": "Static image or video media format.",
      -                    "enum": [
      -                      "static",
      -                      "video"
      -                    ],
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Static image or video media format."
      -              },
      -              "group_id": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider variation/collation group; null when unavailable.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider variation/collation group; null when unavailable."
      -              },
      -              "hook": {
      -                "anyOf": [
      -                  {
      -                    "additionalProperties": false,
      -                    "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable.",
      -                    "properties": {
      -                      "on_screen": {
      -                        "description": "on screen value in this response.",
      -                        "items": {
      -                          "description": "on screen value in this response.",
      -                          "maxLength": 240,
      -                          "type": "string"
      -                        },
      -                        "maxItems": 3,
      -                        "type": "array"
      -                      },
      -                      "opening_visual": {
      -                        "anyOf": [
      -                          {
      -                            "description": "opening visual value in this response.",
      -                            "maxLength": 400,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "opening visual value in this response."
      -                      },
      -                      "source": {
      -                        "description": "Where the accessible ad or advertiser evidence came from.",
      -                        "enum": [
      -                          "video",
      -                          "image"
      -                        ],
      -                        "type": "string"
      -                      },
      -                      "spoken": {
      -                        "anyOf": [
      -                          {
      -                            "description": "spoken value in this response.",
      -                            "maxLength": 1000,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "spoken value in this response."
      -                      },
      -                      "type": {
      -                        "anyOf": [
      -                          {
      -                            "description": "type value in this response.",
      -                            "maxLength": 120,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "Stored hook category; may be present when opener text is unavailable. Null when no stored type is known."
      -                      },
      -                      "written": {
      -                        "anyOf": [
      -                          {
      -                            "description": "written value in this response.",
      -                            "maxLength": 500,
      -                            "type": "string"
      -                          },
      -                          {
      -                            "type": "null"
      -                          }
      -                        ],
      -                        "description": "written value in this response."
      -                      }
      -                    },
      -                    "required": [
      -                      "spoken",
      -                      "on_screen",
      -                      "opening_visual",
      -                      "written",
      -                      "type",
      -                      "source"
      -                    ],
      -                    "type": "object"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Observed opening speech, image text, visual or written hook; null when evidence is unavailable."
      -              },
      -              "hook_type": {
      -                "anyOf": [
      -                  {
      -                    "description": "hook type value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "hook type value in this response."
      -              },
      -              "hook_type_filter": {
      -                "anyOf": [
      -                  {
      -                    "description": "hook type filter value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "hook type filter value in this response."
      -              },
      -              "id": {
      -                "anyOf": [
      -                  {
      -                    "description": "id value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "id value in this response."
      -              },
      -              "image_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "image url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "image url value in this response."
      -              },
      -              "landing_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "landing url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "landing url value in this response."
      -              },
      -              "last_confirmed_at": {
      -                "anyOf": [
      -                  {
      -                    "description": "Most recent confirmed delivery timestamp, when known.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Most recent confirmed delivery timestamp, when known."
      -              },
      -              "last_seen": {
      -                "anyOf": [
      -                  {
      -                    "description": "last seen value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "last seen value in this response."
      -              },
      -              "original_headline": {
      -                "anyOf": [
      -                  {
      -                    "description": "original headline value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "original headline value in this response."
      -              },
      -              "page_name": {
      -                "anyOf": [
      -                  {
      -                    "description": "page name value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "page name value in this response."
      -              },
      -              "platforms": {
      -                "anyOf": [
      -                  {
      -                    "description": "platforms value in this response.",
      -                    "items": {
      -                      "description": "platforms value in this response.",
      -                      "type": "string"
      -                    },
      -                    "type": "array"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "platforms value in this response."
      -              },
      -              "run_duration_days": {
      -                "anyOf": [
      -                  {
      -                    "description": "Computed from the provider start date to the last confirmed delivery; null when unknown.",
      -                    "maximum": 9007199254740991,
      -                    "minimum": 0,
      -                    "type": "integer"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Computed from the provider start date to the last confirmed delivery; null when unknown."
      -              },
      -              "schema_version": {
      -                "anyOf": [
      -                  {
      -                    "const": 1,
      -                    "description": "schema version value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "schema version value in this response."
      -              },
      -              "source": {
      -                "anyOf": [
      -                  {
      -                    "description": "Where the accessible ad or advertiser evidence came from.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Where the accessible ad or advertiser evidence came from."
      -              },
      -              "start_date": {
      -                "anyOf": [
      -                  {
      -                    "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one.",
      -                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Provider start date (YYYY-MM-DD); null when the provider did not report one."
      -              },
      -              "steal_caution": {
      -                "anyOf": [
      -                  {
      -                    "description": "steal caution value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "steal caution value in this response."
      -              },
      -              "still_running": {
      -                "anyOf": [
      -                  {
      -                    "description": "Current delivery evidence: true, false or null when unknown.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Current delivery evidence: true, false or null when unknown."
      -              },
      -              "strength": {
      -                "anyOf": [
      -                  {
      -                    "description": "strength value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "strength value in this response."
      -              },
      -              "strength_label": {
      -                "anyOf": [
      -                  {
      -                    "description": "Delivery-based label: winner, solid or testing. Cautions are separate.",
      -                    "enum": [
      -                      "winner",
      -                      "solid",
      -                      "testing"
      -                    ],
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "Delivery-based label: winner, solid or testing. Cautions are separate."
      -              },
      -              "variation_count": {
      -                "anyOf": [
      -                  {
      -                    "description": "variation count value in this response.",
      -                    "type": "number"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "variation count value in this response."
      -              },
      -              "video_asset_missing": {
      -                "anyOf": [
      -                  {
      -                    "description": "video asset missing value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video asset missing value in this response."
      -              },
      -              "video_thumbnail_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "video thumbnail url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video thumbnail url value in this response."
      -              },
      -              "video_url": {
      -                "anyOf": [
      -                  {
      -                    "description": "video url value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "video url value in this response."
      -              },
      -              "why": {
      -                "anyOf": [
      -                  {
      -                    "description": "why value in this response.",
      -                    "type": "string"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "why value in this response."
      -              },
      -              "your_rival": {
      -                "anyOf": [
      -                  {
      -                    "description": "your rival value in this response.",
      -                    "type": "boolean"
      -                  },
      -                  {
      -                    "type": "null"
      -                  }
      -                ],
      -                "description": "your rival value in this response."
      -              }
      -            },
      -            "type": "object"
      -          },
      -          "maxItems": 3,
      -          "type": "array"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "At most three usable image alternatives for a video source."
      -    },
      -    "max_credits": {
      -      "anyOf": [
      -        {
      -          "description": "Explicit credit ceiling to echo after the user approves this quote.",
      -          "type": "number"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Explicit credit ceiling to echo after the user approves this quote."
      -    },
      -    "message": {
      -      "anyOf": [
      -        {
      -          "description": "message value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "message value in this response."
      -    },
      -    "needs_attention": {
      -      "anyOf": [
      -        {
      -          "description": "True when the ad is waiting on support before it can continue.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "True when the ad is waiting on support before it can continue."
      -    },
      -    "needs_choice": {
      -      "anyOf": [
      -        {
      -          "description": "needs choice value in this response.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "needs choice value in this response."
      -    },
      -    "next": {
      -      "anyOf": [
      -        {
      -          "description": "next value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "next value in this response."
      -    },
      -    "next_action": {
      -      "anyOf": [
      -        {
      -          "description": "Suggested next operation for the current job state.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Suggested next operation for the current job state."
      -    },
      -    "offer_choice_token": {
      -      "anyOf": [
      -        {
      -          "description": "offer choice token value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "offer choice token value in this response."
      -    },
      -    "offer_contract_hash": {
      -      "anyOf": [
      -        {
      -          "description": "offer contract hash value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "offer contract hash value in this response."
      -    },
      -    "poll_after_seconds": {
      -      "anyOf": [
      -        {
      -          "description": "Seconds between status checks; zero when finished.",
      -          "maximum": 9007199254740991,
      -          "minimum": 0,
      -          "type": "integer"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Seconds between status checks; zero when finished."
      -    },
      -    "script_available": {
      -      "anyOf": [
      -        {
      -          "description": "Whether the source can be adapted as a Script in the web app.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Whether the source can be adapted as a Script in the web app."
      -    },
      -    "source_preparation_usd": {
      -      "anyOf": [
      -        {
      -          "description": "source preparation usd value in this response.",
      -          "type": "number"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "source preparation usd value in this response."
      -    },
      -    "source_type": {
      -      "anyOf": [
      -        {
      -          "description": "Media type of the requested source.",
      -          "enum": [
      -            "static",
      -            "video"
      -          ],
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Media type of the requested source."
      -    },
      -    "state": {
      -      "anyOf": [
      -        {
      -          "description": "state value in this response.",
      -          "enum": [
      -            "queued",
      -            "running",
      -            "capacity_deferred",
      -            "needs_attention",
      -            "ready",
      -            "no_preview",
      -            "loading_result",
      -            "failed",
      -            "cancelled",
      -            "unknown"
      -          ],
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "state value in this response."
      -    },
      -    "status": {
      -      "anyOf": [
      -        {
      -          "default": "processing",
      -          "description": "Current progress or delivery state.",
      -          "enum": [
      -            "queued",
      -            "running",
      -            "processing",
      -            "completed",
      -            "complete",
      -            "failed",
      -            "cancelled",
      -            "pending",
      -            "ready",
      -            "started",
      -            "already_started",
      -            "already_done",
      -            "in_progress",
      -            "active",
      -            "paused",
      -            "draft",
      -            "kept",
      -            "discarded",
      -            "delivered",
      -            "expired",
      -            "reserved",
      -            "settled",
      -            "released",
      -            "held",
      -            "consumed",
      -            "generating",
      -            "unknown"
      -          ],
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Current progress or delivery state."
      -    },
      -    "suggested_offer": {
      -      "anyOf": [
      -        {
      -          "description": "suggested offer value in this response.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "suggested offer value in this response."
      -    },
      -    "terminal": {
      -      "anyOf": [
      -        {
      -          "description": "True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention.",
      -          "type": "boolean"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention."
      -    },
      -    "web_url": {
      -      "anyOf": [
      -        {
      -          "description": "StealAds page for continuing this task.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "StealAds page for continuing this task."
      -    },
      -    "what_happens": {
      -      "anyOf": [
      -        {
      -          "description": "Plain explanation of the proposed work, confirmation steps and quote expiry.",
      -          "type": "string"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "Plain explanation of the proposed work, confirmation steps and quote expiry."
      -    },
      -    "what_we_will_make": {
      -      "anyOf": [
      -        {
      -          "additionalProperties": false,
      -          "description": "what we will make value in this response.",
      -          "properties": {
      -            "instructions": {
      -              "anyOf": [
      -                {
      -                  "description": "instructions value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "instructions value in this response."
      -            },
      -            "instructions_origin": {
      -              "anyOf": [
      -                {
      -                  "description": "instructions origin value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "instructions origin value in this response."
      -            },
      -            "key_message": {
      -              "anyOf": [
      -                {
      -                  "description": "key message value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "key message value in this response."
      -            },
      -            "offer": {
      -              "anyOf": [
      -                {
      -                  "description": "offer value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "offer value in this response."
      -            },
      -            "offer_origin": {
      -              "anyOf": [
      -                {
      -                  "description": "offer origin value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "offer origin value in this response."
      -            },
      -            "offer_scope": {
      -              "anyOf": [
      -                {
      -                  "description": "offer scope value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "offer scope value in this response."
      -            },
      -            "source_ad": {
      -              "anyOf": [
      -                {
      -                  "description": "source ad value in this response.",
      -                  "type": "string"
      -                },
      -                {
      -                  "type": "null"
      -                }
      -              ],
      -              "description": "source ad value in this response."
      -            }
      -          },
      -          "type": "object"
      -        },
      -        {
      -          "type": "null"
      -        }
      -      ],
      -      "description": "what we will make value in this response."
      -    }
      -  },
      -  "type": "object"
      -}New value: +null
  4. Changed11 schema fields changed
    • addedInput schema / properties / offer_choice_token
      Added value: +{
      +  "description": "Signed offer_choice_token from the preceding offer check for this same request, valid for 15 minutes.",
      +  "maxLength": 1024,
      +  "type": "string"
      +}
    • addedInput schema / properties / offer_contract_hash
      Added value: +{
      +  "description": "Echo this field from the quote on confirmation when returned. It binds the displayed saved offer; brand changes need a new quote.",
      +  "maxLength": 128,
      +  "minLength": 1,
      +  "type": "string"
      +}
    • addedInput schema / properties / offer_resolution
      Added value: +{
      +  "description": "User-selected offer and storage scope from a preceding offer check; requires its signed offer_choice_token.",
      +  "properties": {
      +    "choice": {
      +      "description": "saved uses brand info; this_ad keeps new info for this run only; save_brand also updates the brand; omit leaves the offer off.",
      +      "enum": [
      +        "saved",
      +        "this_ad",
      +        "save_brand",
      +        "omit"
      +      ],
      +      "type": "string"
      +    },
      +    "user_confirmed": {
      +      "const": true,
      +      "description": "true records that the user explicitly selected this choice after seeing the offer check.",
      +      "type": "boolean"
      +    },
      +    "value": {
      +      "description": "Exact offer text selected by the user, up to 160 characters.",
      +      "maxLength": 160,
      +      "minLength": 1,
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "choice",
      +    "value",
      +    "user_confirmed"
      +  ],
      +  "type": "object"
      +}
    • addedOutput schema / properties / approved_terms
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "approved terms value in this response.",
      +      "items": {
      +        "description": "approved terms value in this response.",
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "approved terms value in this response."
      +}
    • addedOutput schema / properties / choices
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "choices value in this response.",
      +      "items": {
      +        "description": "choices value in this response.",
      +        "type": "string"
      +      },
      +      "type": "array"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "choices value in this response."
      +}
    • addedOutput schema / properties / code
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "code value in this response.",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "code value in this response."
      +}
    • addedOutput schema / properties / needs_choice
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "needs choice value in this response.",
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "needs choice value in this response."
      +}
    • addedOutput schema / properties / offer_choice_token
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "offer choice token value in this response.",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "offer choice token value in this response."
      +}
    • addedOutput schema / properties / offer_contract_hash
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "offer contract hash value in this response.",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "offer contract hash value in this response."
      +}
    • addedOutput schema / properties / suggested_offer
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "suggested offer value in this response.",
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "suggested offer value in this response."
      +}
    • addedOutput schema / properties / what_we_will_make
      Added value: +{
      +  "anyOf": [
      +    {
      +      "additionalProperties": false,
      +      "description": "what we will make value in this response.",
      +      "properties": {
      +        "instructions": {
      +          "anyOf": [
      +            {
      +              "description": "instructions value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "instructions value in this response."
      +        },
      +        "instructions_origin": {
      +          "anyOf": [
      +            {
      +              "description": "instructions origin value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "instructions origin value in this response."
      +        },
      +        "key_message": {
      +          "anyOf": [
      +            {
      +              "description": "key message value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "key message value in this response."
      +        },
      +        "offer": {
      +          "anyOf": [
      +            {
      +              "description": "offer value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "offer value in this response."
      +        },
      +        "offer_origin": {
      +          "anyOf": [
      +            {
      +              "description": "offer origin value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "offer origin value in this response."
      +        },
      +        "offer_scope": {
      +          "anyOf": [
      +            {
      +              "description": "offer scope value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "offer scope value in this response."
      +        },
      +        "source_ad": {
      +          "anyOf": [
      +            {
      +              "description": "source ad value in this response.",
      +              "type": "string"
      +            },
      +            {
      +              "type": "null"
      +            }
      +          ],
      +          "description": "source ad value in this response."
      +        }
      +      },
      +      "type": "object"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "what we will make value in this response."
      +}
  5. Changed2 schema fields changed
    • changedInput schema / properties / confirm / description
      Previous value: -"true starts the ad shown in the cost preview; absent or false returns the preview and spends nothing."New value: +"true starts the ad shown in the cost preview; absent or false returns the preview and reserves no user credits."
    • addedOutput schema / properties / source_preparation_usd
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "source preparation usd value in this response.",
      +      "type": "number"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "source preparation usd value in this response."
      +}
  6. Changed6 schema fields changed
    • changedInput schema / properties / ad_id / description
      Previous value: -"Source ad to steal: one of your ads or an Ad Library ad from search_ads."New value: +"Source ad id from a search or list result or get_ad: an image ad from this account or the Ad Library. A video source gets no cost preview; image alternatives and a web link come back instead."
    • changedInput schema / properties / brand_id / description
      Previous value: -"Your brand the new creative is for."New value: +"Brand id from list_brands: the brand the new ad is for."
    • changedInput schema / properties / confirm / description
      Previous value: -"Set to true to spend the credits shown in the preview. Leave it out to see the cost first."New value: +"true starts the ad shown in the cost preview; absent or false returns the preview and spends nothing."
    • changedInput schema / properties / idempotency_key / description
      Previous value: -"The idempotency_key from the preview. Required with confirm: true. Repeating a confirmed call with the same key returns the first result and does not spend again."New value: +"idempotency_key from the cost preview, needed with confirm: true and valid for 15 minutes. A repeat with the same key returns the first result without a second charge."
    • changedInput schema / properties / max_credits / description
      Previous value: -"Optional for one compatibility release: the approved credit ceiling. An omitted value uses the signed quote price as the ceiling."New value: +"Optional credit ceiling the user approved: the max_credits value from the cost preview. When absent, the previewed price is the ceiling."
    • changedInput schema / properties / notes / description
      Previous value: -"Optional direction, such as an offer or message to feature."New value: +"Optional direction in plain words, such as an offer, message or tone (up to 2,000 characters). Guidance, not a specification: it does not choose the product image, and the on-image headline can differ. The preview key is tied to these exact notes."
  7. Changed4 schema fields changed
    • addedOutput schema / properties / needs_attention
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "True when the ad is waiting on support before it can continue.",
      +      "type": "boolean"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "True when the ad is waiting on support before it can continue."
      +}
    • addedOutput schema / properties / state
      Added value: +{
      +  "anyOf": [
      +    {
      +      "description": "state value in this response.",
      +      "enum": [
      +        "queued",
      +        "running",
      +        "capacity_deferred",
      +        "needs_attention",
      +        "ready",
      +        "no_preview",
      +        "loading_result",
      +        "failed",
      +        "cancelled",
      +        "unknown"
      +      ],
      +      "type": "string"
      +    },
      +    {
      +      "type": "null"
      +    }
      +  ],
      +  "description": "state value in this response."
      +}
    • changedOutput schema / properties / terminal / anyOf
      Previous value: -[
      -  {
      -    "description": "True only when the image is ready or the ad failed or was cancelled.",
      -    "type": "boolean"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]New value: +[
      +  {
      +    "description": "True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention.",
      +    "type": "boolean"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / terminal / description
      Previous value: -"True only when the image is ready or the ad failed or was cancelled."New value: +"True when polling should stop: ready, ended without a preview, failed, cancelled, or awaiting human attention."
  8. First observed

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations: credits are reserved only after confirm: true, the preview costs nothing, jobs take a few minutes, may fail a quality check with refunded credits reported in get_ad_status, and confirmed jobs may prepare an unprepared source with a maximum source_preparation_usd. The idempotentHint annotation is reinforced with the 15-minute key semantics.

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

Conciseness2/5

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

The final block ('Pass language as a BCP-47 tag ... Echo language unchanged on confirmation.') is duplicated verbatim, which is pure waste in an already dense paragraph. The confirm/preview mechanic is front-loaded well, but the run-on sentence structure with repeated language rules hurts readability.

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?

For a 10-parameter mutating tool with a nested object and no output schema, the description covers the state machine (preview, confirm, job, refund), what is returned (a job reference for get_ad_status), and the language contract. The omission is any explanation of the offer-confirmation parameters, which are only covered by the schema.

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 coverage is 100%, so every parameter already carries its own description, and most of the description's parameter talk (notes being guidance, language fallback, echoing the key) restates it. The useful addition is the cross-parameter framing that the same ad_id, brand_id and notes must accompany confirm plus the key, but the nested offer_resolution / offer_choice_token / offer_contract_hash group is never addressed in the description.

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?

Opens with a specific verb and resource: 'Makes one new image ad for a brand by adapting (remixing) a source image ad.' It also distinguishes itself from create_campaign (which 'takes a product image and prompt') and from quote_steal_ad (the preview-only sibling), so an agent can tell them apart without opening schemas.

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

Usage Guidelines4/5

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

Explicitly frames the two-step workflow: call without confirm for a cost preview, then repeat with confirm: true plus the idempotency_key. It names the related siblings (quote_steal_ad, get_ad_status, create_campaign) and states the scope exclusion 'Does not publish ads.' There is no explicit statement of when this tool should NOT be used beyond that boundary.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.