Aller au contenu principal
OrbiAds logo — infrastructure AdOps IA pour Google Ad Manager OrbiAds
OrbiAds logo — infrastructure AdOps IA pour Google Ad Manager
Accedi
GitHub
Docs reporting

Skill MCP

Personalizzare skill di reporting per Claude, Codex e MCP

Usa uno skill quando la stessa domanda di reporting ritorna ogni giorno. Lo skill deve fissare azioni MCP consentite, dimensioni e metriche esatte, formato output e guardrail.

Cosa deve contenere uno skill reporting

Un buon skill non e un prompt generico. E un piccolo contratto operativo per l agente: funzioni MCP consentite, campi GAM validi, forma output JSON o prosa, e azioni vietate.

Azioni consentite

MCP functions + scope

Contratto campi

Dimensions + metrics

Contratto output

JSON, CSV, or summary

Mappa link interni

Ogni skill deve linkare il catalogo campi e la pagina caso esatta. Il lettore ha un percorso chiaro e la SEO comprende meglio il cluster reporting.

Claude Cowork

Skill report GAM giornaliero

Per un brief AdOps mattutino che spiega delivery, revenue, problemi di fill e azioni senza aprire uno spreadsheet.

Apri caso tecnico Leggi guida Academy

Prompt utente

Claude, esegui il report GAM di ieri per DATE, ADVERTISER_NAME, ORDER_NAME, LINE_ITEM_NAME e AD_UNIT_NAME. Includi AD_SERVER_IMPRESSIONS, AD_SERVER_CLICKS, AD_SERVER_CTR, AD_SERVER_REVENUE, AD_REQUESTS, FILL_RATE e UNFILLED_IMPRESSIONS. Riassumi anomalie e dammi il resultId.

Istruzioni skill

Azioni MCP consentite: get_report_dimensions, get_report_metrics, run_custom_report, get_report_result, export_report_csv. api=rest di default. Usa api=soap solo se la reference dice che REST non e disponibile. Restituisci sintesi, azioni e resultId.

Funzioni MCP consentite

get_report_dimensionsget_report_metricsrun_custom_reportget_report_resultexport_report_csv

Reference campi

Output rappresentativo

  • Ieri: 1.284.220 impression, EUR 4.862 revenue, CTR 0,42 %, fill rate 91,8 %.
  • Attenzione: LI-8241 e 18 % sotto la media 7 giorni su AD_UNIT_NAME=Sports/Home.
  • Azione: controllare rotazione creative entro mezzogiorno; resultId rep_20260609_daily.

Guardrail

  • Non inventare campi. Validare nomi incerti con get_report_dimensions o get_report_metrics.
  • Usare GAM REST per tutto il reporting qui; i campi Analytics collegati sono colonne GAM opzionali solo se il link e attivo.

Codex

Skill triage inventario invenduto

Per ordinare le ad unit dove esiste domanda ma fill o monetizzazione perdono valore.

Apri caso tecnico Leggi guida Academy

Prompt utente

Codex, trova inventario invenduto degli ultimi 7 giorni per DATE, AD_UNIT_NAME, AD_UNIT_CODE e DEVICE_CATEGORY_NAME. Usa AD_REQUESTS, AD_SERVER_IMPRESSIONS, UNFILLED_IMPRESSIONS e FILL_RATE. Ordina per revenue persa stimata ed esporta CSV se ci sono piu di 20 righe.

Istruzioni skill

Usa run_custom_report per il report REST completo. fetch_inventory_report e consentito solo come vista rapida ad-unit inventory, non come fonte di tutte le metriche di invenduto. Mantieni AD_REQUESTS accanto a UNFILLED_IMPRESSIONS.

Funzioni MCP consentite

get_report_metricsrun_custom_reportget_report_resultexport_report_csvfetch_inventory_report

Reference campi

Output rappresentativo

  • Sports/Homepage | 184.210 ad requests | 52.440 unfilled | fill rate 71,5 % | revenue persa stimata EUR 1.126.
  • Ipotesi: problema di domanda o sizes, non perdita traffico.
  • Azione: controllare filtri domanda, price floor e bidder sizes prima di cambiare trafficking.

Guardrail

  • Non chiamare GA4 o Google Ads API per questo workflow.
  • Non ottimizzare price floor su un solo giorno; confronta ieri, 7 giorni e stesso weekday.

Codex

Skill guardrail forecast line item

Per verificare se un line item pianificato puo deliverare prima di mutare GAM.

Apri caso tecnico Leggi guida Academy

Prompt utente

Codex, esegui standalone forecast per un line item STANDARD pianificato: Francia, ad units Homepage, sizes 300x250 e 728x90, goal 500000 impression, priorita 8, frequency cap 3 al giorno. Restituisci availableUnits, matchedUnits, possibleUnits, riskLevel e constraint da rilassare.

Istruzioni skill

Usa funzioni forecast, non run_custom_report, perche la disponibilita futura non e una metrica storica. Non creare, aggiornare o riservare il line item. Restituisci decisione: safe, review o unsafe.

Funzioni MCP consentite

get_standalone_forecastget_delivery_forecast_by_line_itemget_prospective_delivery_forecast

Reference campi

Dimensioni

