adhistory-mcp

Overview Schema Source Related Servers Discussions Admin

Competitor Google ads (Ads Transparency Center)

competitor_google_ads

Read-onlyIdempotent

Retrieve a company's Google ads from the Transparency Center to see ad formats, headlines, run dates, and platforms. Use advertiserCheck mode to qualify domains by ad activity.

Instructions

Get the ads a company or domain runs on Google (Search, YouTube, Shopping, Maps, Play, Display), read from the public Google Ads Transparency Center. Each item is one ad: advertiser name, format (text/image/video), headline and description for text ads, first and last shown dates, days running, per-country regions and platforms, and the Transparency Center link. Newest ads first; long-running ads are the proven ones. mode='advertiserCheck' returns one row per domain instead (advertises on Google yes/no, estimated ad count, live now, last ad date), useful to qualify a list of companies. Google does not publish spend or keywords. Cost: $1.00 per 1,000 results (an ad, or a checked domain) on the user's Apify account; the default 20 ads cost about $0.02. Latency: usually 20-90 s, up to 5 min for large requests.

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

Input Schema

Name	Required	Description	Default
`mode`	No	'ads' lists ads; 'advertiserCheck' returns one summary row per domain.	ads
`country`	No	Only ads shown in this country. ANY = all countries.	ANY
`date_to`	No	Optional end date, YYYY-MM-DD.
`domains`	No	Advertiser websites, e.g. ['hubspot.com']. URLs are fine.
`platform`	No	Only ads shown on this Google platform.	all
`ad_format`	No	text = Google Search ads; image and video cover Display and YouTube.	all
`date_from`	No	Optional start date, YYYY-MM-DD.
`company_names`	No	Company names to look up in the Transparency Center; the best match is used.
`advertiser_ids`	No	Transparency Center advertiser IDs (start with AR).
`only_active_ads`	No	Keep only ads shown in the last 3 days.
`max_ads_per_advertiser`	No	Newest ads first. Raise to reach older long-running ads.

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.4.0Nov 9, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds operating context annotations cannot express: per-result cost ($1.00 per 1,000 results, ~$0.02 for the default 20), latency (20-90 s, up to 5 min for large requests), and result ordering (newest first). It also discloses a data limitation (no spend or keywords) and a heuristic ('long-running ads are the proven ones') that shapes how an agent should interpret results.

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

Conciseness5/5

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

The identity of the tool and its output shape come first, then the alternative mode, then constraints (what Google does not publish) and finally cost and latency. Sentences are dense but every one carries distinct information — no restatement of the schema and no 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?

An output schema exists and the description still summarizes the result fields, plus it covers cost, latency, ordering, and mode semantics — sufficient for an 11-parameter tool with all-optional inputs. Minor gaps remain: it does not say what happens if both domains and company_names are supplied, nor that the account/billing context is required for the stated cost. These are small relative to what is covered.

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 description coverage is 100%, so the baseline is 3; the description still adds interpretation. It explains that raising max_ads_per_advertiser is what reaches older long-running ads because results are newest-first, and clarifies that 'advertiserCheck' collapses output to one row per domain rather than per ad. That meaning is not recoverable from the schema's per-field descriptions alone.

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 the ads a company or domain runs on Google') and enumerates the surfaces covered (Search, YouTube, Shopping, Maps, Play, Display). It also enumerates exactly what one result item contains and distinguishes the two operating modes, so an agent knows what it will get before invoking. No sibling tool covers ad intelligence, so there is no ambiguity to resolve.

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 mode-selection guidance: mode='advertiserCheck' is 'useful to qualify a list of companies', implying 'ads' mode is for per-creative inspection. It also sets a boundary by stating 'Google does not publish spend or keywords', which tells the agent when this tool cannot answer a question. It stops short of naming a substitute tool or stating hard exclusions, so it is strong but not complete.

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

Deploy Server