Aller au contenu principal
OrbiAds logo — infrastructure AdOps IA pour Google Ad Manager OrbiAds
OrbiAds logo — infrastructure AdOps IA pour Google Ad Manager
Login
GitHub
Reporting docs

MCP skills

Customize reporting skills for Claude, Codex and MCP

Use a skill when the same reporting question comes back every day. The skill should lock the allowed MCP actions, the exact dimensions and metrics, the output format and the guardrails that keep the agent honest.

What a reporting skill should contain

A good skill is not a generic prompt. It is a small operating contract for an agent: which MCP functions are allowed, which GAM fields are valid, what JSON or prose shape is expected, and which actions are forbidden.

Allowed actions

MCP functions + scope

Field contract

Dimensions + metrics

Output contract

JSON, CSV, or summary

Internal linking map

Each skill should link back to the field catalogue and to the exact use case page. This gives readers a learning path and gives search engines a clean reporting cluster.

Claude Cowork

Daily GAM readout skill

For a morning AdOps brief that explains delivery, revenue, fill issues and actions without opening a spreadsheet first.

Open technical use case Read Academy guide

User prompt

Claude, run yesterday GAM report by DATE, ADVERTISER_NAME, ORDER_NAME, LINE_ITEM_NAME and AD_UNIT_NAME. Include AD_SERVER_IMPRESSIONS, AD_SERVER_CLICKS, AD_SERVER_CTR, AD_SERVER_REVENUE, AD_REQUESTS, FILL_RATE and UNFILLED_IMPRESSIONS. Summarize anomalies and give me the resultId.

Skill instructions

Allowed MCP actions: get_report_dimensions, get_report_metrics, run_custom_report, get_report_result, export_report_csv. Default api=rest. Use api=soap only when the field reference says REST is unavailable. Return a human summary, an action list and the cached resultId.

Allowed MCP functions

get_report_dimensionsget_report_metricsrun_custom_reportget_report_resultexport_report_csv

Field references

Representative output

  • Yesterday: 1,284,220 impressions, EUR 4,862 revenue, CTR 0.42%, fill rate 91.8%.
  • Watch: LI-8241 is 18% below its 7-day average on AD_UNIT_NAME=Sports/Home.
  • Action: inspect creative rotation before noon; full resultId rep_20260609_daily.

Guardrails

  • Do not invent fields. Validate uncertain field names with get_report_dimensions or get_report_metrics.
  • Use GAM REST for all reporting here; linked Analytics fields are optional GAM columns only when the link is active.

Codex

Unsold inventory triage skill

For ranking ad units where demand exists but fill or monetization is leaking.

Open technical use case Read Academy guide

User prompt

Codex, find unsold inventory for the last 7 days by DATE, AD_UNIT_NAME, AD_UNIT_CODE and DEVICE_CATEGORY_NAME. Use AD_REQUESTS, AD_SERVER_IMPRESSIONS, UNFILLED_IMPRESSIONS and FILL_RATE. Rank by estimated lost revenue and export CSV if there are more than 20 rows.

Skill instructions

Use run_custom_report for the full REST report. fetch_inventory_report is allowed only as a quick ad-unit inventory view, not as the source for all unsold metrics. Always keep AD_REQUESTS next to UNFILLED_IMPRESSIONS so traffic loss is not confused with no-fill.

Allowed MCP functions

get_report_metricsrun_custom_reportget_report_resultexport_report_csvfetch_inventory_report

Field references

Representative output

  • Sports/Homepage | 184,210 ad requests | 52,440 unfilled | fill rate 71.5% | est. lost revenue EUR 1,126.
  • Root cause hypothesis: demand or size coverage issue, not traffic loss.
  • Action: check demand filters, price floor and bidder sizes before changing trafficking.

Guardrails

  • Do not call GA4 or Google Ads APIs for this workflow.
  • Do not optimize price floors from one day of data; compare yesterday, 7 days and same weekday.

Codex

Line item forecast guardrail skill

For checking whether a planned line item is likely to deliver before Codex or a user mutates GAM.

Open technical use case Read Academy guide

User prompt

Codex, run a standalone forecast for a planned STANDARD line item: France, Homepage ad units, sizes 300x250 and 728x90, goal 500000 impressions, priority 8, frequency cap 3 per day. Return availableUnits, matchedUnits, possibleUnits, riskLevel and the targeting constraint to relax.

Skill instructions

Use forecast functions, not run_custom_report, because future availability is not a historical reporting metric. Do not create, update or reserve the line item. Return a decision: safe, review, or unsafe.

Allowed MCP functions

get_standalone_forecastget_delivery_forecast_by_line_itemget_prospective_delivery_forecast

Field references

Dimensions

lineItemType=STANDARDadUnitIdscreativePlaceholdersgeoTargetingfrequencyCaps

Metrics

availableUnitsmatchedUnitspossibleUnitsriskLevel

Representative output

  • Forecast: 612,400 availableUnits for a 500,000 goal, matchedUnits 544,900, riskLevel=LOW.
  • Constraint to watch: Homepage + France + frequency cap 3/day reduces possibleUnits by 21%.
  • Decision: safe to review with sales, regenerate before booking.