lineItemType=STANDARDadUnitIdscreativePlaceholdersgeoTargetingfrequencyCaps

Metriche

availableUnitsmatchedUnitspossibleUnitsriskLevel

Output rappresentativo

  • Forecast: 612.400 availableUnits per goal 500.000, matchedUnits 544.900, riskLevel=LOW.
  • Constraint da monitorare: Homepage + Francia + frequency cap 3/giorno riduce possibleUnits del 21 %.
  • Decisione: safe per review sales, rigenerare prima del booking.

Guardrail

  • Il forecast e una stima di planning, non garanzia di delivery.
  • Per line item esistenti, usa get_delivery_forecast_by_line_item.

Codex / LLM JSON

Skill forecast JSON order e key-values

Per restituire un forecast JSON ripetibile che combina contesto order GAM, ID custom targeting risolti e numeri di disponibilita.

Apri caso tecnico Leggi guida Academy

Prompt utente

Codex, produci solo un JSON forecastDecision per l order OR-2026-SUMMER: risolvi l order, risolvi audience=sports e hb_pb=20 in keyId/valueIds, forecastea ad units Homepage/Sports dal 2026-07-01 al 2026-07-31 per 500000 impression, sizes 300x250 e 728x90, priorita 8, frequency cap 3 al giorno.

Istruzioni skill

Azioni MCP consentite: 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. Risolvi gli ID prima del forecast. Restituisci solo JSON, senza prosa. Il forecast non e un report REST HISTORICAL.

Funzioni MCP consentite

list_ordersget_ordersearch_custom_targetingget_custom_targeting_valuesget_standalone_forecastget_delivery_forecast_by_line_itemget_prospective_delivery_forecast

Reference campi

Metriche

availableUnitsmatchedUnitsutilizationPercentriskLevel

Output rappresentativo

  • {"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"}}

Guardrail

  • Non creare, modificare, approvare o riservare l order da questa skill.
  • Non forecasteare con nomi key-value grezzi; risolvi prima gli ID.
  • Mantieni chiavi JSON stabili cosi i prompt LLM downstream validano i campi richiesti.

GAM REST / liens actifs

Skill campi collegati GAM REST

Per reportare campi Analytics, AdSense o Ad Exchange esposti da Google Ad Manager quando il link o la fonte e attiva in GAM.

Apri caso tecnico Leggi guida Academy

Prompt utente

Solo con GAM REST, se i campi collegati sono disponibili, esegui un report HISTORICAL degli ultimi 7 giorni per DATE, PAGE_PATH e DEMAND_CHANNEL_NAME. Includi SESSIONS, GOOGLE_ANALYTICS_REVENUE, ADSENSE_REVENUE, AD_EXCHANGE_REVENUE e AD_EXCHANGE_AVERAGE_ECPM.

Istruzioni skill

Azioni MCP consentite: get_report_dimensions, get_report_metrics, run_custom_report, get_report_result. Usa api="rest" e report_type="HISTORICAL". Se un campo manca o e vuoto, spiegare che la fonte collegata potrebbe non essere attiva in GAM.

Funzioni MCP consentite

get_report_dimensionsget_report_metricsrun_custom_reportget_report_result

Reference campi

Dimensioni

DATEPAGE_PATHDEMAND_CHANNEL_NAME

Metriche

SESSIONSGOOGLE_ANALYTICS_REVENUEADSENSE_REVENUEAD_EXCHANGE_REVENUEAD_EXCHANGE_AVERAGE_ECPM

Output rappresentativo

  • /news/live | Direct | 18.420 sessions | EUR 1.284 revenue Analytics GAM | EUR 942 revenue Ad Exchange | EUR 3,82 eCPM AdX.
  • DEMAND_CHANNEL_NAME=AdSense aggiunge EUR 218 su 62.410 impression; AD_EXCHANGE_REVENUE e la fonte collegata maggiore.
  • Nota: sono campi collegati GAM REST; nessuna chiamata GA4 Data API o Google Ads API.

Guardrail

  • Non chiedere GA4 property ID o Google Ads account ID.
  • Non descrivere costi, keyword, bids o click nativi non disponibili come output GAM REST.

Finance / AdOps

Skill billing ed export evidenze

Per controlli finance mensili che confrontano quantita contrattate, impression delivered, revenue e righe CSV.

Apri caso tecnico

Prompt utente

Prepara il billing report di maggio. Includi solo line items STANDARD e SPONSORSHIP, mostra contracted vs delivered impressions, revenue ed eCPM, poi esporta CSV per finance.

Istruzioni skill

Usare generate_billing_report per righe contracted vs delivered. Usare get_report_result per review ed export_report_csv per finance. Se esiste URL download, usare get_report_download_link dopo export.

Funzioni MCP consentite

generate_billing_reportget_report_resultexport_report_csvget_report_download_link

Reference campi

Output rappresentativo

  • Billing maggio: 42 line items fatturabili, 38 in tolleranza, 4 da rivedere per make-good.
  • STANDARD ha delivered 93,2 % delle impression contrattate; SPONSORSHIP 101,4 %.
  • Export CSV pronto: billing_2026_05_standard_sponsorship.csv.

Guardrail

  • I billing report sono evidenze operative, non documenti contabili finali.
  • Conservare sempre order, line item e advertiser names nell export.