Tool Reference

The Adthena MCP server exposes 20 tools organized by domain. All tools are read-only — they query data but never modify anything in your Adthena account, Google Ads campaigns, or any other system.

Tools

Tool	Description	Report Types
`list_accessible_accounts`	List all Adthena accounts you have access to	—
`get_market_share`	Competitor performance: clicks, spend, impressions, position	`detail`, `groups_and_locations`, `summary`
`get_market_trends`	Competitor performance trends over time	—
`get_competitor_trends`	Unique competitor count trends over time	—
`get_competitor_overlap`	Search term overlap between you and competitors	—
`get_search_terms`	Search term analysis and opportunity discovery	`detail`, `detail_summary`, `opportunities`, `opportunities_summary`
`get_ads`	Most frequent ad copies and product listing ads	Text (`ad_format="text"`) or PLA (`ad_format="pla"`)
`get_ai_overview`	AI Overview appearance metrics and affected search terms	`overview`, `search_terms`
`get_ai_overview_content`	AI Overview citation analysis: sentiment, themes, competitor citations (premium)	`content`, `competitors`
`get_ai_overview_impact`	AI Overview CTR/CPC impact with frequency breakdown (premium)	`impact`, `search_terms`
`get_llm_performance`	LLM domain citation trends and per-domain performance scores	`domain_trends`, `domain_performance`
`get_llm_prompts`	List LLM prompts and prompt groups configured for an account	`prompt_groups`, `prompts`
`get_llm_prompt_metrics`	LLM prompt-level citation counts, health status, and brand mentions	`prompt_groups`, `prompts`
`get_ai_ads_intelligence`	AI Ads Intelligence — brand and competitor presence in LLM paid ad placements (ChatGPT, Google AI)	`performance_trends`, `advertiser_share_trends`, `prompts_analysis`
`get_serp_tracker`	SERP Tracker rule matches (formerly Infringement Tracker) — ads on the SERP that triggered a configured rule. Rule matches, not legal infringements	`matches`, `summary`, `rules`
`get_auto_takedown`	Adthena-detected trademark cases — the inputs to Google's Auto-Takedown system. For enforcement outcomes use `get_trademark_takedowns`	`matches`, `summary`, `rules`
`get_ad_hijacking`	Ad hijacking and affiliate fraud detection	`configurations`, `incidents`, `summary`
`get_brand_activator`	Automated bid management activity and cost savings	`activity_log`, `daily_savings`, `daily_savings_summary`
`get_trademark_takedowns`	Google trademark auto-takedown enforcement outcomes	`detail`, `summary`
`get_account_settings`	Account configuration: locations, groups, metrics	`locations`, `search_term_groups`, `search_term_groups_metrics`

Common Parameters

Most tools accept these parameters:

Parameter	Description
`account_id`	Required. Your Adthena account ID (from `list_accessible_accounts`).
`start_date` / `end_date`	Date range in `YYYY-MM-DD` format. Data is available up to yesterday.
`device`	List of `"desktop"` and/or `"mobile"`.
`report_type`	Selects between detail, summary, and other sub-views.
`page` / `page_size`	Pagination. Default page size is 50, max 1000. Use `page_size=0` to return all results.

Common Filters

Filter	Description
`search_term` / `excluded_search_term`	Filter by search term text (substring match).
`search_term_group` / `excluded_search_term_group`	Filter by user-defined search term group.
`competitor` / `excluded_competitor`	Filter by competitor domain.
`competitor_group` / `excluded_competitor_group`	Filter by user-defined competitor group.
`location`	Filter by geographic location.
`adwords_campaign` / `excluded_adwords_campaign`	Filter by Google Ads campaign name.
`ad_type`	`"textad"`, `"pla"`, or `"organic"`.
`segment_by`	Controls data grouping: `["device"]`, `["ad_type"]`, or both.

LLM Parameters

The LLM tools fall into two surfaces with different engine sets:

Organic citations (get_llm_performance, get_llm_prompts, get_llm_prompt_metrics) — tracks brand citations in LLM responses on ChatGPT and Perplexity.
Paid ad placements (get_ai_ads_intelligence) — tracks paid ad detections in LLM responses on ChatGPT and Google AI.

Both surfaces use prompt-based filtering only — no search/competitor/device filters.

Parameter	Description
`engine`	Organic tools: `"chatgpt"` and/or `"perplexity"` (default both). AI Ads Intelligence: `"chatgpt"` and/or `"googleai"` (default both).
`segment_by`	`["engine"]` to split results per LLM engine. Default aggregates engines into a comma-joined label. `get_llm_prompt_metrics(report_type="prompts")` always segments by engine; `get_ai_ads_intelligence(report_type="prompts_analysis")` ignores `segment_by`.
`prompt` / `excluded_prompt`	Filter by prompt text.
`prompt_group` / `excluded_prompt_group`	Filter by prompt group name.
`location`	Filter by geographic location.
`max_number_of_domains`	Top domains/competitors per bucket. `get_llm_performance(domain_trends)` default 10; `get_ai_ads_intelligence(advertiser_share_trends)` default 5 — brand row always included in addition.
`primary_dimension`	`get_llm_performance(domain_trends)` only: `"frequency"` or `"average_position"`.
`prompt_status`	`get_ai_ads_intelligence(prompts_analysis)` only: `"with_brand_ads"`, `"gap"`, or `"all"` (default).

