shopify-chatgpt-ads-mcp

Overview Schema Source Related Servers Discussions Admin

Create ad (paused)

create_ad

Create a paused OpenAI ad in a specified ad group, submitting it for review. Supports chat card and product-feed templates with images, links, and default product fields.

Instructions

Create an ad, ALWAYS paused; creating it submits it for review. chat_card: title (3-50 chars), body (max 100), https target_url, and an image: image_url (https, at least 640x640; uploaded to OpenAI for you) or file_id, or 4-6 square file_ids where the account allows it. product_ad_template (product-feed ad groups, at most one each): image and link come from each product; title/body/price default to {{product.title}}, {{product.body}}, {{product.price}}. Then call preview_ad.

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_group_id": "<ad_group_id>",
      "name": "<name>",
      "type": "<type>"
    },
    "name": "create_ad"
  }
}

Input Schema

Name	Required	Description
`body`	No
`name`	Yes
`type`	Yes
`price`	No
`title`	No
`file_id`	No
`file_ids`	No
`image_url`	No
`target_url`	No
`ad_group_id`	Yes	Ad group id
`query_string_template`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.2.0Nov 13, 2026

TDQS

A4.5/5.0

Behavior5/5

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

Annotations only say readOnlyHint=false, openWorldHint=true, destructiveHint=false. The description goes well beyond them: the resulting state is always paused, creation triggers a review submission, image_url is uploaded to OpenAI on the caller's behalf, and template ads inherit product fields via {{product.*}} placeholders. These are non-obvious side effects an agent could not infer from the structured fields.

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?

Front-loaded with the most important fact (always paused, submitted for review) and then proceeds type by type. It is dense and the inline field lists are a little hard to parse, but no sentence is filler.

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 an 11-param, no-output-schema mutation tool this covers the hard parts: state after creation, review side effect, image constraints, and the mandatory preview_ad follow-up. Gaps remain around the unexplained params (name, ad_group_id, query_string_template) and what the call returns (e.g., an ad id to feed into preview_ad).

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

Parameters4/5

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

With only 9% schema description coverage across 11 params, the description carries most of the load and does so for the important ones: https target_url, image_url requiring at least 640x640, the 4-6 square file_ids option, and template placeholder defaults for title/body/price. It leaves name, ad_group_id and query_string_template entirely unexplained, which keeps it short of a 5.

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?

States a specific verb and resource ('Create an ad') plus the critical qualifier that the ad is ALWAYS created paused and submitted for review. This distinguishes it cleanly from update_ad, archive_ad and pause_ad in the sibling list.

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?

Gives explicit routing between the two ad types ('chat_card' vs 'product_ad_template (product-feed ad groups)') and mandates the follow-up step 'Then call preview_ad'. It lacks explicit when-not guidance (e.g., use update_ad to change an existing ad), but the creation context is unambiguous.

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

Deploy Server