Guardrails

  • Forecast is a planning estimate, not a delivery guarantee.
  • For existing line items, use get_delivery_forecast_by_line_item instead of standalone inputs.

Codex / LLM JSON

Order and key-value forecast JSON skill

For returning a replayable JSON forecast that combines GAM order context, resolved custom targeting IDs and availability numbers.

Open technical use case Read Academy guide

User prompt

Codex, produce only a forecastDecision JSON for order OR-2026-SUMMER: resolve the order, resolve audience=sports and hb_pb=20 to keyId/valueIds, forecast Homepage/Sports ad units from 2026-07-01 to 2026-07-31 for 500000 impressions, sizes 300x250 and 728x90, priority 8, frequency cap 3 per day.

Skill instructions

Allowed MCP actions: orders list/get, targeting search_custom_targeting/get_custom_targeting_values, reporting get_standalone_forecast/get_delivery_forecast_by_line_item/get_prospective_delivery_forecast. Resolve IDs before forecasting. Return JSON only, no prose. Forecast is not a HISTORICAL REST report.

Allowed MCP functions

list_ordersget_ordersearch_custom_targetingget_custom_targeting_valuesget_standalone_forecastget_delivery_forecast_by_line_itemget_prospective_delivery_forecast

Field references

Metrics

availableUnitsmatchedUnitsutilizationPercentriskLevel

Representative output

  • {"order":{"id":"9482","name":"OR-2026-SUMMER","status":"DRAFT","advertiserId":"7712"},"targeting":{"adUnitIds":["1234567","1234568"],"keyValues":[{"keyId":1871,"valueIds":[9912]},{"keyId":2450,"valueIds":[3301]}]}}
  • {"forecast":{"availableUnits":612400,"matchedUnits":544900,"utilizationPercent":81.6,"contendingLineItems":[{"lineItemId":"90031","priority":6}]}}
  • {"decision":{"riskLevel":"LOW","status":"safe_to_review","relaxFirst":null,"nextAction":"regenerate_before_booking"}}

Guardrails

  • Do not create, update, approve or reserve the order from this skill.
  • Do not forecast with raw key-value names; resolve IDs first.
  • Keep JSON keys stable so downstream LLM prompts can validate required fields.

GAM REST / liens actifs

Linked GAM REST fields skill

For reporting on Analytics, AdSense or Ad Exchange fields exposed by Google Ad Manager when the link or source is active in GAM.

Open technical use case Read Academy guide

User prompt

Using GAM REST only, if the linked fields are available, run a HISTORICAL report for the last 7 days by DATE, PAGE_PATH and DEMAND_CHANNEL_NAME. Include SESSIONS, GOOGLE_ANALYTICS_REVENUE, ADSENSE_REVENUE, AD_EXCHANGE_REVENUE and AD_EXCHANGE_AVERAGE_ECPM.

Skill instructions

Allowed MCP actions: get_report_dimensions, get_report_metrics, run_custom_report, get_report_result. Use api="rest" and report_type="HISTORICAL". If a field is missing or empty, explain that the linked source may not be active in GAM.

Allowed MCP functions

get_report_dimensionsget_report_metricsrun_custom_reportget_report_result

Field references

Dimensions

DATEPAGE_PATHDEMAND_CHANNEL_NAME

Metrics

SESSIONSGOOGLE_ANALYTICS_REVENUEADSENSE_REVENUEAD_EXCHANGE_REVENUEAD_EXCHANGE_AVERAGE_ECPM

Representative output

  • /news/live | Direct | 18,420 sessions | EUR 1,284 GAM Analytics revenue | EUR 942 Ad Exchange revenue | EUR 3.82 AdX eCPM.
  • DEMAND_CHANNEL_NAME=AdSense added EUR 218 on 62,410 impressions; AD_EXCHANGE_REVENUE is the larger linked-demand source.
  • Note: these are GAM REST linked fields; no GA4 Data API or Google Ads API was called.

Guardrails

  • Do not ask for a GA4 property ID or Google Ads account ID.
  • Do not describe unavailable cost, keyword, bid or native click data as GAM REST output.

Finance / AdOps

Billing and export evidence skill

For monthly finance checks that compare contracted quantities, delivered impressions, revenue and CSV evidence rows.

Open technical use case

User prompt

Prepare the May billing report. Include STANDARD and SPONSORSHIP line items only, show contracted vs delivered impressions, revenue and eCPM, then export the result as CSV for finance.

Skill instructions

Use generate_billing_report for contracted vs delivered rows. Use get_report_result for review and export_report_csv for the finance file. If a download URL exists, use get_report_download_link after the export action.

Allowed MCP functions

generate_billing_reportget_report_resultexport_report_csvget_report_download_link

Field references

Representative output

  • May billing: 42 billable line items, 38 delivered within tolerance, 4 need make-good review.
  • STANDARD delivered 93.2% of contracted impressions; SPONSORSHIP delivered 101.4%.
  • CSV export ready: billing_2026_05_standard_sponsorship.csv.

Guardrails

  • Billing reports are operational evidence, not final accounting documents.
  • Always preserve order, line item and advertiser names in the export.