Skip to main content
Glama

Metadata MCP Connector

List Experiment Ads

list_experiment_ads
Read-only

List the ads inside launched experiments (ad sets), grouped by experiment, with each ad's status in that experiment as the Ads tab shows it, for every channel. Pass experiment_ids (experimentId from search_experiments), campaign_ids, or both (both keeps the given experiments that belong to the given campaigns), and optionally statuses, such as ["PAUSED"] for the ads that are off. status is what the channel last reported: ACTIVE (on), PENDING (on but not serving yet, such as in review, processing or before its start date), PAUSED (off), COMPLETED (ended, or no longer on the channel) or FAILED (the channel reports a problem, such as a disapproval, a deletion or an account hold). An ad switched off inside a running ad set reads PAUSED while the ads still on read ACTIVE. On LinkedIn and Meta a paused or ended ad set or campaign also makes all of its ads read PAUSED or COMPLETED, so compare with the experiment's own status (search_experiments). lastActionReason marks a pause of the ad made in Metadata: MANUAL_PAUSE (by a person) or LOW_PERFORMANCE (by the optimizer); MANUAL_PAUSE_PENDING or LOW_PERFORMANCE_PAUSE_PENDING means the channel has not confirmed that pause yet and the ad may still be running; MANUAL_PAUSE_FAILED means the pause failed and the ad keeps running. An ad with no impressions yet is listed with its own status like any other, so never infer an ad's status from zero impressions. When the call passed no statuses and complete is true, an ad in search_experiments' adIds that is missing here has no status in Metadata: either the channel has not reported it yet or it failed to launch (a SOME_ADS_LAUNCH_FAILED or, on LinkedIn, SOME_CREATIVES_LAUNCH_FAILED issue on the experiment in search_experiments points to the latter, though its absence does not rule a failed launch out), so say so and never report it as running or paused; with statuses, a missing ad may simply be in another status. statusLabel is the Ads tab's chip (Disapproved for an ad Google Ads disapproved, unless it is paused). This is not the library status get_ad_details and search_ads_by_names report. Returns at most 250 ads, newest experiments first; complete=false says some were left out and partial marks an experiment cut short. Read-only.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "list_experiment_ads"
  }
}

Input Schema

NameRequiredDescriptionDefault
statusesNoOptional: only ads in these statuses, such as ["PAUSED"] for the ads that are off, or every status but COMPLETED to leave ended ads out.
campaign_idsNoCampaign IDs (wizCampaignId in search_experiments results): lists the ads of every launched experiment in these campaigns. Up to 20.
experiment_idsNoExperiment (ad set) IDs: experimentId from search_experiments. Up to 50.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A4.3/5.0
Behavior5/5

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

Annotations already cover the safety profile (readOnly, non-destructive, closed-world), yet the description adds substantial behavioral context on top: a 250-ad cap, newest-experiments-first ordering, complete=false/partial truncation flags, and detailed semantics for status and lastActionReason including unconfirmed and failed pauses. It also warns against inferring status from zero impressions or from an ad's absence in the results, which is real operational guidance not encoded anywhere else.

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

Conciseness3/5

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

Every claim is substantive, but it is delivered as one undifferentiated wall of prose that mixes invocation, status taxonomy, pause-reason semantics, and missing-ad inference in a single paragraph. Several status points are restated more than once (paused/off appears in the enum gloss and again in the 'ad switched off inside a running ad set' sentence), and no structure front-loads the parameter guidance.

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?

There is no output schema, so the description must carry return-value semantics, and it does: fields like statusLabel, lastActionReason, partial, and complete are explained. For a tool with no annotations gaps and a fully documented schema, this is close to complete, but the missing-ad rule and the status taxonomy are dense enough that the lack of structure leaves some ambiguity for an agent parsing a large result set.

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?

Schema coverage is 100%, so the baseline is 3; the description still adds meaning by spelling out what each status value denotes (ACTIVE/PENDING/PAUSED/COMPLETED/FAILED) and by characterizing a paused ad set's propagation on LinkedIn and Meta, which helps an agent choose filter values. The 'both' combination rule for experiment_ids and campaign_ids is also clarified beyond the schema text.

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 description opens with a precise verb and resource: 'List the ads inside launched experiments (ad sets), grouped by experiment, with each ad's status.' It also explicitly separates what it reports from what 'get_ad_details and search_ads_by_names report,' so an agent can distinguish it from the look-alike siblings without opening a schema.

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?

It gives clear invocation guidance: pass experiment_ids, campaign_ids, or both, and explains the 'both' case ('keeps the given experiments that belong to the given campaigns'). It also points to where the IDs come from (experimentId in search_experiments) and disclaims the sibling tools' status semantics, but it never states a positive when-to-use condition against those alternatives, so this stops short of a 5.

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.

Resources