PingAura

Get ChatGPT Ads ad insights

get-openai-ads-ad-insights

Read-only

Get insights scoped to a single ad over a date range. Set include_sales for order sales, ROAS, CPA and post-click conversion rate under the given attribution windows.

Input Schema

Name	Required	Description
`sort`	No	Sort directives, an array of {field, direction}. Example: [{"field":"spend","direction":"desc"}].
`ad_id`	Yes	Ad ID
`limit`	No	Max rows to return
`since`	Yes	Range start date (YYYY-MM-DD, inclusive)
`until`	Yes	Range end date (YYYY-MM-DD, inclusive)
`domain_id`	Yes	Domain ID
`time_basis`	No	Whether results are dated by ad_event_time or conversion_time. Defaults to ad_event_time.
`include_sales`	No	Also return conversions, CPA, post-click conversion rate, order sales and ROAS. Defaults to false.
`time_granularity`	No	Time granularity. Defaults to none (single rollup row).
`view_window_days`	No	View-through attribution window in days: 0 (off) or 1. Defaults to 1.
`click_window_days`	No	Click attribution window in days: 7, 14 or 30. Defaults to 30.

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedOct 29, 2026

addedInput schema / properties / click_window_days

Added value: +{
+  "description": "Click attribution window in days: 7, 14 or 30. Defaults to 30.",
+  "enum": [
+    7,
+    14,
+    30
+  ],
+  "type": "number"
+}

addedInput schema / properties / include_sales

Added value: +{
+  "description": "Also return conversions, CPA, post-click conversion rate, order sales and ROAS. Defaults to false.",
+  "type": "boolean"
+}

changedInput schema / properties / sort / items / properties / field / description

Previous value: -"Metric name, e.g. \"spend\", \"clicks\", \"impressions\", \"ctr\", \"cpc\", \"cpm\"."New value: +"Metric to sort by: spend, impressions, clicks, ctr, cpc or cpm. Sales figures, conversions included, cannot be sorted on."

addedInput schema / properties / sort / items / properties / field / enum

Added value: +[
+  "spend",
+  "impressions",
+  "clicks",
+  "ctr",
+  "cpc",
+  "cpm"
+]

removedInput schema / properties / sort / items / properties / field / minLength
```
Removed value: -1
```
addedInput schema / properties / sort / maxItems
```
Added value: +5
```

addedInput schema / properties / time_basis

Added value: +{
+  "description": "Whether results are dated by ad_event_time or conversion_time. Defaults to ad_event_time.",
+  "enum": [
+    "ad_event_time",
+    "conversion_time"
+  ],
+  "type": "string"
+}

addedInput schema / properties / view_window_days

Added value: +{
+  "description": "View-through attribution window in days: 0 (off) or 1. Defaults to 1.",
+  "enum": [
+    0,
+    1
+  ],
+  "type": "number"
+}

First observedOct 24, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnly=true, destructive=false, openWorld=false, so the safety profile is covered. The description adds real context by tying include_sales to order sales, ROAS, CPA and post-click conversion rate and linking it to the attribution windows, but says nothing about row limits, pagination, or result granularity.

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?

Two sentences, front-loaded with the purpose, with the usage-relevant flag named second. Efficient overall, though the second sentence partially restates the include_sales schema description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter analytics tool with no output schema, the description should at least sketch the return shape (per-metric rows, rollup vs daily). It covers purpose and one flag but leaves the response contract to the schema, which only describes inputs.

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%, so the schema already documents all 11 parameters including enum values and defaults. The description adds framing for include_sales and connects it to the window parameters, but does not explain sort, limit, or time_basis beyond what the schema states — baseline 3 is appropriate.

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 insights") plus an explicit scope: a single ad over a date range. That scope distinguishes it from the account-, campaign-, and ad-group-level insight siblings, though none are named.

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?

The single-ad scoping implies when to pick this over the account/campaign/ad-group variants, but there is no explicit when-to-use rule, prerequisite, or named alternative. Usage is inferable rather than stated.

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

All PingAura tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?