The Agency Analytics MCP connector routes your AI agent's tool calls to Agency Analytics's own MCP server through Scalekit. Each user signs in to Agency Analytics once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 39 tools.
- Tools
- 39
- What they doRead · write · destructive
- 17 · 21 · 117 read21 write1 destructive
- Users sign in with
- OAuth
- OAuth app
- Scalekit's or your own
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Agency Analytics MCP connection
In AgentKit > Connections, create an Agency Analytics MCP connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Scalekit credentials are available for Agency Analytics MCP server, so you don't need to register an OAuth app.
Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'agencyanalyticsmcp'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Agency Analytics MCP:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'agencyanalyticsmcp_browse_client_custom_metrics',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "agencyanalyticsmcp"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Agency Analytics MCP:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="agencyanalyticsmcp_browse_client_custom_metrics",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user signs in once. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolagencyanalyticsmcp_browse_client_custom_metricsList the custom metrics available for a single client — both campaign-level and account-level — so you can discover which formula-driven KPIs exist (e.g.Read-onlyBrowseClientCustomMetrics
List the custom metrics available for a single client — both campaign-level and account-level — so you can discover which formula-driven KPIs exist (e.g. 'Cost per Lead', 'ROAS'). Returns one row per custom metric with its id, name, data_type, change_format, scope, formula, and description. Use the returned ids with read_client_custom_metrics to fetch computed values.
Inputs
clientIdinteger- The client (campaign) ID.
agencyanalyticsmcp_browse_client_dashboardsList all dashboards for a client/campaign.Read-onlyBrowseClientDashboards
List all dashboards for a client/campaign. Returns paginated dashboards (10 per page). If the user does not see what they are looking for, increment page and call again. Requires client_id on every call.
Inputs
client_idinteger- The client (campaign) ID. Required on every call.
pageinteger- Page number for pagination (default 1).
agencyanalyticsmcp_browse_client_data_sourcesDiscover connected providers and available metric data sources for a campaign.Read-onlyBrowseClientDataSources
Discover connected providers and available metric data sources for a campaign. Pass message (the user's question) to filter returned data sources to only those relevant to the question. Returns providers (connected slugs) and data_sources (AAQL data source definitions with available fields and pre-hydrated filters).
Inputs
clientIdinteger- No description.
messagestring- A description of the data you need.
requireDateRangeboolean- No description.default
false testModeboolean- No description.default
false
agencyanalyticsmcp_browse_client_reportsList all reports for a client/campaign.Read-onlyBrowseClientReports
List all reports for a client/campaign. Use this when no specific report was named and you need to present options or pick the most relevant one. Requires client_id on every call.
Inputs
client_idinteger- The client (campaign) ID. Required on every call.
agencyanalyticsmcp_browse_clientsBrowse or enumerate clients.Read-onlyBrowseClients
Browse or enumerate clients. Two modes: Folder mode (omit groupId) returns all folders with their client counts plus ungrouped clients. Drill-down mode (groupId provided) returns all clients inside the specified folder. Results are paginated via limit and offset.
Inputs
groupIdinteger- Folder ID to drill into. Omit to list all folders and ungrouped clients.
limitinteger- Maximum number of items to return (default 50, max 200).default
50 offsetinteger- Zero-based pagination offset (default 0).default
0 searchstring- Optional text filter applied to client name or URL.
statusstring- Optional status filter — e.g. "active" or "inactive". Omit to return all statuses.
agencyanalyticsmcp_fetch_webFetch a single public web page or document by URL and return its readable text.Read-onlyFetchWeb
Fetch a single public web page or document by URL and return its readable text. HTML is reduced to plain text; JSON, plain-text, and XML responses are returned as-is. Output is truncated to maxLength characters (default 30000).
Inputs
urlstringrequired- Absolute http(s) URL to fetch, e.g. 'https://example.com/article'.
maxLengthinteger- Maximum characters of extracted text to return. Defaults to 30000; clamped to [1000, 100000].
agencyanalyticsmcp_read_client_ai_trackerFetch a client's AI Tracker analytics — how visible the brand is inside AI assistants' answers (ChatGPT, Google AI Overview, Google AI Mode, Claude, Perplexity, Gemini), broken down by a dimension.Read-onlyReadClientAiTracker
Fetch a client's AI Tracker analytics — how visible the brand is inside AI assistants' answers (ChatGPT, Google AI Overview, Google AI Mode, Claude, Perplexity, Gemini), broken down by a dimension. Returns one row per dimension value with AI-visibility metrics (visibility, citations, position, sentiment, citation_rate, prompts). This is AI-answer visibility — NOT Google SERP keyword rankings (use read_client_keywords for that). Supported providers (1): agency-analytics-ai-tracker-v1.
Inputs
clientIdinteger- The client (campaign) ID.
endDatestring- End date in YYYY-MM-DD format.
entityTypestring- The dimension to break down AI visibility by.one of
platformprompttopiccitation_domaincitation_urlby_dateby_date_platformby_date_topicdefaultplatform limitinteger- Maximum rows to return (default 50).default
50 providerstring- The AI Tracker provider slug.one of
agency-analytics-ai-tracker-v1 startDatestring- Start date in YYYY-MM-DD format.
testModeboolean- Set to true to return sample data without a live API call.default
false
agencyanalyticsmcp_read_client_custom_metricsFetch the computed output of a single client's custom metrics (formula-driven KPIs such as 'Cost per Lead' or 'ROAS') over a date range.Read-onlyReadClientCustomMetrics
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. Provide customMetricIds to read specific metrics; omit it to read every custom metric available for the client. Use browse_client_custom_metrics first to discover the available metric ids.
Inputs
byDateboolean- Set to true to return values broken down by date.default
false clientIdinteger- The client (campaign) ID.
customMetricIdsarray- List of custom metric IDs to fetch. Omit to fetch all.
endDatestring- End date in YYYY-MM-DD format.
startDatestring- Start date in YYYY-MM-DD format.
agencyanalyticsmcp_read_client_dashboardFetch data for a specific dashboard.Read-onlyReadClientDashboard
Fetch data for a specific dashboard. Step 1 (no section_name): resolves a dashboard container by dashboard_id or dashboard_name and returns the list of available dashboards. Step 2 (with section_name): fetches provider data for the named dashboard. Requires client_id on every call.
Inputs
client_idinteger- The client (campaign) ID. Required on every call.
dashboard_idinteger- ID of the dashboard to fetch.
dashboard_namestring- Name of the dashboard to fetch.
end_datestring- End date in YYYY-MM-DD format.
section_namestring- Name of the section to fetch data for. Omit for Step 1 (list sections).
start_datestring- Start date in YYYY-MM-DD format.
agencyanalyticsmcp_read_client_data_sourceRun a raw AAQL read query for one client and return the raw connector rows as CSV.Read-onlyReadClientDataSource
Run a raw AAQL read query for one client and return the raw connector rows as CSV. Use this ONLY when the user explicitly asks to export raw data. For normal analytics use the entity and metric tools — they are far more token-efficient.
Inputs
assetstring- No description.
clientIdinteger- No description.
fieldsarray- No description.
filtersobject- No description.
groupByarray- No description.
limitinteger- No description.default
50 offsetinteger- No description.default
0 providerstring- No description.
sortobject- One field-to-direction pair, e.g. {"clicks": "desc"}. Directions: asc, desc. One clause only.
testModeboolean- No description.default
false
agencyanalyticsmcp_read_client_knowledgeAnswer 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).Read-onlyReadClientKnowledge
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). Pass clientId to scope to one client; omit it to search all accessible clients plus shared docs. Returns a grounded, source-cited answer.
Inputs
clientIdinteger- Optional. The client (campaign) whose documents to search. Omit to search across all accessible clients plus shared account-level documents.
promptstring- The natural-language question about the uploaded documents.
agencyanalyticsmcp_read_client_metricsFetch aggregated time-series metrics for a single client over a date range, scoped to one connected integration provider.Read-onlyReadClientMetrics
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 or keyword. Use this for trend questions. Responses are limited to a maximum of 200 rows. Supported providers: adroll, bing-ads, facebook, facebook-ads, google-analytics4, 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, twitter-ads.
Inputs
clientIdinteger- No description.
endDatestring- No description.
fieldsarray- Columns to return, as provider.asset.field or asset.field. Omit for every field.
incrementstring- No description.one of
daymonthdefaultday integrationCampaignIdinteger- One account to read, from the integration_campaigns map on browse_tools. Omit for the total across all of the client's accounts on the provider.
providerstring- No description.one of
adrollamazon-adsbig-commerce-v1bing-adsbird-eyecallrailfacebookfacebook-adsgoogle-ad-manager-v1google-analytics4google-display-video360google-local-services-adsgoogle-my-businessgoogle-search-consolegoogleadwordsground-truth-v1high-levelinstagramlinked-inlinked-in-adspinterest-adsreddit-ads-v1simpli-fispotify-adsstack-adapttiktok-adstiktok-v1twitter-adsyelp-adsyoutube startDatestring- No description.
agencyanalyticsmcp_read_client_reportRead a specific scheduled report for a client/campaign.Read-onlyReadClientReport
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. Step 2 (with section_name): fetches provider data for one specific section. Requires client_id on every call.
Inputs
client_idinteger- No description.
end_datestring- No description.
include_widgetsboolean- When true, the step-1 section listing includes a compact widget summary plus a `uuid` for each section and widget, so you can reference an existing section/widget when editing it.
report_idinteger- No description.
report_namestring- No description.
section_namestring- No description.
start_datestring- No description.
agencyanalyticsmcp_read_knowledge_baseSearch the AgencyAnalytics knowledge base for how-to articles and platform documentation.Read-onlyReadKnowledgeBase
Search the AgencyAnalytics knowledge base for how-to articles and platform documentation. Use this to answer questions about how to use the AgencyAnalytics platform itself.
Inputs
searchstring- Search term to look up in the knowledge base.
agencyanalyticsmcp_search_clientsLook up ONE specific client by name fragment, brand token, or domain.Read-onlySearchClients
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. If the user wants to list, browse, or enumerate clients — use `browse_clients` instead.
Inputs
querystringrequired- A substantive client identifier the user actually provided — a name fragment, brand token, or domain (e.g. "acme", "shopify", ".io"). NOT a search engine query. Empty, whitespace-only, single-character, or generic-word queries will be rejected.
agencyanalyticsmcp_search_usersSearch the teammates and contacts in your own AgencyAnalytics account by name or email.Read-onlySearchUsers
Search the teammates and contacts in your own AgencyAnalytics account by name or email. Returns users you are allowed to contact with id, name, email, and role.
Inputs
querystringrequired- Required. A name or email fragment to search for, e.g. "john", "smith", "john@acme.com".
limitinteger- Optional. Maximum number of users to return (default 10, max 50).default
10
agencyanalyticsmcp_search_webSearch 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.Read-onlySearchWeb
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. Use for keyword research, SERP inspection, and competitor discovery. Not client-scoped — no clientId required.
Inputs
querystringrequired- The search query — a keyword phrase to research.
countryCodestring- Optional two-letter Google country code (gl), e.g. "ca". Takes precedence over the country resolved from location. Google engines only — ignored when engine=bing.
enginestring- Search engine to use: "google" (desktop, default), "google_mobile", "google_local" (local-finder places results), or "bing".one of
googlegoogle_mobilegoogle_localbing languagestring- Optional language code (hl for Google, bing_language for Bing), e.g. "en". Takes precedence over the language resolved from location.
limitinteger- Maximum organic results to return (1-100). Defaults to 10.
locationstring- Optional free-form location to localize results, e.g. "Toronto, Ontario, Canada". For Google, the search domain, country, and language are resolved from it automatically. For Bing, the location string is passed through directly.
agencyanalyticsmcp_browse_client_custom_viewsList the custom views available for a single client — both campaign-level and account-level.WriteBrowse Client Custom Views
List the custom views available for a single client — both campaign-level and account-level. A custom view is a blended data table (the client section's "Views"): named columns mapped onto metrics from one or more connected data sources, e.g. a cross-platform ad spend table. Returns one row per view with its `id`, `name`, `scope` (campaign or account), the column names with their roles (`Date:dimension | Spend:value`), and the data sources it blends (readable `provider.asset` labels). This is the discovery step — it lists definitions, it does not compute any values. Creating a new view is create_client_custom_view and changing one is update_client_custom_view, NOT this tool.
Inputs
clientIdinteger- No description.
agencyanalyticsmcp_browse_client_google_sheetsList the Google Sheets spreadsheets a client's integration can read, or one spreadsheet's tabs.WriteBrowse Client Google Sheets
List the Google Sheets spreadsheets a client's integration can read, or one spreadsheet's tabs. The discovery step before read_client_google_sheets. Two modes: - No spreadsheetId: one row per reachable spreadsheet (id, name). The list is scoped by what the client granted during setup — an empty list means no spreadsheets are shared with the integration, NOT that the client has no spreadsheets. In that case ask the user for the spreadsheet's URL and pass it to read_client_google_sheets directly. - spreadsheetId set (an id from mode 1, or a full docs.google.com URL): one row per tab, in sheet order. The FIRST tab is what a read without sheetName targets. Column discovery is deliberately not here: call read_client_google_sheets with entityType=rows and a small limit — its metadata names each column's header label. Google Sheets reports as the provider slug 'google-sheets' in connected-provider lists. This tool takes no provider parameter.
Inputs
clientIdinteger- No description.
spreadsheetIdstring- A spreadsheet id (or full URL) to list tabs for. Omit to list the reachable spreadsheets.
agencyanalyticsmcp_browse_toolsFind the AgencyAnalytics data source that answers a per-entity or export question about one client.WriteBrowse Tools
Find the AgencyAnalytics data source that answers a per-entity or export question about one client. Breakdowns by an entity (ad campaigns, ad-platform keywords, pages, traffic sources, calls, reviews, deals, orders, …) and raw exports are AAQL data sources, read with execute_read_tool. For trend-over-time questions prefer read_client_metrics, and for biggest-mover questions read_client_metric_signals — both are far more token-efficient. Tracked keyword rankings (Rank Tracker), site audits, AI visibility, Google Sheets and computed custom metric values are not listed here; they have their own tools. Custom view definitions are listed by browse_client_custom_views. Pass clientId and message (a description of the data you need) to get the providers connected to the client and the data sources relevant to the question. Omit or pass an empty message to return every data source. A data_source whose filter carries integration_campaign_id can be read through any of the client's connected accounts for that provider, and lists them in integration_campaigns (a map of id to name, named for the filter slot you send them in). The filter comes pre-bound to one of them. To read a different account, send that same filter to execute_read_tool with integration_campaign_id swapped for that id — there is ONE data_source per source, not one per account, so a missing per-account copy is not a missing account. Ask which account is meant rather than guessing when the question names none and they would answer differently. When writing for a person, call these accounts (or the provider's own word: ad account, property, profile, location, channel) and name them with the map's values. "Integration campaign" is an internal column name — do not use it in anything a user reads, and do not show the numeric ids. A data_source with no integration_campaigns map cannot be scoped to one account, so its figures must not be attributed to a particular one. Each data_sources entry carries provider, asset, group_by, field (the available fields), a filter map (slot -> pre-hydrated value) and a filter_types map (slot -> data type: array, string, integer, date, boolean, …). Pass those to execute_read_tool as provider, asset, groupBy, fields and filters. Send each filter value in the shape its filter_types entry declares — in particular an "array" filter (e.g. channel, event, source_medium) MUST be a list (["Organic Search"]); a scalar is silently ignored. Entity 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: ["1234567890"]. Two exceptions take names: Google Ad Manager's slots, and the campaign slot of facebook-ads/campaigns, which searches campaign names. Set requireDateRange to true to return only data sources that accept a start_date/end_date filter — use it when the question is scoped to a time window (a trend, a month, a comparison) so snapshot-only sources are excluded. Date-less id-lookup sources are still returned when a kept source requires a parent id (e.g. form_id) that only they can supply. Set testMode to true ONLY when the user explicitly asks for demo/test data: discovery then spans the whole connector catalog instead of the client's connected integrations, so a demo read (execute_read_tool with testMode=true) can be built even when nothing is connected. Always pass message with it. Input: clientId (integer — from search_clients), message (string — a description of the data you need), requireDateRange (boolean, default false), testMode (boolean, default false).
Inputs
clientIdinteger- No description.
messagestring- A description of the data you need.
requireDateRangeboolean- No description.default
false testModeboolean- No description.default
false
agencyanalyticsmcp_create_clientCreate a new client (a campaign) on YOUR OWN account.WriteCreate Client
Create a new client (a campaign) on YOUR OWN account. Call search_clients FIRST — client names are not unique, so a second "Acme Co" will be created silently if one already exists. Listing existing clients is browse_clients, NOT this tool. This creates clients; creating account users is create_user, and creating a report section is create_client_report_section. Fields: name is the company name, website is their site (REQUIRED — a client cannot be worked with until it has one). timezone is an IANA identifier such as America/Toronto and defaults to the account's when omitted. group is the client group the app shows as a folder, and is FIND-OR-CREATE — an unrecognised name makes a NEW group, so pass one only when the user named it, and prefer a name browse_clients has already shown you. BILLING — read this before calling. If the account is already at its client limit, this tool RAISES the plan's client allowance, which CHARGES the customer, and then creates the client. It does not ask a second time. The tool result says so whenever it happens: relay that note to the user in full and never omit or soften it. Changing billing requires billing permission, so a caller without it is refused at the limit (creating a client below the limit needs only client-management permission). Accounts that cannot self-serve — on trial, cancelled, paused, with an unpaid invoice, or already at the plan's maximum — are refused with the reason, as is a create at the limit whose price cannot be confirmed. 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 client, and the billing consequence when there is one, 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 client count or the price 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 clients requires client-management permission — the tool refuses with an explanation when the caller does not have it. At most 50 PAID clients can be added per hour per user — that is, creates that raise the plan because the account is at its limit. Creates that fit inside the current plan are not counted. If the cap is reached while working through a list or an uploaded file, tell the user how many were created, that the rest were not, and when the remainder can be added. Input: name (string), website (string), timezone (string, optional — defaults to the account's), group (string, optional — find-or-create), 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).
Inputs
namestringrequired- The client's company name (max 150 chars). Not unique — check search_clients first.
websitestringrequired- The client's website, e.g. acme.com. Required — a client cannot be worked with without one.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is created. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false groupstring- Client group name, shown as a folder in the app. FIND-OR-CREATE: an unrecognised name creates a new group. Omit to leave ungrouped.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
timezonestring- IANA identifier such as America/Toronto. Defaults to the account's timezone when omitted.
agencyanalyticsmcp_create_client_custom_metricCreate a custom metric — a formula-driven KPI (like "Cost per Lead" or a blended ROAS) computed from connected integration metrics.WriteCreate Client Custom Metric
Create a custom metric — a formula-driven KPI (like "Cost per Lead" or a blended ROAS) computed from connected integration metrics. Pass clientId for a single client's metric; OMIT clientId to create an ACCOUNT-LEVEL metric that appears on EVERY client's dashboard (each client computes its own slice; requires an admin or all-access staff caller). Reading existing custom metrics is browse_client_custom_metrics / read_client_custom_metrics, NOT this tool. The formula is passed as STRUCTURED parts — never as a raw variable string: - variables: the metrics the formula uses. Each is {ref, provider, asset, field, groupBy?, filters?} — discover valid provider/asset/field combinations via browse_tools (pick sources whose group_by includes "date"). ref is a short handle like "spend" or "leads" (letters/digits/underscores). Optional filters narrow a variable (e.g. one campaign); a filter value may be a scalar or a list (list = "any of these values"). At most 15 variables; each must be used in the expression. - expression: arithmetic over {ref} placeholders, e.g. "({spend} / {leads}) * 100". Allowed: + - * / ( ) and numbers. Nothing else — no functions, no comparisons. dataType is REQUIRED and must be chosen deliberately: currency for money (cost per lead), percent for rates, float/integer for counts and plain numbers — a wrong type renders wrong everywhere the metric appears. changeFormat is percent (default; up = good) or percent_inverted (up = bad, e.g. cost metrics). After a confirmed create the tool immediately computes the metric over the last 30 days and reports the value — the server does NOT validate arithmetic, so this is where a broken formula (divide-by-zero and the like) surfaces. A failed computation does not undo the creation; the response says so and the metric can be fixed or deleted in the app. Account-level metrics compute per client, so that verification is skipped for them — check any client's dashboard or read_client_custom_metrics instead. 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 metric (name, type, the formula in plain provider.asset.field variables, and a warning if a same-named metric already exists) 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 a same-named metric appeared 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 (plan feature) — the tool refuses with an explanation when they are not. Input: clientId (integer — omit for an account-level metric), name (string), description (string, optional), dataType ("integer"/"float"/"currency"/"percent"), changeFormat ("percent"/"percent_inverted", default percent), variables (array of variable objects as above), expression (string), 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).
Inputs
dataTypestringrequired- REQUIRED, chosen deliberately: currency for money, percent for rates, integer/float for counts.one of
integerfloatcurrencypercent expressionstringrequired- Arithmetic over {ref} placeholders, e.g. "({spend} / {leads}) * 100". Only + - * / ( ) and numbers.
namestringrequired- The custom metric display name (max 128 chars).
variablesarrayrequired- The metrics the formula uses. Max 15; every variable must appear in the expression.
changeFormatstring- percent = up is good (default); percent_inverted = up is bad (cost metrics).one of
percentpercent_inverteddefaultpercent clientIdinteger- The client to create the metric for. OMIT to create an account-level metric shown on every client dashboard (admin / all-access staff only).
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is created. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false descriptionstring- Optional description (max 255 chars).
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
agencyanalyticsmcp_create_client_custom_viewCreate 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.WriteCreate Client Custom View
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).
Inputs
clientIdintegerrequired- No description.
promptstringrequired- Plain-language description of the view to create (max 2000 chars).
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is created. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false generatedViewstring- ONLY on the confirmed call: the generatedView JSON block from the preview, copied EXACTLY. Guarantees the created view matches the approved preview.
namestring- Optional view name override (max 100 chars).
agencyanalyticsmcp_create_mcp_feedbackRecord user feedback explicitly directed at the AgencyAnalytics MCP server experience — its tools, ergonomics, or quality of results.WriteCreateMcpFeedback
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 about the MCP.
Inputs
messagestringrequired- The user's feedback in their own words. 1-2000 characters.
sentimentstringrequired- Overall sentiment of the feedback.one of
positivenegative
agencyanalyticsmcp_create_userCreate a new user on YOUR OWN account (a teammate or a client login) and optionally send them the invite email.WriteCreate User
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).
Inputs
emailstringrequired- The new user's email address. Must not already exist — check with search_users first.
firstNamestringrequired- The new user's first name (max 100 chars).
lastNamestringrequired- The new user's last name (max 100 chars).
rolestringrequired- staff = a teammate; client = a client-portal login (requires clientIds).one of
staffclient allClientsboolean- Staff only, instead of clientIds: standing access to ALL clients, including ones added in the future. Only when explicitly requested.default
false clientIdsarray- Client ids (from search_clients/browse_clients) to grant restricted access to. Required (≥1) when role=client.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is created. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
sendInviteboolean- Send the invite email after creation. false = create silently; the person cannot log in until invited.default
true
agencyanalyticsmcp_execute_create_toolCreate a record through one AAQL backend connector (provider + asset), as the caller.WriteExecute Create Tool
Create a record through one AAQL backend connector (provider + asset), as the caller. `rows` holds the one record to create, as a field→value object; `filters` carries any slots the connector needs to place them. This tool runs in TWO steps. ALWAYS begin with confirmed=false: it returns a preview and changes nothing. Show the preview to the user and END YOUR TURN. Only after the user approves, call again with the same arguments, confirmed=true and the previewToken the preview returned.
Inputs
assetstring- No description.
confirmedboolean- Leave false to preview. Set true only after the user has approved the preview.default
false filtersobject- No description.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
providerstring- No description.
rowsarray- Exactly one row per call.
agencyanalyticsmcp_execute_read_toolRun one AAQL read for one client and return the connector rows as CSV, followed by a `Totals:` section when the connector reports totals.WriteExecute Read Tool
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 id. To read several accounts make ONE call per account rather than passing a list. 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).
Inputs
assetstring- No description.
clientIdinteger- No description.
fieldsarray- No description.
filtersobject- No description.
groupByarray- No description.
limitinteger- No description.default
50 offsetinteger- No description.default
0 providerstring- No description.
sortobject- One field-to-direction pair, e.g. {"clicks": "desc"}. Directions: asc, desc. One clause only.
testModeboolean- No description.default
false
agencyanalyticsmcp_execute_update_toolUpdate records through one AAQL backend connector (provider + asset), as the caller.WriteExecute Update Tool
Update records through one AAQL backend connector (provider + asset), as the caller. `filters` selects the records to change (e.g. {"id": 123}) and is required; `rows` carries the new field values, as field→value objects. The preview shows only the new values; if you cannot read the current ones, say so before calling. This tool runs in TWO steps. ALWAYS begin with confirmed=false: it returns a preview and changes nothing. Show the preview to the user and END YOUR TURN. Only after the user approves, call again with the same arguments, confirmed=true and the previewToken the preview returned.
Inputs
assetstring- No description.
confirmedboolean- Leave false to preview. Set true only after the user has approved the preview.default
false filtersobject- No description.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
providerstring- No description.
rowsarray- Exactly one row per call.
agencyanalyticsmcp_read_client_google_sheetsRead a client's Google Sheets spreadsheet — custom data agencies track outside their marketing platforms (budgets, leads, offline conversions, call logs, campaign trackers).WriteRead Client Google Sheets
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.
Inputs
aggregatorTypestring- by_date only: how metric values combine per date bucket. Defaults to sum.one of
sumavgminmax clientIdinteger- No description.
dateFieldstring- The column letter holding dates (e.g. 'A'). Required for by_date; on rows it must come with startDate and endDate to filter the grid.
endDatestring- Y-m-d. As startDate.
entityTypestring- No description.one of
rowsby_datedefaultrows fieldsarray- Column letters a-cz. by_date: the metric columns to aggregate (required, e.g. ["b","c"]). rows: an optional subset of columns to return.
limitinteger- rows only (max 1000); by_date returns the full date series.default
50 sheetNamestring- The tab to read. Defaults to the first tab; list tabs via browse_client_google_sheets.
spreadsheetIdstring- The spreadsheet to read — an id from browse_client_google_sheets, or a full docs.google.com URL.
startDatestring- Y-m-d. Required for by_date; optional on rows (with dateField and endDate).
agencyanalyticsmcp_read_client_metric_signalsReturn a single client's biggest-moving metrics (trend signals), ranked by the magnitude of their percent change — biggest movers first, whether up or down.WriteRead Client Metric Signals
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.
Inputs
clientIdinteger- No description.
comparisonTypestring- No description.one of
previous_periodyear_over_year directionstring- No description.one of
updownflat limitinteger- No description.default
50 minPercentageChangeMagnitudenumber- No description.
periodinteger- Comparison window in days. Allowed values: 30 or 90 (365-day comparisons are excluded as too noisy). Omit for both windows.
agencyanalyticsmcp_read_client_rank_trackerFetch 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.WriteRead Client Rank Tracker
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.
Inputs
clientIdinteger- No description.
dateIntervalstring- Date bucketing for date-grain breakdowns: daily (default), monthly, or automatic (over 30 days rolls up to months).one of
dailymonthlyautomatic endDatestring- No description.
entityTypestring- No description.one of
keyworddatetagurlrangedate_rangeserpdate_serpdate_keyworddefaultkeyword googleMobileSerpFeaturesarray- As googleSerpFeatures, for Google Mobile. Setting both keeps a keyword matching EITHER engine.
googleSerpFeaturesarray- Keep only keywords holding these Google SERP features on the END DATE of the range, e.g. ["featured_snippet"]. One of: ads_top, featured_snippet, local, hotel, knowledge_graph, people_also_ask, top_story, video, image, shopping, twitter, recipes, ads_bottom, sitelink, indented_result, review, faq.
keywordIdinteger- Required for entityType=date_keyword, and rejected for every other breakdown.
limitinteger- No description.default
50 primaryKeywordboolean- Restrict to the campaign's starred keywords.
rangearray- Ranking-position buckets to keep, e.g. ["1_3","4_10"]. Only the date / range / date_range breakdowns declare it. One of: 1_3, 4_10, 11_20, 21_50, 51_plus.
searchstring- Free-text match on the keyword phrase (or the tag / url label on those breakdowns).
searchLanguageIdinteger- No description.
searchLocationIdinteger- No description.
serparray- Search engines to keep, e.g. ["google","bing"]. Only the serp / date_serp breakdowns declare it. One of: google, google_mobile, google_local, bing.
startDatestring- No description.
tagsarray- Tag IDs to restrict to — NOT labels. Get them from the `tag` breakdown's tag_id column. Must be a list, e.g. [79113]; a bare value is ignored.
testModeboolean- No description.default
false
agencyanalyticsmcp_read_client_rank_tracker_diagnosticsInvestigate 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).WriteRead Client Rank Tracker Diagnostics
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.
Inputs
clientIdinteger- No description.
enginestring- Which engine's recorded ranking is disputed: google, google_mobile, google_local, bing.one of
googlegoogle_mobilegoogle_localbing keywordIdinteger- The tracked keyword to investigate. Get it from read_client_rank_tracker entityType=keyword.
agencyanalyticsmcp_read_client_site_auditorFetch 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.WriteRead Client Site Auditor
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.
Inputs
auditIdstring- Which crawl to read: a task_id from the `audits` breakdown, or 'latest' (the newest crawl). Not accepted on `audits`/`history`, which span every crawl.default
latest clientIdinteger- No description.
endDatestring- Y-m-d. As startDate.
entityTypestring- No description.one of
summarytestsauditshistorypagestest_pagespage_detaildefaultsummary limitinteger- No description.default
50 searchstring- Free-text match on the check name (tests) or the page URL (pages).
showPassedboolean- tests only: set false to hide passing checks. Default includes them.
startDatestring- Y-m-d. Required for entityType=history, and rejected for every other breakdown — they read one crawl, not a window.
statusCodestring- HTTP status bucket to keep on the pages breakdown — one of 2xx, 3xx, 4xx, 5xx. Exact codes such as "404" are refused: the crawl provider only filters by bucket, so use 4xx for broken pages.one of
2xx3xx4xx5xx testIdinteger- Required for entityType=test_pages, and rejected for every other breakdown. Get it from the `tests` breakdown's test_id column.
testModeboolean- No description.default
false urlstring- Required for entityType=page_detail, and rejected for every other breakdown. Copy it exactly from the `pages` breakdown's url column.
agencyanalyticsmcp_update_clientUpdate 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.WriteUpdate Client
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).
Inputs
clientIdintegerrequired- The client to update, from search_clients or browse_clients.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is changed. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false groupstring- Client group to move the client into, shown as a folder in the app. FIND-OR-CREATE: an unrecognised name creates a new group. Omit to leave the group unchanged; use removeFromGroup to ungroup.
namestring- New company name (max 150 chars). Omit to keep the current name.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
removeFromGroupboolean- true = take the client out of its current group. Cannot be combined with group.default
false timezonestring- New IANA timezone identifier such as America/Toronto. Omit to keep the current one.
websitestring- New website, e.g. acme.com. Omit to keep the current one. Changing it re-fetches the logo for the new website and changes Rank Tracker attribution.
agencyanalyticsmcp_update_client_custom_metricUpdate an existing custom metric — rename it, change its description, data type or change format, or replace its formula.WriteUpdate Client Custom Metric
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).
Inputs
customMetricIdintegerrequired- The custom metric to update, from browse_client_custom_metrics.
changeFormatstring- percent = up is good; percent_inverted = up is bad. Changing it flips every KPI/goal verdict on this metric. Omit to keep.one of
percentpercent_inverted clientIdinteger- Optional scope check: the client a client-level metric belongs to. Omit for an account-level metric.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is changed. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false dataTypestring- New data type: currency for money, percent for rates, integer/float for counts. Omit to keep.one of
integerfloatcurrencypercent descriptionstring- New description (max 255 chars). Omit to keep it; it cannot be cleared.
expressionstring- New arithmetic over {ref} placeholders, e.g. "({spend} / {leads}) * 100" — only together with variables.
namestring- New display name (max 128 chars). Omit to keep the current name.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
variablesarray- New formula variables — only together with expression; replaces the whole formula. Max 15; every variable must appear in the expression.
agencyanalyticsmcp_update_client_custom_viewUpdate an existing custom view (a blended data table in the client's "Views" section) — rename it, or change its columns from a plain-language request.WriteUpdate Client Custom View
Update an existing custom view (a blended data table in the client's "Views" section) — rename it, 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, pass name only. The columns stay exactly as they are. - To CHANGE COLUMNS, 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 column that is removed or renamed stops showing in every widget that used it, so the tool refuses a regeneration that drops or renames a column. Only when the USER asked to remove or rename a column, or to stop reading a data source in it, list its current name in removeColumns. - 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, 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), 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 the confirmed rename call, exactly as the preview returned it), confirmed (boolean — leave false to preview; set true only after the user approves).
Inputs
clientIdintegerrequired- The client the view was listed for with browse_client_custom_views.
customViewIdintegerrequired- The custom view to update, from browse_client_custom_views.
columnEditsarray- Column edits the USER asked for, applied in order. Each names its column as the view currently has it. Never with prompt.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is changed. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false generatedViewstring- ONLY on the confirmed prompt call: the generatedView JSON block from the preview, copied EXACTLY. Guarantees the written view matches the approved preview.
namestring- New view name (max 100 chars). Omit to keep the current name.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
promptstring- The change to the columns, in plain language (max 1000 chars). Omit to only rename.
removeColumnsarray- Current column names the USER asked to remove, rename, or stop reading a data source in — only with prompt. Any other column the regeneration drops, or stops reading a source in, is refused, because a widget that shows only that column would go blank.
agencyanalyticsmcp_update_client_keyword_rankingsQueue 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.WriteUpdate Client Keyword Rankings
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.
Inputs
clientIdinteger- No description.
confirmedboolean- Leave false to preview the refresh (keyword list + credit cost) without queuing anything. Set true ONLY after the user has explicitly approved the preview in a later turn.default
false keywordIdsarray- The tracked keyword ids to refresh (from read_client_rank_tracker entityType=keyword). Max 50 per call — each spends one refresh credit.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
agencyanalyticsmcp_update_userUpdate an existing user on YOUR OWN account — their name, and which clients they can see.WriteUpdate User
Update an existing user on YOUR OWN account — their name, 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. 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 change a user's email address or role, and cannot deactivate anyone — 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. Updating users requires user-management permission — the tool refuses with an explanation when the caller does not have it, when the target is an admin, or when the target is yourself (change your own details in your account settings). Input: userId (integer, required), firstName (string), lastName (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).
Inputs
userIdintegerrequired- The id of the user to update — resolve it with search_users.
addClientIdsarray- Client ids to ADD to the user's current access. Omit to leave their access unchanged.
allClientsboolean- Staff targets only, and only when you have all-client access yourself. true = standing access to ALL clients, including ones added in the future. false = switch them off that standing pass, which requires addClientIds naming the clients they keep.
confirmedboolean- ALWAYS false on the first call — the preview is mandatory and nothing is written. Set true only on a follow-up call, after the user has replied approving the exact preview.default
false emailstring- New login email. Omit to leave unchanged. No verification email is sent.
firstNamestring- New first name (max 100 chars). Omit to leave unchanged.
lastNamestring- New last name (max 100 chars). Omit to leave unchanged.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
removeClientIdsarray- Client ids to REMOVE from the user's current access. Omit to leave their access unchanged.
agencyanalyticsmcp_execute_delete_toolDelete records through one AAQL backend connector (provider + asset), as the caller.DestructiveExecute Delete Tool
Delete records through one AAQL backend connector (provider + asset), as the caller. `filters` selects the records to delete (e.g. {"id": 123}) and is required. Tell the user which records the filter selects; if you cannot read them, say so before calling. This tool runs in TWO steps. ALWAYS begin with confirmed=false: it returns a preview and changes nothing. Show the preview to the user and END YOUR TURN. Only after the user approves, call again with the same arguments, confirmed=true and the previewToken the preview returned.
Inputs
assetstring- No description.
confirmedboolean- Leave false to preview. Set true only after the user has approved the preview.default
false filtersobject- No description.
previewTokenstring- Leave unset on the preview. On the confirmed call, pass back exactly the previewToken the preview returned.
providerstring- No description.
No tools match.