LLM tools do NOT support search/competitor filters

These endpoints use prompt-based filtering only. Parameters like device, ad_type, search_term, competitor, adwords_campaign, and is_whole_market are not available.

How to read AI Ads Intelligence responses

get_ai_ads_intelligence distinguishes between several "absence" states that look similar but mean different things. Reading them correctly is essential — getting it wrong leads to opposite conclusions.

The API never returns JSON null. Undefined values are omitted from the response (the key is absent from the object), never serialized as null. To detect "undefined", check whether the key is present in the JSON, not whether its value is null.

ad_presence_rate is always present and numeric (period-level and per-day in time_series). The DAO zero-fills buckets with no data and substitutes 0 for any undefined value, so a 0 is ambiguous — it can mean "no scrapes occurred" OR "scrapes occurred but the brand was not detected". Use the total_prompts field at the same level to disambiguate (never cross levels):
- Period level: each segment carries a period-wide total_prompts. total_prompts > 0 ⇒ scrapes occurred during the period ⇒ ad_presence_rate = 0 is a real "brand absent" signal. total_prompts = 0 ⇒ no scrapes ⇒ no signal.
- Per-day level: each time_series point carries its own total_prompts (distinct prompts scraped that day). Same rule: total_prompts > 0 that day ⇒ rate of 0 means the brand was absent that day; total_prompts = 0 that day ⇒ no scrapes that day, no signal.
- Never recommend action ("the brand is invisible here, push a campaign") based on ad_presence_rate = 0 alone — always check the matching total_prompts first.
- prompts_analysis has no such ambiguity — the SQL HAVING clause guarantees every returned row has scrapes. Absent your_ads_detection_rate is a definitive "brand absent" signal there.
Period-level rate fields that may be omitted. Absence is a meaningful signal — it tells you which entity is missing from the data, not "data unavailable". The rate would have been 0 had it been emitted.
- your_ads_detection_rate (prompts_analysis): absent ↔ the brand had zero detections on that prompt.
- top_competitor_rate, avg_competitor_detection_rate (prompts_analysis), top_competitor_detection_rate (performance_trends): absent ↔ no competitors were detected.
- you_vs_top_competitor_rate: absent ↔ either the brand or the competitors are absent (or both).
share_of_ads is always present (period and daily). Advertisers with zero detections in the period don't appear in the response at all — including the brand. If a brand row is missing from advertiser_share_trends, the brand had no detections in that bucket.
top_competitor key omitted → no competitors were detected in that bucket / on that prompt. Interpret as "uncontested", not "missing data".
Gap prompt → in prompts_analysis, a row with your_ads_detection_rate absent AND competitors_count > 0. Brand had zero detections; competitors did.
Greenfield prompt → is_greenfield: true is set explicitly, and top_competitor is absent. Brand has detections AND no competitors were detected. Highest-priority targets.
is_greenfield is always present (boolean).
competitors entry with domain: "" → the source data has no domain for that advertiser. The name is still authoritative; do not interpret as missing data.
Zero-fill guarantee → every requested (engine, location) bucket is always emitted, and every day in [start_date, end_date] appears in each time_series. An empty time_series or a date gap would be a bug.
engine field shape → with segment_by=[] the engine field is a sorted comma-joined label like "chatgpt, googleai" (the aggregated bucket). With segment_by=["engine"] it is a single engine name.
No prior-period deltas are computed server-side — call the tool twice with adjacent date ranges and diff client-side.

Safety Annotations

Every tool includes MCP safety annotations. All tools use identical annotations because the entire server is read-only:

Annotation	Value	Meaning
`readOnlyHint`	`true`	The tool only reads data — it does not modify anything.
`destructiveHint`	`false`	The tool cannot delete or destructively modify data.
`idempotentHint`	`true`	Calling the tool multiple times with the same parameters returns the same result.
`openWorldHint`	`true`	The tool interacts with external systems (the Adthena API).

This applies to all 20 tools. The annotations are enforced in the source code and verified by automated tests.

Resources

The server also provides 5 read-only MCP resources that give the client context about your account and the data model:

Resource	URI	Description
Quick Reference	`docs://quick-reference`	Question-to-tool mapping table — read first to find the right tool.
Concepts	`docs://concepts`	Core Adthena concepts and metric definitions (share, position, count metrics).
Workflows	`docs://workflows`	Step-by-step workflows for 9 common analysis patterns.
Date Rules	`docs://date-rules`	Date handling rules, time period auto-resolution, and data alignment.
Data Access	`docs://data-access`	Pagination modes, segmentation (segment_by), and filtering options.

Data Limits

Constraint	Details
AI Overview	`start_date` must be on or after `2025-07-31`
AI Overview Content / Impact	`start_date` must be within the last 30 days
Brand Activator activity_log	Limited to the last 60 days (savings endpoints have no date restriction)
Search Term Opportunities	Limited to the last 30 days
LLM Performance / Prompt Metrics / AI Ads Intelligence	`start_date` must be within the last 30 days
LLM Prompts (listing)	No date range required — lists account configuration
Pagination	Max `page_size` is 1000. Use `page_size=0` for all results (streamed).
Time periods	Auto-calculated: daily (last 30 days), weekly (last 13 months), monthly (older).