Reportei

Permanently delete a timeline event by its ID. This action CANNOT be undone. You MUST confirm with the user before deleting. WHEN TO CALL: Use when the user explicitly asks to remove a timeline event. Examples: 'Remove the outdated milestone', 'Delete the timeline event I just created', 'Clean up old annotations for this project'. WARNING: Always confirm with the user before deleting: "Are you sure you want to delete this timeline event? This cannot be undone." PREREQUISITES: Call list_timeline_events first to find the event ID.

delete_timeline_event

Permanently remove a webhook subscription by ID. The URL will no longer receive notifications. This action CANNOT be undone. You MUST confirm with the user before deleting. WHEN TO CALL: Use when the user explicitly asks to remove a webhook subscription. Examples: 'Remove webhook 123', 'Unsubscribe from this webhook', 'Delete the webhook for report_created'. WARNING: Always confirm with the user before deleting: "Are you sure you want to delete this webhook? This cannot be undone." PREREQUISITES: Call list_webhooks first to get the webhook id.

delete_webhook

Get full details of a single automation: schedule, notification channels and their config, recipients, WhatsApp settings, last run, sources (integrations), template, period, and comparison period. Returns notification_channels (array of active channels: "email", "in-app", "whatsapp"), email recipients (if email channel active), whatsapp_url and whatsapp_type (if whatsapp active). WHEN TO CALL: Use when the user asks about a specific automation's configuration. Examples: 'What are the settings for automation X?', 'Who receives this automated report?', 'Which integrations are included in this automation?', 'How is this automation notifying?'. PREREQUISITES: Call list_automations first to get the automation id.

get_automation

Retrieve the authenticated company profile and settings. Returns: id, name, logo, type, total_clients (number of projects), and company_specialty. TERMINOLOGY: A "company" is the top-level account in Reportei. It owns multiple projects (clients). WHEN TO CALL: Use to verify authentication, check company context, or answer questions about the company itself. Examples: 'How many projects do I have?', 'What is my company name?', 'What type of company am I?', 'What is my company specialty?'. NEXT STEPS: Call list_projects to see individual projects within the company.

get_company_settings

Compose and execute a fully customized datatable query for a single integration using a custom set of metrics and dimensions, then return the rows. Nothing is persisted — no widget, table, report or dashboard is created or modified. Use this tool when: - The user needs insights from a table with a combination of columns that does not match any existing preset (e.g. "show campaigns by spend, CPM and frequency" when no preset has all three). - You want to reason over richer or more focused data than what is already in the report before giving your answer. Workflow: 1. Call list_table_fields(integrationSlug) to discover valid metric keys, dimension keys, and available preset reference_keys for this integration type. 2. Pick a reference_key from datatable_presets as the base (it carries the correct query template for G4 — do not invent reference_keys). 3. Call this tool with the reference_key plus your chosen metric/dimension keys. IMPORTANT — nothing is altered: This is an internal read-only query. The user's reports, dashboards, and widgets are never touched. Use the returned data to reason and craft your answer, then discard it. Returns: { spec_used, rows, rows_total, rows_truncated } on success. { error: true, type, message } on failure. Error types: not_found, not_editable, invalid_reference_key, invalid_metrics, invalid_dimensions, too_many_metrics, too_many_dimensions.

get_custom_table_data

Retrieve full details of a single dashboard by its ID, including shareable URLs. Returns: id, title, subtitle, start_date, end_date, comparison_start_date, comparison_end_date, template_id, client_id, created_at, internal_url, and external_url. WHEN TO CALL: Use when the user wants details about a specific dashboard. Examples: 'Get the link to dashboard X', 'What period is this dashboard showing?'. The external_url can be shared with clients for a live, always-updated view. PREREQUISITES: Call list_dashboards first to find the dashboard ID.

get_dashboard

Fetch the full Markdown content of a help-center article by its slug. The slug must come from the catalog listed in the system prompt or from a previous search_help_center call — do NOT guess or invent slugs. Returns: { found: true, slug, title, content } on success. { found: false, error } when the article does not exist. After retrieving the content, summarise it in plain language for the user. Do NOT dump the raw Markdown verbatim — always paraphrase or highlight the key steps relevant to the user's question.

get_help_article

Retrieve full details of a single connected integration (account / data source / network) by its ID. Returns: id, name, slug, status ("active" or "inactive"), project_id, project_name, created_at, and updated_at. TERMINOLOGY: "account", "network", "source" all refer to integrations. WHEN TO CALL: Use when the user asks about a specific integration's details. Examples: 'Is my Facebook Ads integration active?', 'When was this integration connected?', 'Which project does this account belong to?'. PREREQUISITES: Call list_integrations first to find the integration ID. NEXT STEPS: Use the slug from the response with list_metrics to discover available metrics.

get_integration

Fetch actual numeric/chart/table data for one or more SPECIFIC metrics of a SINGLE connected integration (account/source/network) within a date range. This is the most granular data tool — it fetches exact metrics you choose from exactly one integration. TERMINOLOGY: integrationId refers to a connected account/source (from list_integrations), NOT a project/client ID. IMPORTANT — METRICS FORMAT: Each object in the metrics array MUST be passed exactly as returned by list_metrics. Do NOT add, remove, or modify any fields. Only include fields that list_metrics returned for that metric. If list_metrics returned dimensions, sort, custom, or type, include them as-is. If list_metrics did NOT return a field, do NOT include it (no empty arrays or nulls). WHEN TO CALL: Use when the user asks about specific metrics from a specific platform, or needs granular control over which data to fetch. Examples: 'How many followers did I gain this month on Instagram?', 'What was my ad spend on Facebook Ads specifically?', 'What is my website traffic trend on GA4?', 'How did my Instagram engagement change compared to last month?', 'What is my Google Ads ROAS for this quarter?'. WHEN NOT TO CALL: - If the user wants an overview across ALL platforms at once → use get_performance_summary instead (no need to call list_metrics first). - If the user wants to compare channel categories → use get_channel_breakdown instead. - If the user wants only ads/paid metrics across all ad platforms → use get_campaign_summary instead. - If the user wants top posts/content → use get_top_content instead. - If the user wants audience demographics across platforms → use get_audience_insights instead. CRITICAL PARAMS: The metrics array MUST NOT be invented. You MUST call list_metrics first to get valid metric objects. If the user has not specified which metrics they want, ask them or call list_metrics to discover what is available before calling this tool. PREREQUISITES: 1. list_integrations → get integrationId 2. list_metrics → get metric objects (pass the slug from the integration) 3. Then call this tool with those exact metric objects. Returns metric values keyed by reference_key. Errors are returned inline as {type: "no_data_in_period"}, {type: "expired_token"}, or {type: "invalid_metrics_combination"}. Optionally provide comparisonStart/comparisonEnd for period-over-period comparison on a single integration.

get_metrics_data

Get REPORTEI'S OWN opportunity score for a project (client), computed by Reportei from the Meta Ads data it has already collected. This is not the score Meta shows inside Ads Manager, and the two numbers are not expected to match. The score highlights how much optimization opportunity exists in the connected Meta Ads account selected by Reportei's opportunity score logic. This tool is read-only: it never applies recommendations or changes campaigns. WHEN TO CALL: Use when the user asks for an optimization score, opportunity score, improvement potential, or quick health check for Meta Ads on a specific project. This is the default for a bare "opportunity score" request. PREREQUISITES: Call list_projects first to get the projectId. NEXT STEP: Call get_recommendations with the same projectId to inspect the recommended actions.

get_opportunity_score

Retrieve full details of a single project (client) by its ID. Returns: id, name, logo, timezone, locale, date_format, and decimal_separator_format. TERMINOLOGY: "project", "projeto", "client", "cliente" refer to projects. "account", "conta", "network", "rede", "source" refer to integrations — use get_integration instead. WHEN TO CALL: Use when the user asks about a specific project's settings. Examples: 'What timezone is client X using?', 'What locale and date format does this project use?'. PREREQUISITES: Call list_projects first to find the project ID.

get_project

Get Meta Ads optimization recommendations for a project (client), based on REPORTEI'S OWN opportunity score data — not on what Meta's Ads Manager is currently recommending. Recommendations may include affected campaign/ad objects when includeObjects is true. This tool is read-only: it never applies recommendations or changes campaigns. WHEN TO CALL: Use when the user asks what to improve, which optimizations are recommended, or why the Meta Ads opportunity score can be improved. WHEN NOT TO CALL: Do not use this tool to apply recommendations. The MCP intentionally exposes no apply/mutation action for Meta Ads recommendations. PREREQUISITES: Call list_projects first to get the projectId.

get_recommendations

Retrieve full details of a single report by its ID, including shareable internal and external URLs. Returns: id, title, subtitle, start_date, end_date, comparison_start_date, comparison_end_date, template_id, client_id, created_at, internal_url, and external_url. WHEN TO CALL: Use when the user wants details about a specific report. Examples: 'Get the shareable link for report X', 'What period does this report cover?'. The external_url can be shared with clients who do not have a Reportei account. PREREQUISITES: Call list_reports first to find the report ID.

get_report

Retrieve the ACTUAL metric VALUES (widget data) of an existing report OR dashboard by its ID. Unlike get_report (which returns only metadata), this returns the numbers the user sees on screen: KPI values with period-over-period comparison, chart series, and table rows, grouped by integration (Facebook, Instagram, Google Ads, etc.). WHEN TO CALL: - The user refers to "this report", "this dashboard", "esse relatório", or the data on screen (the SCREEN CONTEXT section of the system prompt provides the reportId when applicable). - The user asks you to analyze, summarize, comment on, or compare the metrics of a specific existing report/dashboard. Examples: 'What do you think about this report?', 'Resuma os números desse relatório', 'Which metric grew the most here?', 'Compare os canais desse dashboard'. WHEN NOT TO CALL: - To fetch fresh/live metrics not tied to an existing report → use get_metrics_data. - For report metadata only (title, dates, share link) → use get_report. PARAMS: - reportId (required): numeric ID of the report or dashboard. - sourceId (optional): restrict the response to a single integration's source_id (from the report's own sources) when the report is large and you only need one platform. - sortByColumn (optional): a column name from a table's `columns` list (e.g. "results", "spend", "cost_per_results"). Sorts EVERY in-scope table that has that column by its numeric value over the table's FULL rows (before sampling) and returns the top of the sorted order — so you get the TRUE highest/lowest even from a `rows_truncated` table. Non-numeric/empty cells sort last. Pair with sourceId to scope to one integration. - descending (optional): direction for sortByColumn. true (default) = highest first ("most/best/top"); false = lowest first ("cheapest/fewest/worst"). RESPONSE SHAPE: `sources[]` lists EVERY integration in the report (always complete, never truncated) — each with `platform` (e.g. "Instagram Business", "Facebook", "YouTube", "Pinterest"), `account_name`, `data_status`, and its `widgets`. To answer "which integrations/networks are in this report", read `sources[].platform` and EXCLUDE any entry flagged `is_custom_block:true` (a consolidated summary block, not a network). PERIOD & DATA FRESHNESS: `report.start_date`/`end_date` are the CURRENT analysis period and `report.data_synced_at` is when the data was last synced. State the period from these fields — NEVER invent, guess, or carry over a date range from another report. A dynamic dashboard's period can legitimately be a single day (e.g. a "week-to-date" view on a Monday). If `data_synced_at` is clearly older than the period end (the data was not refreshed for the current window), do NOT present the figures as the current period's data — say plainly that the latest available data is from `data_synced_at`. WIDGET TYPES: each widget has a `type` — `number` (single KPI, may include a `comparison`), `chart` (time series in `labels`+`series`), `table` (a `columns` list naming each column, then `rows`; each row's values are POSITIONAL — value at index N belongs to `columns[N]`; may be `rows_truncated`), or `funnel` (an ORDERED list of `steps[]`, each a stage with its own `label`+`value`, e.g. content views → add to cart → leads → purchases). A funnel step already gives the report's EXACT aggregate for that stage. PREFER a direct aggregate (a `number` KPI or a `funnel` step) over summing `table` rows — table rows may be truncated (`rows_truncated:true`), so summing them undercounts. Only sum table rows when no direct aggregate for that metric exists, and if the table is truncated say the sum is a partial/visible total, not the real total. READING A TABLE: row values are positional — to read a metric, find it in `columns` and take the value at that same index in each row (some cells are objects like {value, title} where `title` names the result type; use `value` for math). A cell's value is the literal figure shown on screen for that column. RANKING / SUPERLATIVES ("which campaign/ad/row has the highest/lowest/best/worst X?", "top/worst N"): This is a MANDATORY flow. Correctness comes before speed — NEVER answer a ranking from an unsorted response, and NEVER give a preliminary / "based on the visible sample" answer. 1. Identify the EXACT metric asked — NEVER a proxy. Distinct metrics are NOT interchangeable: reach/alcance (unique people) is NOT impressions (total views), and neither is clicks/results. If the requested metric is NOT a column of the relevant table AND is not the result type of its rows, do NOT rank by a lookalike column — say the report doesn't break that metric down per row here and, if it is a real platform metric, fetch it LIVE (see METRIC NOT IN THE REPORT). E.g. "most reach" with no reach column → do NOT answer with impressions. 2. ALWAYS get the rows ALREADY SORTED by that metric BEFORE answering: call get_report_data with sortByColumn = that column and descending = true for highest/most/best or false for lowest/cheapest/fewest/worst (pair with sourceId to scope to the owning integration). Answer ONLY from that sorted result (its rows are flagged `sorted_by`). The rows of an UNSORTED call — including the visible sample of a `rows_truncated` table — are in arbitrary storage order, NOT ranked, so you must never rank off them. If you said you would fetch sorted data, you MUST issue that call before replying. This applies to EVERY ranking question, even a table that looks small or complete — when in doubt, do the sorted call. 3. Ambiguous "best / melhor" with no explicit metric: pick the clearest concrete metric for those rows (e.g. most results/conversions), STATE which metric you used, and sort by it — or ask the user the criterion. Never answer "best" vaguely from unsorted data. 4. ONE EXCEPTION for a LOWEST cost ranking — a "cost per X" / cost-per-result / any ratio column reads 0 (or empty) when the row had ZERO results: that is an UNDEFINED ratio, not the "cheapest". Skip rows whose result count is 0 and take the smallest POSITIVE value among rows that actually produced results. 5. Report the literal top row(s) of the sorted result. You MAY add one line noting the winning row's result type differs from others, but the literal extreme is the answer. Mention truncation only if the sorted result itself is still `rows_truncated`. PROJECTIONS: any forward-looking or extrapolated figure — "per month", "would generate +X", scaling this (~30-day) period out, "potential of …" — is an ESTIMATE, not a number from the report. Label it clearly as an estimate/projection and do not present it with false precision; the report's own figures are the only actuals. METRIC NAMES — USE `widget.label`: each widget carries a human-readable `label` (its exact metric name); `metric` is only an internal id. ALWAYS refer to a metric by its `label`, and respect the distinctions it encodes — several metrics look similar but are NOT the same. For reach especially: a label like "Total reach (organic + paid) in the last 30 days" is a FIXED 30-day window (NOT the report's analysis period), while "Sum of daily unique reach" is summed across the period and may count a person on multiple days. Never present a "last 30 days" value as if it were the report period's value, and never sum different reach labels together. ALWAYS list EVERY integration, including ones whose `data_status` is: - "error" → the integration is in the report but failed to load data; report it and briefly explain the reason from its `error` field (e.g. expired token, needs reintegration). - "no_data" → present but returned no data for this period. - "ok" → has data in `widgets`. NEVER omit an integration just because it has no widgets — say it is present and why its data is missing. Only widget VALUES are ever trimmed to fit the response; the integration list is not. METRIC NOT IN THE REPORT — FETCH IT LIVE AUTOMATICALLY (do NOT ask first): If the user asks for the value of a specific metric that is NOT among the widgets returned here, it was likely just not included in this report's template — but it can usually still be fetched LIVE for the SAME period and integration. Do NOT stop at "it's not in the report", do NOT tell the user to recreate the report or check the platform manually, and do NOT ask for permission or say "I can fetch it if you want" — go ahead and fetch it in THIS SAME response: 1. Note the report period and the relevant integration (platform + source_id) from this result. 2. list_integrations(projectId) → map that source_id to its integration id. 3. list_metrics(integration_slug) → find the metric's widget definition. 4. get_metrics_data(integrationId, start, end, [widget]) for the SAME period as the report. You MUST actually run get_metrics_data — reading get_report_data alone is NOT fetching live. NEVER say "I fetched it live" (or "busquei ao vivo") unless you truly called get_metrics_data in this turn. Do NOT just infer the value from another report figure (e.g. assuming 0 views because 0 stories were published) — actually fetch it; if you ever do reason from a report figure, state that basis honestly instead of claiming a live fetch. CRITICAL — your FINAL message (the one that states the value) MUST, in this exact order: FIRST the framing (BEFORE the number): (1) that this metric is NOT part of the report; (2) that you fetched it LIVE for the same period, so it may differ slightly from the report; (3) any genuinely important platform notice (e.g. the metric was discontinued/replaced). THEN lead with the REQUESTED metric as the clear headline answer (its name + value, standing out on its own, e.g. bold or its own line) — this is what the user asked for, so it must NOT be buried in a list. Only AFTER that may you add related/context metrics from the report. Put this framing in the FINAL answer itself — do NOT leave it only in the short pre-tool narration (the general "don't repeat pre-tool sentences" rule does NOT apply to this framing; the user must see it together with the number). Keep the whole reply concise. Only fetch for integrations that are actually in this report, and only for the report's period. If the platform cannot return the metric historically (a real limitation), say so plainly instead of guessing. PRESENTING TO THE USER: the field names in this response (data_status, points_truncated, rows_truncated, is_custom_block, widgets_shown, note, metric, columns, sorted_by, sort_desc, series, etc.) are INTERNAL, and so are the raw column names in `columns` and the metric identifiers / reference keys (e.g. "cost_per_results", "ig:stories_count", "gads:cost_micros", "fb_ads:spend"). Use the `columns` entries to locate data, but when presenting translate them to plain names ("cost per result", "custo por resultado") — never show the raw column key. NEVER show any raw field name, JSON key, or metric reference key to the user — always use the metric's plain human name ("Stories published", "Story Views", "Ad spend", etc.) and natural language. This also applies when the user asks HOW you do something (e.g. "how do you find the integrations in this report?"): answer at a PRODUCT level ("I read which integrations the report includes and each one's data status") and do NOT reveal the tool name, the response's field/JSON structure, or the internal filtering logic (e.g. skipping is_custom_block entries). Be transparent about WHAT you do, never about the raw internals. If some values were trimmed, only mention it if the user asks for detail you don't have, and phrase it plainly (e.g. "the full breakdown has more rows than I can show here"). Time-series charts return their points in `labels` + `series` — read the value at the requested label (e.g. label "8h") directly; do not claim data is unavailable when the label is present. NOTES: This is a READ-ONLY snapshot already stored for the report — no live API calls are made, nothing is modified. When a `note` about trimmed widget values appears, or when you need the true top/bottom of a `rows_truncated` table, call again with a specific sourceId (add sortByColumn + descending for the ranking) to drill into one integration.

get_report_data

Retrieve full details of a single timeline event by its ID. Returns: id, title, content (HTML), project_id, report_id, date, created_at, and updated_at. WHEN TO CALL: Use when the user wants the full content of a specific event. Examples: 'Get details of timeline event X', 'What is the full content of this milestone?', 'Which report is this event linked to?'. PREREQUISITES: Call list_timeline_events first to find the event ID.

get_timeline_event

Detailed progress data for a specific tracked KPI goal: current value, target, percentage completion, estimated end value, situation assessment, days remaining, and recent value history. WHEN TO CALL: Use when the user asks about detailed progress on a specific goal. Examples: 'How close am I to reaching my Instagram follower goal?', 'What is the progress on my Google Ads conversion goal?', 'Am I on track to hit my monthly target?', 'Show me detailed goal progress'. WHEN NOT TO CALL: - If the user wants a summary of ALL goals → use list_goals instead. PREREQUISITES: Call list_goals first to find the tracked_metric_id.

get_goal_progress

List all report automations for a project. Returns id, title, status (enabled/disabled), frequency (weekly/biweekly/monthly), notification channels, schedule, next run time, and last run. TERMINOLOGY: An "automation" is a scheduled job that automatically generates and delivers a report to recipients at a recurring interval. Delivery can happen via three channels: - "email": report sent to email addresses - "in-app": notification inside the Reportei platform - "whatsapp": report summary sent to a WhatsApp webhook URL Multiple channels can be active simultaneously (e.g. email + whatsapp). WHEN TO CALL: Use when the user asks about scheduled/automatic reports for a project. Examples: 'What automations are set for this project?', 'When does the next report get sent?', 'List scheduled report automations'. RELATED TOOLS: Use get_automation for full details of a specific automation, create_automation to add one, toggle_automation to enable/disable, update_automation to change settings. PREREQUISITES: Call list_projects first to get the projectId.

list_automations

List dashboards (live/dynamic data views) for the authenticated company. Unlike reports (static snapshots), dashboards refresh data automatically every time they are viewed. TERMINOLOGY: A "dashboard" in Reportei is a LIVE view that always shows up-to-date data. Reports are static snapshots. If the user says "dashboard" or "live view", use this tool. If the user says "report", use list_reports instead. WHEN TO CALL: Use when the user asks about existing dashboards or live views. Examples: 'Show me all live dashboards', 'Which dashboards does client X have?', 'Do I have any dashboards for this project?'. RELATED TOOLS: Use get_dashboard for full details, create_dashboard to create a new one. PREREQUISITES: Call list_projects first to get the projectId for filtering.

list_dashboards

List all tracked KPI goals for a project with their current situation. Each goal tracks a specific metric from a connected integration over a recurring time period with a target value. Returns goal ID, metric reference_key, source info, frequency, current value, target, progress percentage, and situation (high/ideal/average/low/no_data). TERMINOLOGY: A "goal" (also "KPI goal" or "tracked metric") is a target set for a specific metric (e.g. "reach 10000 Instagram followers this month"). Goals track progress automatically. WHEN TO CALL: Use when the user asks about goals, targets, KPIs, or tracking status. Examples: 'What goals are set for this project?', 'Which KPIs are being tracked?', 'Are we on track to meet our goals?', 'Show me all active goals and their status'. RELATED TOOLS: Use get_goal_progress for detailed progress on a specific goal, create_goal to add a new one, update_goal to change target or alerts. PREREQUISITES: Call list_projects first to get the projectId.

list_goals

List connected integrations (accounts / data sources / networks) for the authenticated company. Each entry returns: id, name, slug (e.g. "facebook_ads"), status ("active" or "inactive"), project_id, project_name, created_at, and updated_at. IMPORTANT: a project can hold several distinct accounts that share the same display name (e.g. three separate Meta Ads accounts all named "Reportei"). They are different integrations with different ids — list every one of them separately and never merge same-named entries into a single item. TERMINOLOGY: When the user mentions "account", "network", "source", or "data source", they are referring to integrations — use this tool. Do NOT use list_projects for these terms. Projects (clients) are a different concept: they group multiple integrations together. WHEN TO CALL: Use when the user asks about connected platforms, or as a prerequisite step to resolve integration IDs needed by other tools. Examples: 'Which platforms is my client connected to?', 'Do I have Google Ads connected?', 'Show me all Instagram accounts', 'Which networks are active for project X?'. NEXT STEPS: After getting integration IDs, use the slug with list_metrics to discover available metrics, or pass IDs to get_metrics_data, create_report, or create_dashboard. PREREQUISITES: Call list_projects first to get the projectId for filtering. PAGINATION: the response's `meta.last_page` tells you how many pages exist. When it is greater than 1 you have NOT seen every row — request the next pages before answering anything that depends on the full list (counts, "all of them", picking one to act on).

list_integrations

DISCOVERY tool: list all available metrics (widgets) for a given integration type identified by its slug. This tool does NOT fetch data — it returns the CATALOG of what can be fetched. Use the metric objects returned here as input to get_metrics_data to retrieve actual values. TERMINOLOGY: Metrics belong to integration TYPES (e.g. "facebook_ads", "instagram_business"), not to projects (clients). A "slug" identifies the platform type, not a specific connected account. Returns a paginated array where each entry contains: id, reference_key (e.g. "fb_ads:spend"), component (number_v1, chart_v1, or datatable_v1), metrics, dimensions, sort, and type. WHEN TO CALL: Use when the user asks what metrics are available, or before calling get_metrics_data to discover valid reference_keys. Examples: 'What metrics can I pull from Instagram?', 'Which KPIs are available for Google Ads?', 'What data can I get from Facebook Ads?', 'Show me all available YouTube metrics'. WHEN NOT TO CALL: - If the user wants actual metric VALUES (not discovery) → use get_metrics_data after calling this tool. - If the user wants a quick aggregated overview → use get_performance_summary or get_campaign_summary (they auto-select relevant KPIs without needing to discover metrics first). PREREQUISITES: Call list_integrations first to find the integration slug. NEXT STEP: Pass the metric objects returned here directly to get_metrics_data.

list_metrics

List projects (clients) for the authenticated company. This is typically the FIRST STEP in any workflow — most other tools require a projectId. TERMINOLOGY: When the user mentions "project", "projeto", "client", or "cliente", they refer to projects — use this tool. A project groups multiple integrations (accounts/sources) together. Do NOT use this tool when the user asks about "account", "conta", "network", "rede", or "source" — those refer to integrations; use list_integrations instead. Each entry returns: id, name, logo, timezone (e.g. "America/Sao_Paulo"), locale (e.g. "pt_br"), date_format, and decimal_separator_format. WHEN TO CALL: Use when the user asks about their clients/projects, or as the first step to resolve a projectId needed by other tools. Examples: 'Show me all my clients', 'Which projects do I manage?', 'How many clients do I have?', 'Find the project for client X'. NEXT STEPS: After getting a projectId, call list_integrations to see connected platforms, list_reports/list_dashboards for existing outputs, or any analytics tool for performance data. PAGINATION: the response's `meta.last_page` tells you how many pages exist. When it is greater than 1 you have NOT seen every project — request the next pages before answering anything that depends on the full list.

list_projects

List generated reports (static data snapshots) for the authenticated company. Each entry returns: id, title, subtitle, start_date, end_date, comparison_start_date, comparison_end_date, template_id, client_id, created_at, internal_url, and external_url. TERMINOLOGY: A "report" in Reportei is a STATIC snapshot of marketing data captured at creation time. It does NOT update automatically. For live/dynamic data views, use dashboards instead. WHEN TO CALL: Use when the user asks about existing reports, wants to find a report link, or wants to see report history. Examples: 'Show me recent reports for client X', 'What reports were created this month?', 'How many reports does this project have?', 'Find the latest report'. WHEN NOT TO CALL: - If the user wants live/dynamic views → use list_dashboards instead. - If the user wants to fetch raw metric data → use get_metrics_data or get_performance_summary. RELATED TOOLS: Use get_report for full details, create_report to generate a new one. PREREQUISITES: Call list_projects first to get the projectId for filtering.

list_reports

DISCOVERY tool: list all combinable metrics and dimensions available for a given integration type, along with its datatable presets (reference_keys you can use as the base for get_custom_table_data). Use this tool when you want to query a table with a CUSTOM set of columns that is different from what the report already shows. For example, if the user asks "compare campaigns by spend, impressions and CPM" and no existing preset already contains exactly those columns, call this tool first to verify the available metric keys, then call get_custom_table_data to fetch the result. Returns: - editable: whether this integration type supports column customization - datatable_presets: existing table presets (reference_key, default columns) - available_metrics: map of metric_key => label (all combinable columns) - available_dimensions: map of dimension_key => label (grouping/breakdown keys) WHEN NOT TO CALL: - If a preset from list_metrics already has the exact columns needed, use get_metrics_data directly — no need for custom composition. PREREQUISITES: Call list_integrations first to obtain the integration slug. NEXT STEP: Pass a reference_key from datatable_presets + chosen metric/dimension keys to get_custom_table_data.

list_table_fields

List report and dashboard templates available for the authenticated company. Each entry returns: id, title, description, created_at, and updated_at. TERMINOLOGY: A "template" defines the layout and widget configuration for reports and dashboards. Templates with "Dashboard" in the title are for create_dashboard; others are for create_report. The "Default" template is the platform-provided starter layout and can be used when the user does not specify a template preference. WHEN TO CALL: Use when the user asks about available templates, or as an optional prerequisite for create_report, create_dashboard, or create_automation. If the user does not specify a template, you can use the default — you do NOT need to call this tool in that case. Examples: 'Which templates can I use for a report?', 'What dashboard templates are available?', 'Show me my custom templates'. RELATED TOOLS: Pass the template id to create_report, create_dashboard, or create_automation.

list_templates

List timeline events (milestones, notes, or annotations) for the authenticated company. Each entry returns: id, title, content (HTML string), project_id, report_id (if linked), date (YYYY-MM-DD), created_at, and updated_at. TERMINOLOGY: A "timeline event" is a user-created milestone, note, or annotation recorded for a project. It can optionally be linked to a specific report. Also known as "milestone", "note", "annotation", or "event". WHEN TO CALL: Use when the user asks about milestones, events, notes, or timeline history. Examples: 'What milestones happened for client X?', 'Show me the timeline for this month', 'Which events are linked to this report?', 'What happened on this date for my project?'. RELATED TOOLS: Use get_timeline_event for full details, create_timeline_event to add new ones, update_timeline_event to modify, delete_timeline_event to remove. PREREQUISITES: Call list_projects first to get the projectId for filtering.

list_timeline_events

List all webhook subscriptions for the authenticated company. Returns each webhook's id, url, event_type, project_id (if scoped), status, created_at, updated_at. TERMINOLOGY: A "webhook" is a subscription that sends HTTP POST notifications to an external URL when specific events occur in Reportei. Each subscription covers one event type. Available event types: report_viewed, report_created, dashboard_created, automation_executed, control_goal_met, control_goal_not_met, timeline_milestone_added. WHEN TO CALL: Use when the user asks about webhook configurations or notifications. Examples: 'What webhooks are configured?', 'Which URLs receive report_created notifications?', 'List my webhook subscriptions'. RELATED TOOLS: Use create_webhook to add new subscriptions, update_webhook to modify, delete_webhook to remove.

list_webhooks

Aggregated KPI summary from ALL connected integrations of a project for a date range. Returns key numeric metrics (followers, engagement, reach, spend, clicks, sessions, etc.) grouped by platform in a flat list — all in a single call instead of querying each integration individually. This is the broadest overview tool available. WHEN TO CALL: Use for broad, cross-platform overviews. Examples: 'Give me an overview of all my marketing performance', 'How is my client doing across all channels?', 'Summarize this month's marketing KPIs', 'What are the key numbers for project X?'. WHEN NOT TO CALL: - If the user wants metrics grouped by CATEGORY (social vs ads vs analytics) → use get_channel_breakdown instead. - If the user asks specifically about ADS performance (spend, ROAS, CTR) → use get_campaign_summary instead. - If the user wants a specific metric from ONE integration → use get_metrics_data instead. - If the user wants period-over-period comparison with deltas → use compare_periods instead. - If the user wants top posts/content → use get_top_content instead. - If the user wants audience demographics → use get_audience_insights instead. PREREQUISITES: Call list_projects first to get the projectId.

get_performance_summary

Aggregate, rank, total or compare metrics across MULTIPLE projects (clients) of the company in a single call. Use this instead of looping per-project tools (get_campaign_summary, get_metrics_data, etc.) when the user asks something that needs data from many projects. WHEN TO CALL: - "Which project spent the most on X?" → aggregation=ranking with the right metric_keys. - "Total Y across all my clients" → aggregation=total. - "Compare metric A vs B in all projects" → aggregation=comparison with multiple metric_keys. - "Top 10 projects by Z" → aggregation=ranking, sort=desc, limit=10. WHEN NOT TO CALL: - Single-project questions → use get_metrics_data, get_campaign_summary, etc. - Time series across projects → not supported in v1. - Calculated/derived metrics (ROAS, CTR, conversion rate) → not supported in v1, request the base metrics and combine them yourself when possible. BEHAVIOR: This tool returns immediately with `{status: "queued"}` and a short summary. The actual answer is produced asynchronously and arrives in this same thread once the analysis is complete (can take a few minutes for accounts with many projects). The chat input stays locked while the background job runs. ===================================================================== FAST-PATH: USE A PRESET INSTEAD OF DISCOVERING metric_keys ===================================================================== For recurring cross-project questions you should use a `preset` — a curated bundle of reference_keys baked into the server. Presets are MORE RELIABLE than guessing metric_keys via list_metrics and SHOULD ALWAYS BE PREFERRED when one matches the user's question. AVAILABLE PRESETS: - "ads_spend" — total amount spent on paid ads across every supported network (Facebook Ads, Google Ads, TikTok Ads, LinkedIn Ads, Pinterest Ads, Microsoft Ads, Twitter Ads, Spotify Ads). Use it whenever the user asks about ads investment / spend / budget across projects. Examples: - "Qual projeto teve maior investimento em ads?" → preset="ads_spend", aggregation="ranking", sort="desc" - "Total gasto em anúncios no mês passado" → preset="ads_spend", aggregation="total" - "Top 5 clientes por investimento em mídia paga" → preset="ads_spend", aggregation="ranking", limit=5 When using a preset, leave metric_keys EMPTY ([]). The preset expands to the right reference_keys on the server side. ===================================================================== PARAMETERS: - preset (optional): one of the curated bundles above (e.g. "ads_spend"). When set, metric_keys must be empty/omitted — the preset supplies them. - metric_keys: array of V4Config reference_keys, e.g. ["fb_ads:spend", "gads:cost_micros"]. Use this ONLY when no preset fits. Call list_metrics(integration_slug) first if you don't know the exact keys. Only `number_v1` (scalar) widgets are supported. - aggregation: one of `ranking`, `total`, `breakdown`, `comparison`. - start_date / end_date: YYYY-MM-DD. - filters (optional): { integration_types?: int[], project_ids?: int[], max_projects?: int }. - sort: `desc` (default) or `asc` — only meaningful for ranking. - limit (optional): cap on result rows — only meaningful for ranking. - group_by: `project` (default) or `source_type` — only meaningful for breakdown. ERRORS: - `invalid_preset`: preset name does not exist. Inspect `available_presets` and retry. - `invalid_metric_key`: reference_key does not exist. Inspect `suggestions` and retry. - `unsupported_widget_type`: the requested metric is not scalar (chart/datatable). Pick a number_v1 widget instead. - `invalid_period`: dates are malformed or out of order. - `invalid_aggregation`: unknown aggregation strategy.

run_company_analysis

Search the Reportei help center knowledge base for articles matching a keyword or topic. Returns up to 5 results, each with a slug, title and one-sentence summary. Use this tool FIRST when the user asks a how-to question about the Reportei platform (e.g. "how do I create a template?", "why are my Instagram impressions not loading?"). After finding a relevant slug, call get_help_article to fetch the full content before answering. If no results are returned for a specific query, broaden the search term (e.g. "impressões" → "instagram métricas") and try once more. WHEN NOT TO CALL: - For data/analytics questions (use the metrics/report tools instead). - For billing disputes, account access issues or bug reports — emit [CONTACT_SUPPORT] so the user can reach a human agent.

search_help_center

Enable or disable an automation. When enabled, the automation is registered with the scheduler and will run at the next scheduled time. When disabled, no reports are sent. Idempotent: enabling an already enabled (or disabling an already disabled) automation does not error. WHEN TO CALL: Use when the user wants to activate, deactivate, pause, or resume an automation. Also called automatically after create_automation when the user confirms activation. Examples: 'Turn on automation X', 'Disable this automation', 'Pause the weekly report', 'Activate the automation I just created'. PREREQUISITES: Call list_automations to get the automation id.

toggle_automation

Top-performing posts and content ranked by engagement across SOCIAL MEDIA platforms only. Returns media/content data tables from social integrations: Instagram, Facebook, YouTube, LinkedIn, TikTok, Pinterest, and Threads. Does NOT include ads platforms or web analytics. WHEN TO CALL: Use when the user asks about their best posts, top content, or content performance. Examples: 'What were my best performing posts this month?', 'Show me top content across all social channels', 'Which posts got the most engagement?', 'What content performed best on Instagram?'. WHEN NOT TO CALL: - If the user asks about ADS campaigns or ad creatives → use get_campaign_summary instead. - If the user wants numeric KPIs (followers, reach) not post-level content → use get_performance_summary instead. - If the user wants a specific metric from one social platform → use get_metrics_data instead. PREREQUISITES: Call list_projects first to get the projectId.

get_top_content

Update an existing automation. PATCH-style: only provided fields are changed; omitted fields keep their current values. You can update: title, scheduleHour, notification channels, email recipients, WhatsApp settings, alertEmail, sourceIds, comparisonPeriod. NOTIFICATION CHANNELS: Pass notificationChannels to change how the report is delivered. Array of one or more: "email", "in-app", "whatsapp". When changing to include "email", make sure recipients are set (either already configured or passed in this call). When changing to include "whatsapp", make sure whatsappUrl is set. CRITICAL PARAMS — ASK WHEN AMBIGUOUS: - When the user says "change the email", ask whether they mean: alert email (failure alerts), recipient list (who receives the report), or both. Then pass only the relevant parameter(s). - alertEmail accepts ONLY ONE email. If the user wants multiple, tell them only one is allowed. - When the user says "send via WhatsApp", you need the whatsappUrl. If not provided, ask. WHEN TO CALL: Use when the user wants to modify an existing automation's settings. Examples: 'Change the automation time to 10am', 'Add another recipient', 'Update the alert email to X', 'Switch to WhatsApp delivery', 'Add in-app notifications', 'Change who receives the report'. PREREQUISITES: Call list_automations or get_automation first to get the automation id and current values.

update_automation

Update an existing KPI goal's target value and/or alert configuration. When targetValue is provided, creates a new goal period with the updated target starting from the current period boundaries. Alert settings can be toggled independently. CRITICAL PARAMS — ASK WHEN AMBIGUOUS: - If the user says "change the goal" without specifying a new target number, ask: "What should the new target value be?" WHEN TO CALL: Use when the user wants to modify an existing goal's target or alerts. Examples: 'Increase my Instagram follower goal to 15000', 'Change the target for my ads conversion goal', 'Update the KPI target', 'Enable alerts when the goal is reached'. PREREQUISITES: Call list_goals first to find the tracked_metric_id.

update_goal

Partially update an existing timeline event. PATCH-style: only provided fields are changed; omitted fields keep their current values. Never pass an empty string for content. CONTENT FORMATTING RULES (when updating content): The same HTML formatting rules from create_timeline_event apply here. When the user asks to update or improve event content, ALWAYS produce well-structured HTML: - Use <b> or <strong> for section headings and key terms - Use <ul>/<li> for bullet-point lists and <ol>/<li> for ordered/ranked items - Use <br> for line breaks between sections - Organize into logical sections (Summary, Analysis, Strengths, Weaknesses, Recommendations, etc.) - If the existing content is unstructured plain text and the user asks for any edit, take the opportunity to restructure the entire content into proper HTML format. Never produce a plain wall of text for analytical or descriptive events. WHEN TO CALL: Use when the user wants to modify an existing timeline event. Examples: 'Change the date of milestone X', 'Update the campaign launch note', 'Move this event to a different project', 'Link this timeline event to a report', 'Improve the formatting of this event'. PREREQUISITES: Call list_timeline_events or get_timeline_event first to find the event ID.

update_timeline_event

Update an existing webhook subscription by ID. PATCH-style: only provided fields are changed; omitted fields keep their current values. You can change the callback URL, event type, or project scope. Use clearProjectScope to make the webhook receive events for all projects. Valid event types: report_viewed, report_created, dashboard_created, automation_executed, control_goal_met, control_goal_not_met, timeline_milestone_added. WHEN TO CALL: Use when the user wants to modify an existing webhook's settings. Examples: 'Change webhook 123 URL to https://new.example.com/hook', 'Update webhook to listen for automation_executed', 'Scope webhook to project 5'. PREREQUISITES: Call list_webhooks first to get the webhook id.

update_webhook