Billy Grace Insights

Resolve a client display name to a tenant client_id. Call this before any other tool when you only have a display name. Arguments: - client_name (optional, default '%'): display name to search. Plain text matches any part of the name, case-insensitively. For pattern search, use '%' as a placeholder for any run of characters and '_' for a single character; omit the argument or pass '%' alone to list all accessible clients (respects limit). Returns: {results: [{id, name}, ...], requires_selection: bool, note: str}. Follow the note field for next steps. Empty results is a normal outcome, not a tool failure — confirm the spelling with the user and retry, narrow the name, or list all accessible clients with client_name='%'. Do not guess a client_id.

Load full skill content for one or more skill refs. A skill ref is either: - a bare skill name (e.g. 'billy-grace-data-retrieval') — returns the full SKILL.md body, or - a reference path (e.g. 'billy-grace-data-retrieval/references/metrics.md') — returns that specific reference document. Examples: - skill_refs=['billy-grace-data-retrieval'] - skill_refs=['billy-grace-data-retrieval', 'billy-grace-data-retrieval/references/metrics.md'] Load billy-grace-data-retrieval once per conversation before the first insights_query. Use only refs listed in the catalog below. Available skills: - billy-grace-analysis: Interpret Billy Grace marketing results: analyze campaign performance, explain ROAS and CPA, apply funnel stages, optimize budgets, compare channels, evaluate creative performance, landing pages, organic search, and advertised vs sold products, and diagnose why performance changed. Use whenever the user asks what the numbers mean, why results moved, or how to improve them, even if they never say "analysis". Do not use to build or run the query that fetches the data (use billy-grace-data-retrieval), or to pick attribution models, modes, or windows (use billy-grace-attribution). - billy-grace-attribution: Choose and explain Billy Grace attribution settings: attribution models (Last Click, MTA, UMM), attribution modes (Session Date vs Event Date), attribution windows (1-day through unlimited), and conversion lag. Use whenever the user mentions attribution, MTA, UMM, last click, session date, event date, attribution windows, or conversion lag, or when the choice of attribution parameters changes how a query result must be read. Do not use to build or run the query itself (use billy-grace-data-retrieval), or for performance interpretation unrelated to attribution settings (use billy-grace-analysis). - billy-grace-data-retrieval: Query Billy Grace marketing data: campaign performance, ROAS, CPA, spend, conversions, impressions, clicks, ad sets, channels, custom events, shopping product ads, products sold, paid search keywords, landing pages, organic Google search (Search Console), and reach and frequency. Load once per conversation before the first insights_query call, and whenever the user wants to compare campaigns, channels, products, pages, or time periods. Do not use to interpret or explain numbers that have already been returned (use billy-grace-analysis), or to choose attribution models, modes, or windows (use billy-grace-attribution).

Discovery tool for insights_query. Returns valid metrics, dimensions, and attribution options for a dataset. Arguments: - table_name (required): one of marketing_performance, shopping_performance, keyword_performance, product_sales, landing_page_performance, search_console_performance. Returns: {table_name, description, metrics, dimensions, attribution_models, attribution_modes}. Call this before insights_query to pick a dataset and valid fields.

