Skip to main content
Glama
Reddit Ads MCP server

Reddit Ads MCP server

by get-mcp-ads

reddit get insights

reddit_get_insights
Read-onlyIdempotent

Retrieve Reddit Ads performance insights with native metrics, entity and audience breakdowns, pagination, and explicit UTC date ranges for campaign analysis.

Instructions

Native Reddit reporting with metrics and entity/audience breakdowns, explicit UTC dates and pagination. Empty results validate transport only. Reported audience demographics differ from configured targeting.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "adAccountId": "<adAccountId>",
      "startsAt": "<startsAt>",
      "endsAt": "<endsAt>",
      "fields": "<fields>"
    },
    "name": "reddit_get_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoItems per page, 1 to 100. Defaults to 50.
cursorNoOpaque next_cursor returned by the previous page. Omit it for the first page.
endsAtYesReport end in UTC on the hour, after startsAt. Hourly breakdowns cover at most seven days.
fieldsYesNative Reddit field names, e.g. IMPRESSIONS, CLICKS, SPEND, CONVERSION_SIGN_UP_CLICKS, CONVERSION_SIGN_UP_VIEWS. Use reddit_get_reporting_schema for supported fields; never guess names. Lowercase spellings are accepted.
filterNoOptional native Reddit report filter expression, passed unchanged.
startsAtYesReport start in UTC on the hour, such as 2026-10-01T00:00:00Z.
breakdownsNoNative breakdowns, e.g. CAMPAIGN_ID, AD_GROUP_ID or AD_ID. At most three. Lowercase spellings are accepted. API compatibility constraints still apply.
adAccountIdYesReddit ad account ID (a2_...) listed in REDDIT_ADS_ACCOUNT_IDS, not the business ID.

Output Schema

NameRequiredDescriptionDefault
resultYesOriginal 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.

  1. Changed2 schema fields changedv1.0.1
    • 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"
      +  }
      +]
  2. First observedv1.0.0

TDQS

A3.6/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety bar is low, and the description adds genuinely useful behavioral caveats: empty result sets only prove transport worked, and reported audience demographics diverge from configured targeting. Those are data-interpretation warnings an agent cannot get from the annotations. It still omits rate limits, permission requirements, and pagination termination 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?

Three short sentences, front-loaded with the primary capability, with no filler. The telegraphic phrasing ('Empty results validate transport only') is dense but each sentence carries distinct information.

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?

An output schema exists, annotations carry the safety profile, and all 8 parameters are described in-schema, so the description only needs to supply the traps: UTC-only hour-aligned windows implied, empty-result semantics, and the demographic-vs-targeting discrepancy. It covers exactly those gaps for a read-only reporting tool.

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 coverage is 100%, so every parameter including limit, cursor, startsAt/endsAt and breakdowns is already documented at the field level. The description only echoes 'explicit UTC dates and pagination' without adding format constraints or the alternating/conjunctive rules for breakdown combinations. Baseline 3 applies when the schema does the heavy lifting.

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 resource and scope: native Reddit reporting producing metrics with entity/audience breakdowns, UTC date ranges and pagination. That clearly separates it from the entity-lookup siblings (reddit_get_campaigns, reddit_get_ads), though it never names another reporting/reference tool explicitly.

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?

No sentence says when to reach for this tool versus reddit_get_reporting_schema (which the schema itself points to) or the campaign/ad-group lookup tools. The only conditional guidance is interpretive ('Empty results validate transport only'), which explains a result state rather than directing tool selection.

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