X Ads by Get MCP Ads

Overview Schema Source Related Servers Discussions Admin

x ads get campaign reach

x_ads_get_campaign_reach

Read-onlyIdempotent

Fetches reach and average-frequency metrics for specified X Ads campaigns over a date range, so you can measure audience exposure and ad frequency.

Instructions

Get reach and average-frequency metrics for campaigns Native X fields and pagination are preserved; monetary fields ending in _micro are millionths of the account currency.

Input Schema

Name	Required	Description
`end_time`	Yes	ISO 8601 end of the metrics window (exclusive); must be in the past (a future end_time is rejected).
`account_id`	Yes	X Ads account ID from X_ADS_ACCOUNT_IDS.
`start_time`	Yes	ISO 8601 start of the metrics window.
`campaign_ids`	Yes	Comma-separated campaign IDs to fetch reach for (max 20).

Output Schema

Name	Required	Description	Default
`result`	Yes	Original tool result: parsed JSON when the text is JSON, otherwise the text or multiple MCP content blocks. Provider fields depend on the selected query.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv1.1.1Oct 30, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "properties": {},
-    "type": "object"
-  },
-  {
-    "items": {},
-    "type": "array"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "number"
-  },
-  {
-    "type": "boolean"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  {
+    "items": {},
+    "type": "array"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "boolean"
+  },
+  {
+    "type": "null"
+  }
+]

First observedv1.0.1Sep 23, 2026

TDQS

B3.2/5.0

Behavior3/5

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so the safety profile is covered. The description adds real value with the _micro currency-unit convention and the note that native X fields and pagination are preserved, but it says nothing about how reach is computed, rate limits, or cardinality of results.

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 is front-loaded in the first clause and the total length is two sentences. The second sentence is awkwardly spliced (missing punctuation between "campaigns" and "Native X fields"), which slightly hurts readability.

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, so return values need not be explained, and the schema fully documents all four required parameters. The description covers purpose plus data-format conventions; only the semantics of "reach" and any result-size expectations are left implicit.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema itself documents the ISO 8601 window, the 20-campaign cap, and the past-only end_time rule. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Get reach and average-frequency metrics for campaigns"), which clearly separates it from entity-fetch siblings like x_ads_get_campaign and aggregate siblings like x_ads_get_account_stats. It does not explicitly name an alternative, so it falls short of a 5.

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

Usage Guidelines2/5

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

There is no statement of when to use this tool versus x_ads_get_campaign, x_ads_get_account_stats, or x_ads_get_line_item, and no prerequisites or exclusions beyond what the schema implies. The second sentence covers data conventions, not usage selection.

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