Fetch aggregated marketing performance metrics for a single client over a date range. Typical workflow (first data question in a conversation): 1. Load workflow guidance once: get_skills(skill_refs=['billy-grace-data-retrieval']). 2. get_client_id when you only have a display name; otherwise reuse client_id from context. 3. get_table_schema(table_name=...) to pick dataset and valid fields. 4. list_custom_events(client_id) to pick event and per-event attribution/metrics. 5. insights_query (this tool). For follow-up questions in the same conversation, reuse client_id and prior discovery results. Do not reload the skill or re-resolve the client unless the user switches accounts. Required arguments: - client_id: tenant id from conversation context or get_client_id. - metrics: metric names from get_table_schema / list_custom_events. Do not invent names. - start_date, end_date: inclusive ISO dates (YYYY-MM-DD). - custom_event: event name as returned by list_custom_events. Optional arguments (defaults in parentheses): - table_name ('marketing_performance'): marketing_performance | shopping_performance | keyword_performance | product_sales | landing_page_performance | search_console_performance. - attribution_window ('7-day'): '1-day' | '7-day' | '30-day' | 'unlimited'. Omit it for attribution_model 'LC', which has no attribution window and rejects one. - attribution_model ('MTA'): 'LC' | 'MTA' | 'UMM' Call get_table_schema to see which models are supported for a given dataset. - attribution_mode ('session_date'): 'session_date' | 'event_date' Call get_table_schema to see which modes are supported for a given dataset. - dimensions ([]): group-by columns from get_table_schema. - dimension_filter_mapping ({}): SQL-IN filters, e.g. {'source': ['facebook', 'google']}. - limit (1000): max rows, capped at 10000. Notes: - All datasets require customer_name + custom_event (ev) filters. - Returns rows with requested dimensions and SUM-aggregated metric values.

Discovery tool for insights_query. Lists custom events for a client with per-event attribution models and metrics from Postgres configuration. Arguments: - client_id (required): tenant id from conversation context or get_client_id. - table_name (optional, default marketing_performance): dataset context. - limit (optional, default 1000, max 10000): maximum distinct events returned. Returns: list of {name, attribution_models, metrics} objects.

Fetch reach (unique people reached) and frequency (average times each saw an ad) for paid channels that report them, such as Meta and TikTok, at campaign or ad set level. Reach cannot be summed: the same person is reached on several days and by several campaigns. This tool never sums. It reduces rows to one value per campaign or ad set, then returns the min, max, and mean across whatever group_by collapses, with every campaign or ad set weighted equally. Never add up the returned reach values yourself. Required arguments: - client_id: tenant id from conversation context or get_client_id. - start_date, end_date: inclusive ISO dates (YYYY-MM-DD). Optional arguments (defaults in parentheses): - level ('campaign'): 'campaign' | 'adset'. - window ('1d'): '1d' | '7d' | '30d' | '90d'. Pre-deduplicated reach over the trailing window ending on each date. - group_by ([]): any of 'date_column', 'source', 'campaign', 'adset' (adset level only). - entity_date_reducer ('mean'): 'window_endpoint' | 'mean'. How each campaign or ad set's dates are reduced when date_column is not kept. - source (none): one source to filter on, e.g. 'facebook'. - limit (1000): max rows, capped at 10000. Unique reach over a period: set start_date and end_date both to the period's last day, pick the matching window (e.g. '30d' for the last 30 days), and use entity_date_reducer 'window_endpoint'. Widening the date range instead averages overlapping windows. Load billy-grace-data-retrieval/references/reach-and-frequency.md via get_skills before the first call. Returns: {rows: [...]}, ordered by reach_mean, highest first. Only campaigns or ad sets with reach in the window are counted.

Report a dataset, metric, dimension, or capability that this server does not offer yet, so the Billy Grace product team can consider adding it. Call this when a user question cannot be answered because the data is missing, not when a call fails for another reason. First check the gap is real with get_table_schema and list_custom_events, because a field you did not find is usually named differently rather than absent. Submit one suggestion per gap, and do not resubmit a gap you already reported in this conversation. Arguments: - client_id (required): tenant the suggestion is raised for, from conversation context or get_client_id. The gap is counted per client, so pass the client the user was asking about. - kind (required): dataset | metric | dimension | tool | other. - title (required): short name for the missing thing, 3-120 characters. Reuse the wording the data would use, so repeated requests for the same gap group together. - description (required): what it should contain or measure and how it would be used, 10-2000 characters. - table_name (optional): marketing_performance | shopping_performance | keyword_performance | product_sales | landing_page_performance | search_console_performance, when the gap concerns one dataset. Write the description in your own words as a data need. Do not quote the user, and never include personal data such as names, email addresses, phone numbers, or anything that identifies one person. Returns: {suggestion_id, suggestion_key, note}. Quote the suggestion_id to the user, tell them the suggestion is recorded for review and not a commitment to build it, then continue with what the current tools can answer.