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, 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, and keyword performance. Load once per conversation before the first insights_query call, and whenever the user wants to compare campaigns, channels, 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. 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. - attribution_window ('7-day'): '1-day' | '7-day' | '30-day' | 'unlimited'. - 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.