Meta Ads by Get MCP Ads

meta get insights

meta_get_insights

Read-onlyIdempotent

Query Meta Ads performance insights across 170+ metrics and 43+ breakdowns, automatically splitting incompatible combinations into multiple requests and merging results.

Instructions

Query Meta Ads performance insights. Supports 170+ metrics, 43+ breakdowns with intelligent query planning. Use meta://metrics resource to see available metrics. Use meta://breakdowns for available breakdowns. The query planner automatically splits incompatible metric/breakdown combinations into multiple API requests and merges results. For purchases, leads or conversion analysis, request actions (and action_values for revenue) or explicit metrics such as purchases, omni_purchases or leads. The native conversions field is not a universal conversion total, and its absence does not mean purchases or leads are unavailable. Label the exact action_type and never sum overlapping purchase types.

Input Schema

Name	Required	Description	Default
`adIds`	No	Restrict ad-level insights to these ad IDs.
`level`	Yes	Aggregation level: account, campaign, adset, or ad
`limit`	No	Maximum number of returned items or rows. The declared bounds and default apply; use pagination for additional results.
`metrics`	Yes	Metric keys from meta://metrics (e.g., impressions, spend, ctr)
`adsetIds`	No	Restrict adset- or ad-level insights to these ad set IDs.
`timeRange`	No	Custom date range with since/until in YYYY-MM-DD format
`breakdowns`	No	Breakdown keys from meta://breakdowns (e.g., age, gender, country)
`datePreset`	No	Predefined date range (e.g., last_7d, last_30d)
`dimensions`	No	Dimension keys listed in meta://compatibility. Entity metadata, such as names, statuses and budgets, is read at its current value.
`adAccountId`	Yes	Ad account ID (e.g., act_123456789)
`campaignIds`	No	Restrict campaign-, adset- or ad-level insights to these campaign IDs.
`timeIncrement`	No	Time granularity: 1 (daily), 7 (weekly), 'monthly', or 'all_days'
`attributionMode`	No	Use Meta account settings, ad-set settings, or explicitly supplied windows. No setting is inferred from returned numbers.	account
`effectiveStatus`	No	Keep only entities with this native effective status at the selected level.
`actionBreakdowns`	No	Native action breakdowns such as action_type. Only for action metrics.
`actionReportTime`	No	Date basis for actions, sent explicitly to Meta.	impression
`attributionWindows`	No	Only with attributionMode explicit. These windows are sent identically to every split query and account total.
`includeAccountTotals`	No	Also read native account-level totals with the same dates, metrics and attribution. Requires no entity filter, dimension or breakdown.

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.

Changed9 schema fields changedv2.1.1Oct 30, 2026

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

addedInput schema / properties / actionBreakdowns

Added value: +{
+  "description": "Native action breakdowns such as action_type. Only for action metrics.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

addedInput schema / properties / adsetIds

Added value: +{
+  "description": "Restrict adset- or ad-level insights to these ad set IDs.",
+  "items": {
+    "pattern": "^\\d+$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / campaignIds

Added value: +{
+  "description": "Restrict campaign-, adset- or ad-level insights to these campaign IDs.",
+  "items": {
+    "pattern": "^\\d+$",
+    "type": "string"
+  },
+  "maxItems": 100,
+  "minItems": 1,
+  "type": "array"
+}

addedInput schema / properties / dimensions

Added value: +{
+  "description": "Dimension keys listed in meta://compatibility. Entity metadata, such as names, statuses and budgets, is read at its current value.",
+  "items": {
+    "type": "string"
+  },
+  "maxItems": 100,
+  "type": "array"
+}

addedInput schema / properties / effectiveStatus

Added value: +{
+  "description": "Keep only entities with this native effective status at the selected level.",
+  "enum": [
+    "ACTIVE",
+    "PAUSED"
+  ],
+  "type": "string"
+}

changedInput schema / properties / includeAccountTotals / description

Previous value: -"Also read native account-level totals with the same dates, metrics and attribution. Requires no adIds or breakdowns."New value: +"Also read native account-level totals with the same dates, metrics and attribution. Requires no entity filter, dimension or breakdown."

removedInput schema / properties / timeRange / 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 observedv2.0.1Sep 23, 2026

TDQS

A3.8/5.0

Behavior4/5

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

Beyond the read-only annotations, the description discloses important behavior: the query planner splits incompatible metric/breakdown combinations into multiple API requests and merges results. It also warns about conversion semantics and overlapping purchase types, though it does not cover rate limits or error behavior.

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?

The description is front-loaded with purpose and resource pointers, and every sentence provides useful context. It is slightly dense and repeats the query-planning idea, but it avoids unnecessary 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?

For an 18-parameter insights tool with annotations and an output schema, the description covers the most important behavioral and query-semantic context. It is not fully complete because it omits explicit sibling routing and some operational caveats.

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 schema documents parameters well. The description adds meaningful semantics beyond the schema by explaining metric/breakdown resources, conversion analysis behavior, action_type labeling, and the pitfalls of the native conversions field.

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?

The description states a specific verb and resource: query Meta Ads performance insights, including metrics/breakdown support. It is clear about what the tool does, but it does not explicitly distinguish itself from the sibling meta_get_insights_raw.

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

Usage Guidelines3/5

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

It gives implied usage guidance by pointing to meta://metrics and meta://breakdowns and by explaining how to handle purchases/leads/conversion analysis. However, it does not state when to use this tool versus alternatives such as meta_get_insights_raw or meta_validate_query.

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

Deploy Server