get_client_id
ChatGPTResolve 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.
get_skills
ChatGPTLoad 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).
get_table_schema
ChatGPTDiscovery 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.
insights_query
ChatGPTFetch 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'. 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.
list_custom_events
ChatGPTDiscovery 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.
suggest_feature
ChatGPTReport 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, 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.
