Skip to main content
Glama
Google Ads Transparency

Google Ads Transparency

get_ads_with_copy

Retrieve Google ads with ad copy—headlines, descriptions, display URLs, countries, including screenshot-only text ads—to analyze advertiser messaging.

Instructions

Get Google ads WITH their ad copy (headline, description, display URL), including text ads that Google stores only as screenshots, plus the countries each ad ran in.

Runs the hosted Apify Actor "datalume/google-ads-transparency-scraper" with your own
Apify account. Requires the APIFY_TOKEN environment variable. It is PAID per result
(about $0.002 per ad, $0.0035 per ad with copy on Apify's free plan; failed rows are free).
The run stops at max_total_charge_usd. Prefer list_ads when the ad text is not needed.

Args:
    domains: advertiser websites, e.g. ["booking.com"].
    advertiser_names: advertiser names to look up, e.g. ["Samsung Electronics"].
    region: 2-letter country code (e.g. "US") or "anywhere".
    platform: "all", "search", "youtube", "shopping", "maps" or "play".
    ad_format: "all", "text", "image" or "video".
    min_days_running: keep ads shown on at least this many days.
    sort_by: "recentlyShown", "longestRunning" or "newest".
    max_ads_per_target: maximum ads per domain or name (keep small to control cost).
    max_total_charge_usd: hard spending cap for this call, in USD.

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": "get_ads_with_copy"
  }
}

Input Schema

NameRequiredDescriptionDefault
regionNoanywhere
domainsNo
sort_byNorecentlyShown
platformNoall
ad_formatNoall
advertiser_namesNo
min_days_runningNo
max_ads_per_targetNo
max_total_charge_usdNo

Output Schema

NameRequiredDescriptionDefault
resultYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.7/5.0
Behavior4/5

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

With no annotations, the description carries the full disclosure burden and does well: it names the hosted Actor, the required APIFY_TOKEN, that the call is PAID per result with concrete per-ad prices, that failed rows are free, and that spending is hard-capped at max_total_charge_usd. It stops short of describing rate limits or the result shape, though an output schema exists to cover returns.

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?

Purpose, then cost/auth caveats, then a clean Args list — front-loaded and skimmable with no filler sentences. The Args block is long, but every line compensates for an undocumented schema field, so the length is justified rather than redundant.

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

Completeness5/5

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

For a nine-parameter paid scraping call, the definition covers the three things an agent must know before invoking: cost model and cap, credential requirement, and the meaning of every argument. Return-value explanation is unnecessary because an output schema is supplied.

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

Parameters5/5

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

Schema coverage is 0% and the schema supplies no enums, yet the Args block defines all nine parameters with examples ('booking.com', 'Samsung Electronics'), allowed values for region, platform, ad_format and sort_by, and the cost-control semantics of max_ads_per_target and max_total_charge_usd. This is meaning the structured fields do not provide anywhere.

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 ('Get Google ads WITH their ad copy') and enumerates the distinguishing payload: headline, description, display URL, screenshot-only text ads, and countries per ad. It also explicitly contrasts itself with the sibling, so an agent can pick it over list_ads without opening either schema.

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

Usage Guidelines5/5

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

Gives an explicit routing rule: 'Prefer list_ads when the ad text is not needed', which names the alternative and the condition that selects it. It adds a second usage constraint in the cost/charge-cap guidance, telling the agent to keep max_ads_per_target small to control spend.

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