Skip to main content
Glama

Honeyfield Marketing MCP

OpenAI Ads (Beta): Insights

openai_ads_insights
Read-only

BETA — Leistungszahlen der OpenAI-Ads-Anzeigen (ChatGPT) je Kampagne, Anzeigengruppe oder Anzeige, plus Summe (total). Je Zeile: id, name, impressions, clicks, spend (Kontowährung), ctr_pct, cpc, conversions (Ziel-Conversions: Klick 30 Tage + View 1 Tag; nur mit verknüpftem Conversion-Ereignis, sonst 0). total rechnet ctr_pct, cpc und cost_per_conversion aus den Summen. level: campaign (Standard), ad_group oder ad. days: die letzten N vollen Tage bis gestern; date_from/date_to ('YYYY-MM-DD', inklusiv, Tage in der Zeitzone des Werbekontos) gehen vor, max. 365 Tage. date_to = heute ist möglich, aber die Kosten des laufenden Tages verbucht OpenAI verzögert (oft 0) — CPC und Kosten je Conversion sind dann zu niedrig. daily: true = eine Zeile je Tag (Feld date). campaign_ids: optional nur diese Kampagnen. workspace: Slug des Kunden-Workspace (optional bei nur einem Workspace).

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "openai_ads_insights"
  }
}

Input Schema

NameRequiredDescriptionDefault
daysNo
dailyNo
levelNocampaign
date_toNo
date_fromNo
workspaceNo
campaign_idsNo

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the readOnlyHint/openWorldHint annotations, the description discloses important behavior: conversions use a click-30-day + view-1-day window and read 0 unless a conversion event is linked, and the total row derives ctr_pct, cpc and cost_per_conversion from summed values rather than averaging. The caveat about delayed same-day spend is exactly the kind of operational nuance annotations cannot convey.

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?

It is front-loaded with the purpose and then organized parameter-by-parameter, with essentially no filler. It is somewhat dense and repeats the returned column list even though an output schema exists, which is a minor redundancy rather than bloat.

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?

For a 7-parameter, zero-coverage read tool with annotations and an output schema, nothing an agent needs is missing: granularity, time window semantics, filtering, workspace resolution and the same-day data caveat are all covered.

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

Parameters5/5

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

Schema description coverage is 0%, so the description carries the full burden and does it: level enumerates campaign/ad_group/ad with its default, days means the last N full days ending yesterday, date_from/date_to are inclusive YYYY-MM-DD in the ad account timezone with a 365-day cap, daily toggles per-day rows via a date field, and workspace is optional for single-workspace accounts.

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

Purpose5/5

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

The description names a specific verb+resource: performance metrics ('Leistungszahlen') for OpenAI Ads at campaign, ad group or ad granularity, plus an aggregated total row. It even enumerates the returned metrics, so an agent can tell this is the reporting tool rather than a listing tool like openai_ads_list_campaigns or a mutation like openai_ads_update_campaign.

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

Usage Guidelines4/5

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

It states defaults (level=campaign, days=30), that date_from/date_to override days, and that campaign_ids optionally narrows scope, which gives clear context for invocation. It also warns that date_to=today yields under-reported cost/CPC. It does not explicitly exclude scenarios or point to a sibling, but within the openai_ads family there is no competing insights tool, so the guidance is adequate.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources