AgencyAnalytics

Create a custom view for one client — a blended data table (the client's "Views" section) combining metrics from one or more connected data sources, e.g. a cross-platform ad spend table with Google Ads and Facebook Ads side by side. Listing existing views is browse_client_custom_views, NOT this tool. Describe the view in plain language via `prompt` (e.g. "a table of daily sessions and conversions from GA4 next to Google Ads spend") — the platform generates the column and data-source definition from the client's connected sources. You do NOT pass columns. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is created — the platform generates the view, renders a sample of it over the last 30 days, and returns the columns, data sources, sample rows, and a generatedView JSON block for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, adjust the prompt and call again (still confirmed=false). - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with confirmed=true AND generatedView set to EXACTLY the JSON block from the preview. Generation is not deterministic: echoing the block back is what guarantees the created view is the one the user approved. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, never treat the original request as pre-approval, and never set confirmed=true on the first call. Custom views must be enabled for the caller (plan/role feature) — the tool refuses with an explanation when they are not. Requires permission to update the client. Campaign-level only (clientId is required). Input: clientId (integer), prompt (string, max 2000 — the plain-language description), name (string, optional — overrides the generated view name, max 100), generatedView (JSON string — ONLY on the confirmed call, copied exactly from the preview), confirmed (boolean — leave false to preview; set true only after the user approves).

create_client_custom_view

Create a new user on YOUR OWN account (a teammate or a client login) and optionally send them the invite email. Call search_users FIRST to check the person does not already exist — a duplicate email is rejected. This creates account users; it does NOT create clients (campaigns) and does NOT email arbitrary addresses (create_email emails existing users). Fields: firstName, lastName, email, role ("staff" — a teammate; or "client" — a client-portal login). Access: clientIds (client ids from search_clients/browse_clients) grants restricted access to those clients — REQUIRED (at least one) when role=client, since a client user with no clients sees an empty portal. allClients=true (staff only, instead of clientIds) grants a standing pass to ALL clients INCLUDING ONES ADDED IN THE FUTURE — only use it when the user explicitly asks for access to everything, and it is only available when you have all-client access yourself. sendInvite (default true) controls whether the invite email is sent; creation alone never emails anyone, and the person cannot log in until they accept an invite. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is created — it returns the fully-resolved user (name, email, role, access, whether an email will be sent) for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, apply them and call again (still confirmed=false) to re-confirm. - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with the same arguments, confirmed=true and the previewToken the preview returned, to create. A confirm without that token, with different arguments, or after the clients or staff-seat count changed is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, never treat the original request as pre-approval, and never set confirmed=true on the first call. Creating users requires user-management permission, and staff seats may be capped by the plan — the tool refuses with an explanation when either applies. Input: firstName (string), lastName (string), email (string), role ("staff"/"client"), clientIds (integer[], optional — required for role=client), allClients (boolean, staff only, excludes clientIds), sendInvite (boolean, default true), confirmed (boolean — leave false to preview; set true only after the user approves), previewToken (string — only on the confirmed call, exactly as the preview returned it).

create_user

Run one AAQL read for one client and return the connector rows as CSV, followed by a `Totals:` section when the connector reports totals. Use those totals rather than summing the rows yourself. Use this for per-entity breakdown questions and raw exports. For trend-over-time questions prefer read_client_metrics, and for biggest-mover questions prefer read_client_metric_signals — both are far more token-efficient. Always call browse_tools first with the client id and a description of the data you need, pick the matching data_sources entry, then call this tool with that entry's provider, asset, fields, group_by and filter map (set start_date/end_date from the user's question). It runs immediately — derive the date range and filters from what the user asked rather than interrogating them. For an open-ended export request where the user has not said what they want ("dump my data"), present the available data sources as friendly options and let them pick before calling. integration_campaign_id is a single account ID. browse_tools returns one entry per source, with its filter pre-bound to one account and every connected account listed in its integration_campaigns map; to read another account, send the same filter with integration_campaign_id swapped for that map key. To read several accounts make ONE call per account rather than passing a list. A source read one account at a time is refused without integration_campaign_id when the client has several connected accounts on its provider, or none; with only one, that account is read. Send integration_campaign_id only when the entry's filter carries it: a source without it cannot be read for a chosen account, so the call is refused. A read scoped to one account opens with an `Integration account: Name (Account Identifier X, ID N)` line: name that account when reporting the figures, and pass N back as integration_campaign_id to read it again. Row limit defaults to 50 (max 500); paginate with offset for large reads. Do not invent provider/asset/field/filter values; this tool does not validate them against a known list and relies on browse_tools for valid inputs. Match each filter value to the shape declared in that data source's filter_types map — an "array" filter MUST be passed as a list (["Organic Search"]); a scalar value may be silently ignored, rejected, or not applied. Entity filter slots (campaign, ad_group, ad, adsquad, …) take the provider's ids from the source's id column (campaign_id, ad_group_id, …), not display names: {"campaign": ["1234567890"]}. Two exceptions take names: Google Ad Manager's slots, and the campaign slot of facebook-ads/campaigns, which searches campaign names. Input: clientId (integer), provider (string), asset (string), filters (object — start_date/end_date and any provider filter slots), fields (string[]; omit or [] for all fields of the asset), groupBy (string[]), sort ({field_name, direction}), limit (integer, default 50, max 500), offset (integer, default 0), testMode (boolean — serve the provider's demo data instead of the client's live data; only pass true when the user explicitly asks for testMode).

execute_read_tool

Fetch a single public web page or document by URL and return its readable text. Sends realistic desktop-browser headers so the page responds as it would for a human visitor. HTML is reduced to plain text (scripts, styles, and markup removed); JSON, plain-text, and XML responses are returned as-is. Binary, image, and other non-text content is not supported. Output is truncated to `maxLength` characters (default 30000). Provide one absolute http(s) URL — private, internal, and cloud-metadata addresses are blocked. Use to read an article, documentation page, or API/JSON endpoint the user names. For live web search use search_web instead; for AgencyAnalytics help articles use read_knowledge_base.

fetch_web

Fetch a client's AI Tracker analytics — how visible the brand is inside AI assistants' answers, broken down by a dimension. Returns one row per dimension value with the AI-visibility metrics: visibility (share of AI answers that mention the brand, 0-100), citations (cited URLs on the brand's own domain), position (the brand's rank among the brands an answer mentions), sentiment (0-100), citation_rate, and prompts (whichever the breakdown reports). Platforms tracked: ChatGPT, Google AI Overview, Google AI Mode, Claude, Perplexity, Gemini. Use this for AI-search / generative-engine-optimization questions — e.g. "which AI assistants mention us most?", "our visibility in ChatGPT vs Perplexity", "which prompts surface our brand", "which domains do AI answers cite for our topics", "AI visibility trend over the last 30 days". This is AI-answer visibility — NOT Google SERP keyword rankings or search volume (that is tracked keyword data — read it with read_client_rank_tracker; it tracks a keyword's rank position in classic search results). Pass an entityType. Only these provider/entityType combinations work: - agency-analytics-ai-tracker-v1: platform, prompt, topic, citation_domain, citation_url, by_date, by_date_platform, by_date_topic Breakdown families: visibility by platform/prompt/topic; citations by cited domain/URL; and time-series (by_date, by_date_platform, by_date_topic). The date-series breakdowns live here — read_client_metrics does NOT cover AI Tracker. The prompt breakdown also returns each prompt's query fan-out (fan_out_queries): the sub-queries the AI platform searched while answering it. Use it for "what did ChatGPT search for" and "query fan-out per prompt" questions. A prompt row's metrics and fan-out come from one fetch: its latest in the date range, or its last in the 365 days before the range. fetched_at names that fetch (date_last_fetched is the newest fetch overall, which can be later). An empty fetched_at means the prompt has no fetch in that window, so its fan-out and metrics are both empty. Multiple queries are separated by " | ". Fan-out coverage depends on the platform: ChatGPT and Gemini report it; Claude only when it chose to search the web for that prompt; Perplexity, Google AI Overview and Google AI Mode never do, so an empty fan_out_queries beside a fetched_at is expected on those platforms, not missing data. Metric availability differs slightly per breakdown (e.g. citation_rate is a citation-breakdown metric; prompts appears on topic/citation breakdowns) — columns a breakdown does not report are simply absent. If the campaign's prompts have never been fetched yet the tool returns no rows with an "initializing" note — AI Tracker is still collecting its first results, not an error. Before calling, determine provider availability using this priority order: 1. If `connected_providers` is in the system prompt and non-empty, use it — confirm the desired provider is listed there. 2. If `connected_providers` is in the system prompt but empty, decline without calling this tool — no providers are connected. 3. If `connected_providers` is absent but `search_clients` was called earlier in this conversation, use those cached results. 4. If none of the above, call `search_clients` first to resolve connected providers. If the provider is absent from whichever source applies, decline — unless testMode is explicitly requested by the user, in which case call the tool with testMode=true; testMode bypasses the integration connection check by design and returns demo data. Pass the provider slug directly ('agency-analytics-ai-tracker-v1') — no conversion needed.

read_client_ai_tracker

Fetch the computed output of a single client's custom metrics (formula-driven KPIs such as "Cost per Lead" or "ROAS") over a date range. Custom metrics combine multiple providers/fields through a user-defined formula — use this when the user asks about a named KPI that is not a raw provider metric. Provide `customMetricIds` to read specific metrics; omit it to read every custom metric available for the client (both campaign-level and account-level). Use browse_client_custom_metrics first to discover the available metric ids, names, and types. By default returns one aggregated value per metric (id, name, value, data_type, change_format). Set byDate=true to return a per-date time series (id, name, date, value) for each metric.

read_client_custom_metrics

Use this tool to fetch data for a specific dashboard. Requires client_id on every call. If the user already selected a dashboard by name (e.g. from browse_client_dashboards), go directly to step 2 — pass dashboard_id and section_name in the same call. Do not call step 1 first. Step 1 (no section_name) — only use when you do not yet know which dashboard the user wants: resolves a dashboard container by dashboard_id or dashboard_name and returns the list of available dashboards. Use this to present options to the user. Step 2 (with section_name) — fetches provider data for the named dashboard. Never fetch data across all dashboards at once. Always ask the user which dashboard they want before calling this step. Never refer to dashboards as "sections" when communicating with the user.

read_client_dashboard

Run a raw AAQL read query for one client and return the raw connector rows as CSV, followed by a `Totals:` section when the connector reports totals. Use those totals rather than summing the rows yourself. Use this for per-entity breakdown questions (ad campaigns, keywords, pages, calls, reviews, deals, orders, …) and for raw data exports — always after browse_client_data_sources has resolved the data source. For trend-over-time questions prefer read_client_metrics, and for biggest-mover questions prefer read_client_metric_signals — both are far more token-efficient. Workflow: call browse_client_data_sources with the client id and a description of the data you need first, pick the matching data_sources entry, then call this tool with that entry's provider, asset, fields, group_by, and filter map (set start_date/end_date from the user's question). It runs immediately — derive the date range and filters from what the user asked rather than interrogating them. For an open-ended export request where the user has not said what they want ("dump my data"), present the available data sources as friendly options and let them pick before calling. integration_campaign_id is a single account ID. browse_client_data_sources returns one entry per source, with its filter pre-bound to one account and every connected account listed in its integration_campaigns map; to read another account, send the same filter with integration_campaign_id swapped for that map key. To export from several accounts make ONE call per account rather than passing a list. A source read one account at a time is refused without integration_campaign_id when the client has several connected accounts on its provider, or none; with only one, that account is read. Send integration_campaign_id only when the entry's filter carries it: a source without it cannot be read for a chosen account, so the call is refused. A read scoped to one account opens with an `Integration account: Name (Account Identifier X, ID N)` line: name that account when reporting the figures, and pass N back as integration_campaign_id to read it again. Row limit defaults to 50 (max 500); paginate with offset for large exports. Do not invent provider/asset/field/filter values; this tool does not validate them against a known list and relies on browse_client_data_sources for valid inputs. Match each filter value to the shape declared in that data source's filter_types map — an "array" filter MUST be passed as a list (["Organic Search"]); A scalar value may be silently ignored, rejected, or not applied. Entity filter slots (campaign, ad_group, ad, adsquad, …) take the provider's ids from the source's id column (campaign_id, ad_group_id, …), not display names: {"campaign": ["1234567890"]}. Two exceptions take names: Google Ad Manager's slots, and the campaign slot of facebook-ads/campaigns, which searches campaign names. Input: clientId (integer), provider (string), asset (string), filters (object — start_date/end_date and any provider filter slots; integration_campaign_id is a single account id, make one call per account to export from several), fields (string[]; omit or [] for all fields of the asset), groupBy (string[]), sort ({field_name, direction}), limit (integer, default 50, max 500), offset (integer, default 0), testMode (boolean — serve the provider's demo data instead of the client's live data, so a source can be read without a live integration and without calling the provider's real API; only pass true when the user explicitly asks for testMode).

read_client_data_source

Read a client's Google Sheets spreadsheet — custom data agencies track outside their marketing platforms (budgets, leads, offline conversions, call logs, campaign trackers). Use browse_client_google_sheets first to find the spreadsheetId and tab names; spreadsheetId also accepts a full docs.google.com URL pasted by the user. Pass an entityType: - `rows` (default): the raw grid. Columns come back as letters (a, b, c, …) and the sheet's header row is returned as column LABELS in a note, not as a data row. Start here with a small limit to learn the sheet's shape. - `by_date`: chosen metric columns aggregated per date bucket, server-side — for trend questions over sheet data. Requires dateField (the column letter holding dates, e.g. 'A'), startDate, endDate, and fields (the metric column letters to aggregate, e.g. ["b","c"]). Optional aggregatorType: sum (default), avg, min, max. Percent-formatted columns are scaled to percentages and missing dates are zero-filled. by_date aggregates the tab's first 2,500 data rows (the module's bound) — on a longer sheet the series understates and the output note says so; narrow with the rows breakdown's date window to check a sheet's size first. by_date windows are limited to 10 years. The `rows` breakdown accepts an optional date window too — pass dateField + startDate + endDate together (all three or none) to keep only rows whose date column falls in the window. sheetName picks the tab; without it the FIRST tab is read. Column letters run a-cz (the sheet's first 104 columns); the date column may sit past that (e.g. 'DA'). This reads the sheet as the client shared it — NOT platform metrics (read_client_metrics) and NOT a data-source export (browse_tools); Google Sheets never appears in that catalog. If the sheet is not listed by browse_client_google_sheets the integration may still read it by URL — access is checked per file by Google. Before calling, determine provider availability using this priority order: 1. If `connected_providers` is in the system prompt and non-empty, use it — confirm the desired provider is listed there. 2. If `connected_providers` is in the system prompt but empty, decline without calling this tool — no providers are connected. 3. If `connected_providers` is absent but `search_clients` was called earlier in this conversation, use those cached results. 4. If none of the above, call `search_clients` first to resolve connected providers. If the provider is absent from whichever source applies, decline — unless testMode is explicitly requested by the user, in which case call the tool with testMode=true; testMode bypasses the integration connection check by design and returns demo data. Google Sheets reports as the provider slug 'google-sheets'. This tool takes no provider parameter.

read_client_google_sheets

Answer questions grounded in a client's uploaded documents — contracts, invoices, statements of work, proposals, briefs, meeting notes, reports — or the account's shared docs (brand guidelines, templates, policies). Use it whenever the answer lives in uploaded paperwork rather than live analytics: contract or retainer terms, invoice amounts or line items, scope and deliverables, goals/KPIs, or action items — even when the user never says "document", "file", or "upload". If a factual client question could plausibly be answered from their files, check here before answering from memory or saying you do not have it. Pass clientId to scope to one client (shared account-level docs are still included); omit it to search all accessible clients plus shared docs. Not for AgencyAnalytics platform how-to (use read_knowledge_base) or live metric/analytics data (use the analytics tools). Returns a grounded, source-cited answer, plus (when clientId is given) the client's own record — its company name and website — and a business_context list of the client's structured profile fields — company details, services, pricing, tone of voice, target audience, competitors, and any custom fields the agency maintains — which you should use and cite the same way as the document answer.

read_client_knowledge

Return a single client's biggest-moving metrics (trend signals), ranked by the magnitude of their percent change — biggest movers first, whether up or down. Use this to answer "what changed the most for this client?", "what are the biggest movers / drops / gains?", or "what's notable about this client right now?". To focus on only gains or only declines, pass direction=up or direction=down. These are pre-computed trend signals (period-over-period and year-over-year comparisons) refreshed once daily — NOT real-time. Each row carries the metric (variable), the comparison window (period_days), the comparison type (previous_period / year_over_year), current_value, comparison_value, absolute_change, percentage_change, and trend_direction. Signals span every connected provider at once, so no provider argument is needed and no provider-connection check is required. By default it returns the 30- and 90-day comparison windows (365-day comparisons are excluded as too noisy to be actionable) and both comparison types, so a single metric can appear up to ~4 times (once per window × comparison). Narrow the results with the optional filters: - period: restrict to one window (30 or 90 days). - comparisonType: restrict to previous_period or year_over_year. - direction: restrict to up, down, or flat movers. - minPercentageChangeMagnitude: only movers whose |percent change| meets this floor. - limit: max rows to return (default 50, max 200). For raw daily/monthly time series use read_client_metrics; for per-entity breakdowns use browse_tools followed by execute_read_tool. This tool is for surfacing the notable movements, not exporting full series.

read_client_metric_signals

Fetch aggregated time-series metrics for a single client over a date range, scoped to one connected integration provider. Returns one row per day or month — NOT one row per campaign, keyword, page, call, or traffic entity. Responses are limited to a maximum of 200 rows. Without integrationCampaignId, every figure is the total across all of the client's accounts on that provider, and the response names them on its first line; say so rather than attributing the figures to one account. To read one account, pass its integrationCampaignId: a key from the `integration_campaigns` map on this provider's browse_tools entries, or the ID the first line gives for it (not its Account Identifier, which is the provider's own id). Only a connected account can be read on its own; a disconnected one has no ID on that line, and its stored data is only in the total. fields narrows the columns: pass labels as they appear in an earlier response (provider.asset.field), or asset.field. Omit fields to get every field the provider stores. Only the assets in those labels store time series; a date-grouped browse_tools entry on any other asset cannot be read here. Use this for trend questions: "how has this client's overall performance changed over time?". For data broken down by entity (campaigns, ad groups, keywords, pages, calls, traffic sources, …), use browse_tools to pick the matching data source, then execute_read_tool. Columns are labelled provider.asset.field (e.g. amazon_ads.campaign_analytics.clicks): a provider can store the same field name on several assets, and each is its own column. The label's provider segment is not a valid `provider` value; pass the slug from the supported list (amazon-ads, not amazon_ads). Supported providers (30): adroll, amazon-ads, big-commerce-v1, bing-ads, bird-eye, callrail, facebook, facebook-ads, google-ad-manager-v1, google-analytics4, google-display-video360, google-local-services-ads, google-my-business, google-search-console, googleadwords, ground-truth-v1, high-level, instagram, linked-in, linked-in-ads, pinterest-ads, reddit-ads-v1, simpli-fi, spotify-ads, stack-adapt, tiktok-ads, tiktok-v1, twitter-ads, yelp-ads, youtube. Before calling, determine provider availability using this priority order: 1. If `connected_providers` is in the system prompt and non-empty, use it — confirm the desired provider is listed there. 2. If `connected_providers` is in the system prompt but empty, decline without calling this tool — no providers are connected. 3. If `connected_providers` is absent but `search_clients` was called earlier in this conversation, use those cached results. 4. If none of the above, call `search_clients` first to resolve connected providers. If the provider is absent from whichever source applies, decline — this tool has no testMode parameter and cannot bypass the connection check. To compare metrics across providers, call this tool once per provider and compare the responses — multi-provider scoping is not supported. Note: this tool no longer accepts `'all'` or any aggregate scoping; callers that previously used `'all'` must now call once per provider from `connected_providers` and combine results themselves.

read_client_metrics

Fetch a client's Rank Tracker data — where the client ranks in classic search results for the keywords the agency tracks, broken down by a dimension. Engines covered: Google, Google Mobile, Google Local, and Bing. Metrics per breakdown: ranking position, best position (_top), average position (_avg), cumulative movement (_change), how many keywords rank (_ranking_count), the ranking URL, monthly search volume, and competition. Use this for SEO keyword-ranking questions — e.g. "which keywords rank best?", "how have our rankings trended?", "how many keywords are on page one?", "which pages earn our rankings?", "why did this keyword drop?". LOWER IS BETTER for every position metric: rank 1 beats rank 40, and `ranking_average` is a mean SERP position, not a score. A rank that falls from 40 to 3 is an improvement. This is classic-SERP rank tracking — NOT AI-answer visibility (that is read_client_ai_tracker: mention rate and citations inside ChatGPT/Gemini/Claude/Perplexity answers) and NOT a live SERP lookup (that is search_web). It reads only the keywords this client has chosen to track. Pass an entityType — one of: keyword, date, tag, url, range, date_range, serp, date_serp, date_keyword. - `keyword` (default): one row per tracked keyword. - `date`: campaign rollup per day — the ranking trend. read_client_metrics does NOT cover Rank Tracker, so the trend lives here. - `tag` / `url`: keywords rolled up by tag label, or by the page that ranks. - `range` / `date_range`: position buckets (1-3, 4-10, 11-20, 21-50, 51+), overall or per day. - `serp` / `date_serp`: mean position per search engine, overall or per day. - `date_keyword`: ONE keyword's daily history — requires keywordId (get it from the `keyword` breakdown first). Do not pass keywordId to any other breakdown. Optional filters, each valid only on the breakdowns whose schema declares it — passing one elsewhere is REFUSED (it would be silently ignored, not applied): - `search`, on keyword / tag / url. `range`, on date / range / date_range. `serp`, on serp / date_serp. - `tags`, `primaryKeyword`, `searchLocationId`, `searchLanguageId` — every breakdown except date_keyword. - `tags` takes tag IDs, NOT labels: read them from the `tag` breakdown's tag_id column first, or the filter matches nothing. - `googleSerpFeatures` / `googleMobileSerpFeatures` — the date, range, date_range, serp and date_serp breakdowns only. These select on the SERP features a keyword holds ON THE END DATE of the range: membership only, so the position metrics still span the whole window. Setting both keeps a keyword matching EITHER engine, not both. - `dateInterval` — the date-grain breakdowns only. Rows are daily by default; `monthly` buckets by month, `automatic` derives it from the span (over 30 days becomes monthly). On the `keyword` breakdown the rows are not sorted purely by rank: the starred keyword is pinned first and keywords that have never ranked are pushed below ranked ones, so do not report row 1 as "the best-ranking keyword" — read the position values. Rankings are collected by a nightly job. If the campaign's rankers have not run yet the tool returns an "initializing" note rather than zeros. CAUTION on dates before collection started: the rollup returns a row for EVERY date in the window and fills gaps from the nearest measured day — forward from the last one, and where there is none, BACKWARD from the first later one. So a range beginning before this campaign's first ranker run shows those earlier dates carrying the first measured day's numbers, which look like real history. Treat the start of a long range with suspicion and prefer a window you know was tracked. Before calling, determine provider availability using this priority order: 1. If `connected_providers` is in the system prompt and non-empty, use it — confirm the desired provider is listed there. 2. If `connected_providers` is in the system prompt but empty, decline without calling this tool — no providers are connected. 3. If `connected_providers` is absent but `search_clients` was called earlier in this conversation, use those cached results. 4. If none of the above, call `search_clients` first to resolve connected providers. If the provider is absent from whichever source applies, decline — unless testMode is explicitly requested by the user, in which case call the tool with testMode=true; testMode bypasses the integration connection check by design and returns demo data. Rank Tracker reports as the provider slug 'rank-tracker'. This tool takes no provider parameter — it serves only Rank Tracker.

read_client_rank_tracker

Investigate ONE tracked keyword's disputed ranking: returns the evidence behind the recorded position for a single keyword + engine — NOT ranking numbers over time (that is read_client_rank_tracker). Use when a ranking looks wrong — "shows Not Found but we rank #1", a sudden unexplained drop, or disagreement with another rank tracker. Get the keywordId from read_client_rank_tracker's `keyword` breakdown first. Returns three labeled sections: 1. SETTINGS — what the ranking matcher ran under: keyword phrase, search location and language, the campaign's tracked URL with its URL-scope matching rule, Google 3-pack handling, CID enforcement, the configured Google Business Profile CIDs, refresh interval, and the last POSITIVE recorded position per engine (a spike-detection baseline that a Not Found reading does not clear — use read_client_rank_tracker's date_keyword breakdown for the latest reading). 2. STORED SERP — the capture behind the last recorded position: when it was fetched, how many fetch attempts it took, how many results it holds, and each notable result classified against the campaign settings with a verdict: matched / matched_not_rankable (the site IS on the SERP but inside a feature block — an ad, video, knowledge panel — that the ranking never counts) / same_domain_out_of_scope (the URL exists on the tracked domain but the URL scope excludes it) / cid_enforced_skip (URL matched but CID enforcement rejected it) / ignored_local / local_link_unresolvable (Google wrapped or omitted the link and no CID was configured) / no_match. Each result row carries TWO positions: serp_position (the provider's raw slot on the SERP) and counted_position (the rank the matcher records — only organic-rankable rows advance it, so ads and feature blocks make the two diverge). The recorded ranking corresponds to counted_position. An explicit line states when the tracked domain appears NOWHERE in the capture — with a valid capture, that is the SERP-volatility signature, not a bug. 3. KNOWN OUTAGES — registered provider outage windows for the engine, to correlate a disputed date with a period whose readings are excluded or masked. Read this BEFORE suggesting a refresh: a refresh OVERWRITES the stored capture, destroying the evidence under dispute. An empty or near-empty capture (very few results, none organic) indicates a degraded provider response — a data problem worth escalating, not a real ranking loss. This tool reads stored data only; it never triggers a fetch and consumes no credits.

read_client_rank_tracker_diagnostics

Use this tool to read a specific scheduled report for a client/campaign. Requires report_id or report_name. Step 1 (no section_name): resolves the report and returns its list of sections. Always call without section_name first to discover sections. Step 2 (with section_name): fetches provider data for one specific section. You must never fetch data across all sections at once — always ask the user which section they want before step 2. Requires client_id on every call.

read_client_report

Fetch a client's Site Auditor results — the technical site health found by AgencyAnalytics' own crawler: the audit score, which checks pass or fail (broken links, missing titles, slow pages, duplicate content, …), and per-page detail. Use this for site-health questions — e.g. "how healthy is the site?", "what technical SEO issues does it have?", "which pages are broken?", "is site health improving?", "why is this page failing?". Scores are 0-100 and HIGHER IS BETTER (the opposite of a SERP rank). Check severities, worst first: critical, error, warning. This tool READS finished crawls only — it cannot start, re-run, or stop a crawl. Every breakdown except `audits` and `history` reads ONE crawl, chosen by auditId: pass a task_id from the `audits` breakdown, or leave the default 'latest' (the newest crawl, even if it is still running or failed). To read last month's crawl, list `audits` first — do NOT pass startDate/endDate, which only the `history` breakdown accepts. Pass an entityType — one of: summary, tests, audits, history, pages, test_pages, page_detail. - `summary` (default): the chosen crawl's rollup — score, pages crawled, per-severity check counts, and the task_id that 'latest' resolved to. - `tests`: one row per audit check with failure counts — the main site-health table. Failed checks first. - `audits`: one row per crawl — status (initiating/processing/completed/error/cancelled), dates, and the error_message when a crawl failed. The place to find auditIds and to see WHY results look empty. - `history`: the audit score per crawl date — the trend. The only breakdown taking startDate/endDate (both required there). - `pages`: one row per crawled page, worst score first. Fetched live from the crawl provider, so it is slower than the other breakdowns. - `test_pages`: the pages failing ONE check — requires testId (get it from the `tests` breakdown first). Columns vary by check: link checks list the broken target, threshold checks carry the measured value. - `page_detail`: ONE page's per-check results — requires url (copy it exactly from the `pages` breakdown). Optional filters, each valid only on the breakdowns whose schema declares it — passing one elsewhere is REFUSED (it would be silently ignored, not applied): `search` on tests / pages; `statusCode` on pages; `showPassed` on tests. testMode (demo data) is REFUSED on the audits and test_pages breakdowns — their schemas author no demo data, so the empty result would look like a real finding. This is the platform's own crawler — NOT Google PageSpeed or Lighthouse scores (those are separate integrations read via browse_tools), NOT keyword rankings (read_client_rank_tracker), and NOT a live page fetch (fetch_web). If no audit has ever run the tool says so instead of returning zeros. A crawl still in progress returns partial rows plus a status note. An errored crawl can legitimately return no rows — check entityType=audits for its error_message before reporting "the site has no issues". Before calling, determine provider availability using this priority order: 1. If `connected_providers` is in the system prompt and non-empty, use it — confirm the desired provider is listed there. 2. If `connected_providers` is in the system prompt but empty, decline without calling this tool — no providers are connected. 3. If `connected_providers` is absent but `search_clients` was called earlier in this conversation, use those cached results. 4. If none of the above, call `search_clients` first to resolve connected providers. If the provider is absent from whichever source applies, decline — unless testMode is explicitly requested by the user, in which case call the tool with testMode=true; testMode bypasses the integration connection check by design and returns demo data. Site Auditor reports as the provider slug 'agency-analytics-auditor-4'. This tool takes no provider parameter — it serves only Site Auditor.

read_client_site_auditor

Search the AgencyAnalytics knowledge base for how-to articles and platform documentation.

read_knowledge_base

Queue a fresh ranking check for one or more of a client's tracked keywords — the same action as the Rank Tracker dashboard's Refresh button. Get keyword ids from read_client_rank_tracker entityType=keyword. TWO COSTS, disclose both: each keyword refresh consumes ONE refresh credit, and a refresh OVERWRITES the keyword's stored SERP capture — the evidence read_client_rank_tracker_diagnostics reads. When a ranking is under dispute, ALWAYS run the diagnostics BEFORE refreshing. Results are not immediate: the ranker tasks run in the background (minutes to hours), and fresh results are only visible in date ranges that INCLUDE TODAY. This queues data collection — it reads nothing. Rankings are read_client_rank_tracker; the evidence behind one ranking is read_client_rank_tracker_diagnostics. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is queued and no credit is spent — it returns the resolved keyword list with the credit cost for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, apply them and call again (still confirmed=false) to re-confirm. - ONLY once the user has explicitly approved in a LATER turn — after they have seen the preview — call again with the same arguments, confirmed=true and the previewToken the preview returned, to queue the refresh. A confirm without that token, with different keyword ids, or after a keyword changed is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf.

update_client_keyword_rankings

Look up ONE specific client by name fragment, brand token, or domain. Returns the single best-matching client (highest cosine similarity over `company`+`url`) with a `providers` field — use that to confirm a provider is connected before calling any entity tool. See the `query` parameter description for usage guardrails. If the user wants to list, browse, or enumerate clients — including "show all clients", "list my clients", "what clients do I have", or browsing by folder — use `browse_clients` instead.

search_clients

Search the teammates and contacts in your own AgencyAnalytics account by name or email. Use this to resolve a user's id before calling create_email or update_user, and to check a person does not already exist before create_user. It returns only users you have access to in your account. Natural for requests like "email John the report": first search_users for "John", then create_email to the matching user_id. Input: query (string — a name or email fragment, required), limit (integer, optional, default 10, max 50). Returns a JSON array of matching users, each with id, name, email, role, and status. status is "active", or "pending" for someone on the account who has not activated their login yet (they have not accepted an invite, or none was sent — pending does not mean an invite went out). Only active users can be emailed — for a pending user, say they have not activated their login rather than calling create_email. A pending user can still be updated with update_user, and is already on the account, so do not create them again. Pass the chosen user's id as create_email's user_id. If nothing matches, refine the query or ask the user to confirm the name.

search_users

Search the live web and return a compact keyword-research result set: organic results (position, title, link, domain, snippet), related searches, People Also Ask questions, and the answer box when present. Defaults to Google desktop. Set `engine=google_mobile` for the mobile SERP, or `engine=bing` for Bing (Bing returns no People Also Ask or answer box). Set `engine=google_local` for the Google local-finder (places) results — businesses with position, title, link, CID, rating, and address under `places_results`; no organic results, related searches, or People Also Ask. Use it to verify local/map rankings; always pass a `location`. Use for keyword research, SERP inspection, and competitor discovery. Not client-scoped — no clientId required. Results are token-heavy, so prefer one well-chosen query over looping many variations. Localize Google results with `location` (free-form, e.g. "Toronto, Ontario, Canada") or the `countryCode`/`language` codes. For Bing only `location` and `language` apply. If the response includes `showing_results_for`, Google rewrote the query — re-search with the exact phrase only if the original spelling matters.

search_web

Record user feedback explicitly directed at the AgencyAnalytics MCP server experience — its tools, ergonomics, or quality of results. Only call this when the user clearly intends to leave feedback (e.g. "I want to give feedback on the MCP", "this MCP is great", "the MCP is broken"). Do not call for incidental opinions about underlying data, individual integrations, or unrelated workflows.

create_mcp_feedback

Update an existing client (a campaign) on YOUR OWN account: rename it, change its website or timezone, move it into a client group, or take it out of its group. Resolve the client with search_clients or browse_clients FIRST and tell the user the CURRENT value you are about to change — the confirmation the user sees names only the new values. This edits clients; creating one is create_client, and listing them is browse_clients. Pass ONLY the fields that should change; anything omitted is left exactly as it is. Fields cannot be blanked — the platform ignores empty values — with one exception: pass removeFromGroup=true to take the client out of its group (never pass group="" for that). group is FIND-OR-CREATE — an unrecognised name makes a NEW group — so prefer a group name browse_clients has already shown you, and never pass group and removeFromGroup together. Changing the website has two side effects the user should know about: the client's cached logo is discarded and re-fetched for the new website, and Rank Tracker attributes search results to the client by its website from then on. Changing the name changes nothing else. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is changed — it returns each field that will change as "current → proposed" for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, apply them and call again (still confirmed=false) to re-confirm. - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with the same arguments, confirmed=true and the previewToken the preview returned, to update. A confirm without that token, with different arguments, or after the stored values changed is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, never treat the original request as pre-approval, and never set confirmed=true on the first call. Updating clients requires client-management permission — the tool refuses with an explanation when the caller does not have it. Demo clients accept only name and website changes. When nothing you passed differs from the stored values the tool says so and writes nothing. Client edits are rate-limited per user (50 per minute): on a "too many requests" failure, tell the user to wait a minute and retry — never loop. Input: clientId (integer), name (string, optional), website (string, optional), timezone (string, optional — IANA identifier), group (string, optional — find-or-create), removeFromGroup (boolean, optional), confirmed (boolean — leave false to preview; set true only after the user approves), previewToken (string — only on the confirmed call, exactly as the preview returned it).

update_client

Update an existing custom metric — rename it, change its description, data type or change format, or replace its formula. Resolve the metric with browse_client_custom_metrics FIRST and tell the user the CURRENT value you are about to change — the confirmation the user sees names only the new values. This edits metrics; creating one is create_client_custom_metric, and reading values is read_client_custom_metrics. Pass ONLY the fields that should change; anything omitted keeps its stored value. Fields cannot be blanked (the platform drops empty values), so a description cannot be cleared. A metric's scope cannot change: a client-level metric stays with its client and an account-level metric stays account-wide — to move one, delete and recreate it in the app. clientId is optional and only asserts scope: for a client-level metric it must be that client; omit it for an account-level metric. To replace the formula pass variables AND expression together, in the same STRUCTURED form create_client_custom_metric takes: variables are {ref, provider, asset, field, filters?} (discover provider/asset/field via browse_tools, group_by must include "date"; max 15, every variable used), expression is arithmetic over {ref} placeholders using only + - * / ( ) and numbers. The formula is replaced whole, never merged. Consequences to disclose: every report or dashboard widget, goal and KPI built on this metric changes with it, silently; changing changeFormat flips whether an increase counts as good or bad for every KPI and goal on it. After a confirmed formula change the tool recomputes the metric over the last 30 days and reports the value (skipped for account-level metrics) — a failed computation does not undo the update. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is changed — it returns each field that will change as "current → proposed" for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, apply them and call again (still confirmed=false) to re-confirm. - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with the same arguments, confirmed=true and the previewToken the preview returned, to update. A confirm without that token, with different arguments, or after the stored metric changed is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, never treat the original request as pre-approval, and never set confirmed=true on the first call. Custom metrics must be enabled for the account, and account-level metrics can only be edited by an admin or all-access staff user — the tool refuses with an explanation otherwise. When nothing you passed differs from the stored definition it says so and writes nothing. Metric edits are rate-limited per user (50 per minute): on a "too many requests" failure, tell the user to wait a minute and retry — never loop. Input: customMetricId (integer), clientId (integer, optional scope check), name (string, optional), description (string, optional), dataType ("integer"/"float"/"currency"/"percent", optional), changeFormat ("percent"/"percent_inverted", optional), variables (array of variable objects, optional — with expression), expression (string, optional — with variables), confirmed (boolean — leave false to preview; set true only after the user approves), previewToken (string — only on the confirmed call, exactly as the preview returned it).

update_client_custom_metric

Update an existing custom view (a blended data table in the client's "Views" section) — rename it, rename, remove or re-aggregate its columns, or change its columns from a plain-language request. Resolve the view with browse_client_custom_views FIRST. Creating a view is create_client_custom_view; listing views is browse_client_custom_views. - To RENAME the view, pass name only. The columns stay exactly as they are. - To RENAME, REMOVE or RE-AGGREGATE columns, pass columnEdits: a list of edits applied in order, each naming its column exactly as the view currently has it, even if an earlier edit renames it — {"op": "rename", "column": "Spend", "to": "Cost"}, {"op": "remove", "column": "Clicks"}, {"op": "aggregate", "column": "CTR", "aggregate": "avg"} (sum, avg, min or max; value columns only). Everything else about each column stays as it is. A new name may not be one any column has now (so no swaps) or contain a backtick, and the view keeps at least one dimension column. Views with computed columns cannot be edited this way. Never combine columnEdits with prompt. - To CHANGE COLUMNS any other way, pass prompt with the change in plain language (e.g. "add a CTR column", "show cost as an average"). The platform regenerates the view from its stored definition plus your request — it is regenerated, not patched, so review every column in the preview. The view keeps its name unless you also pass name. - Widgets find a view's columns BY NAME. A widget that shows one column, such as a stat or a chart, goes blank when that column is removed or renamed; a table shows a renamed column under its new name and drops a removed one. So only remove or rename a column the USER asked to. The tool refuses a regeneration that drops or renames a column unless its current name is in removeColumns — list it only when the user asked to remove or rename that column, or to stop reading a data source in it. - Views with computed columns or columns that calculate their value from a formula, views that read more than 20 data sources, a filtered source (one connected account) or a source not grouped by exactly one dimension, and views whose stored column names or data sources repeat cannot be regenerated; rename them here or edit them in the app's view editor. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is changed — it returns each change as "current → proposed" (for a prompt: the column changes, a sample of the new view over the last 30 days, and a generatedView JSON block). Relay that summary verbatim and END YOUR TURN. - If the user wants changes, adjust and call again (still confirmed=false). - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with the same arguments plus confirmed=true, and for a prompt change generatedView set to EXACTLY the JSON block from the preview; for a rename or columnEdits, previewToken set to exactly the token the preview returned. A confirm that differs from its preview, or follows a change to the stored view, is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, never treat the original request as pre-approval, and never set confirmed=true on the first call. Custom views must be enabled for the caller, editing needs report permissions and permission to update the client, and an account-level view (shown on every client) can only be edited by an admin or all-access staff user — the tool refuses with an explanation otherwise. When nothing would change it says so and writes nothing. View edits are rate-limited per user (50 per minute): on a "too many requests" failure, tell the user to wait a minute and retry — never loop. Input: customViewId (integer), clientId (integer — the client the view was listed for), name (string, optional, max 100), columnEdits (array of edits, optional), prompt (string, optional, max 1000), removeColumns (array of current column names, optional — only with prompt), generatedView (JSON string — ONLY on the confirmed prompt call, copied exactly from the preview), previewToken (string — ONLY on a confirmed call without prompt, exactly as the preview returned it), confirmed (boolean — leave false to preview; set true only after the user approves).

update_client_custom_view

Update an existing user on YOUR OWN account — their name, email, and which clients they can see. Resolve the userId with search_users first. This updates account users (teammates and client logins); it does NOT update clients/campaigns (that is update_client). Fields: firstName, lastName, email. An email change replaces the user's login: no verification email is sent and they are not signed out. A user's role cannot be changed. Client access: addClientIds / removeClientIds (client ids from search_clients/browse_clients) adjust the user's current access — the tool reads what they have now, applies your additions and removals, and writes the resulting list, so you never send the full set. allClients=true (staff users only) replaces their access with a standing pass to ALL clients INCLUDING ONES ADDED IN THE FUTURE (only available when you have all-client access yourself); allClients=false switches a user off that standing pass and needs addClientIds naming the clients they should keep, and also needs all-client access yourself, since everything left off that list is taken away. Pass only what should change — anything you omit is left exactly as it is. If every value you pass already matches what is stored, nothing is written and the tool says so. This tool cannot deactivate anyone or change passwords — those are done in the app. This tool runs in TWO steps. ALWAYS begin with confirmed=false — a first call with confirmed=true is a protocol violation, even when the user's request sounds pre-approved: - FIRST call it with confirmed=false (the default). Nothing is written — it returns each change as current → proposed, plus the resulting client access, for the user to approve. Relay that summary verbatim and END YOUR TURN. - If the user wants changes, apply them and call again (still confirmed=false) to re-confirm. - ONLY after the user has REPLIED with explicit approval — a real message that arrives after they have seen the preview — call again with the same arguments, confirmed=true and the previewToken the preview returned, to write. A confirm without that token, with different arguments, or after the user's stored details or access changed is refused: preview again. The preview and the confirmed=true call must NEVER happen in the same turn. Never approve on the user's behalf, and never set confirmed=true on the first call. The platform decides who may update whom; the tool refuses with its reason before the preview. The account's admin cannot be updated from here, except that the admin may change their own email from Agency AI in the app, not through this connection; nobody else can update themselves (change your own details in your account settings). Input: userId (integer, required), firstName (string), lastName (string), email (string), addClientIds (integer[]), removeClientIds (integer[]), allClients (boolean, staff targets only), confirmed (boolean — leave false to preview; set true only after the user approves), previewToken (string — only on the confirmed call, exactly as the preview returned it).

update_user