Tools reference
The server exposes 97 read-only tools. Your assistant chooses them for you; this page is useful to understand what it can see, or to call the tools directly.
Every tool is annotated readOnlyHint: true, destructiveHint: false and idempotentHint: true. The server has no resources and no prompts.
Conventions
Most tools share these parameters. The tables below list them as P, D, G and F.
| Parameter | Type | Description | |
|---|---|---|---|
| P | project_id | string (UUID), required | The project. Get it from list_projects. |
| D | from, to | string, required | Date range YYYY-MM-DD, both days included. Days are cut in UTC; the dashboard uses your workspace's timezone, so daily figures can differ slightly. |
| G | granularity | hour · day · week · month, optional | Time bucket of series. Default day. |
| F | filters | object, optional | Restrict to a segment. See below. |
JSON
{
"page": { "type": "contains", "value": "/blog" },
"countries": ["FR", "BE"],
"cities": ["Paris"],
"devices": ["mobile"],
"browsers": ["Chrome"],
"os": ["iOS"],
"sources": ["Organic Search"]
}
page.type is exact, contains or not-contains; page.values accepts several paths. Countries are ISO 3166-1 codes.
Results come back as JSON in a single text block. When a call fails, the tool returns isError: true with the HTTP status and the beginning of the upstream response.
Projects & context
| Tool | Returns | Parameters |
|---|---|---|
list_projects | Projects you can access: id (the UUID other tools need), name, URL, identifier. Start here. | — |
get_project_context | AI-analysed business brief (industry, model, audience, offer, brand voice, markets, stack, keywords) and tracked competitors. | P |
list_knowledge_documents | Documents in the project's knowledge base: uploaded files and synced Google Drive, OneDrive and Notion items. | P |
get_knowledge_document | One document: its AI summary, extracted text and relevance. | document_id (UUID) |
get_integrations_status | Status of every data source (Search Console, Meta, Google Ads, LinkedIn Ads, TikTok, YouTube, Business Profile, email, HubSpot, Pipedrive, Stripe, Shopify…). Call it before querying a source. | P |
Audience & acquisition
All these tools take P, D, and optionally G and F.
| Tool | Returns |
|---|---|
get_audience_totals | Sessions, pageviews and unique users. The go-to tool for "how much traffic?". |
get_sessions_overview | Sessions and users over time. |
get_bounce_rate | Bounce rate. |
get_avg_session_time | Average session duration. |
get_scroll_depth | Scroll depth. |
get_new_vs_returning | New vs returning visitors. |
get_top_acquisition_channels | Sessions by channel: direct, organic search, social, referral, paid, email, GEO… |
get_channels_daily | Sessions per channel, over time. |
get_channel_revenue | Revenue attributed to each channel. |
get_top_referrers | Top referring domains. |
get_referrer_trends | Referrers over time, with their conversions and revenue. |
get_search_engine_share | Organic search split by engine. |
get_ai_traffic_share | Share of traffic from AI assistants (ChatGPT, Claude, Perplexity, Gemini…). |
get_ai_traffic_trends | AI assistant traffic over time. |
get_ai_top_pages | Top 20 landing pages for AI-referred visits, per engine. |
get_top_countries | Visitors by country. |
get_top_regions | Sessions by region (states, provinces). |
get_top_cities | Sessions by city. |
get_top_languages | Visitors by browser language. |
get_device_types | Mobile / desktop / tablet. |
get_device_dimensions | Sessions by screen size. |
get_top_browsers | Top browsers. |
get_top_os | Top operating systems. |
Pages
| Tool | Returns | Parameters |
|---|---|---|
get_top_pages | Pages with views, engagement time, bounce rate, trend vs the previous period and SEO score. Paginated and sortable. | P, D, F, page (default 1), per_page (default 10, max 200), sort_by (views · avg_time · bounce_rate · trend · technical), sort_dir (asc · desc) |
list_site_pages | Every page (path and title) with its sessions. Without from/to, all time. | P, from/to (optional), F, pathname (substring), page, per_page (default 50, max 200) |
get_spike_explanation | Why a day stands out in a series: the pages, channels, referrers and countries (or, for Search Console, pages and queries) that did more than usual. | P, date (YYYY-MM-DD), source (analytics · gsc), metric (sessions · users · clicks · impressions), baseline_days (max 90), F |
Custom events & funnels
Event tools accept props: conditions on event properties, as a list of { key, op, values } items. op is one of eq, neq, contains, not_contains, has_in_list, gt, gte, lt, lte, set, unset. Totals and series can also aggregate a numeric property with agg (sum · avg · min · max) and agg_prop.
| Tool | Returns | Parameters |
|---|---|---|
list_event_names | Custom events recorded in the period, with counts and last seen date. The entry point for event questions. | P, D, F |
list_event_props | Properties each event carries, with their type and most frequent values. | P, D, names (up to 50), values_per_prop (default 10, max 50), F |
get_event_totals | Count per event (0 for a name never recorded), or an aggregate of a property. | P, D, names (1–50), props, agg, agg_prop, F |
get_event_daily | Daily counts or aggregates per event. | Same as get_event_totals |
get_event_breakdown | One event split by the values of a property. | P, D, name, prop, limit (max 12), props, agg, agg_prop, F |
list_event_occurrences | Individual occurrences, newest first, with their properties and page. | P, D, name, prop (optional), page, per_page (default 20, max 100), F |
get_funnel | Users reaching each step of an ordered funnel, with drop-offs. | P, D, steps (2+ items { type: "page" | "event", values: [...] }), utm_source, utm_medium, utm_campaign |
Real time & session replay
| Tool | Returns | Parameters |
|---|---|---|
get_realtime_activity | Visitors right now: pages, sources, countries. Last 30 minutes, or 10 minutes around at. | P, at (RFC 3339, optional) |
get_realtime_timeline | Visitors per minute. | P |
get_realtime_map | Where current visitors are. | P, at (optional) |
list_active_sessions | Active sessions, with the sessionId replays need. | P, at (optional) |
get_session_replay_events | Raw recording of one session (rrweb events, packed). | P, session_id |
Traffic quality
Both tools take P, D, F and target_countries, a list of ISO codes. Without it, the project's own country whitelist is used; an empty list counts every country.
| Tool | Returns |
|---|---|
get_traffic_quality_stats | Traffic Quality Score of the period: how engaged its sessions are, on a 0–100 scale, with the scoring rules. |
get_traffic_quality_daily | The same score, day by day. |
Search Console & indexation
| Tool | Returns | Parameters |
|---|---|---|
get_gsc_daily | Clicks, impressions, CTR and average position per day. | P, D |
get_gsc_keywords_overview | Keyword totals compared with the previous period. | P, D |
get_gsc_top_keywords | Top queries, paginated. | P, D, limit (default 50, max 500), offset |
get_gsc_top_pages | Top organic landing pages. | P, D, limit (default 50, max 500) |
get_gsc_keyword_pages | Pages ranking for one query (exact match). | P, query, D, limit (default 20, max 500) |
get_gsc_page_keywords | Queries a page ranks on. | P, page (full URL), D, limit (default 20, max 500) |
get_gsc_index_coverage | Indexed vs not indexed vs not inspected URLs, with reasons. | P, D |
get_gsc_index_coverage_urls | URLs in a given indexation state, paginated. | P, D, state, page, per_page (default 10, max 100) |
get_gsc_index_coverage_history | Indexation counts per day. | P, D |
get_gsc_indexation_status | Sitemaps: submitted URLs, warnings, errors. | P, D |
SEO audits (crawler)
| Tool | Returns | Parameters |
|---|---|---|
list_crawls | Past site audits. | project_id or workspace_id |
get_crawl_score | Overall SEO score of one audit. | crawl_id |
get_crawl_score_history | Score of every audit over time, newest first. | P, limit (default 20, max 100) |
get_crawl_pages | Pages found by an audit: status, depth, response time, SEO metadata, issues. | crawl_id |
get_crawl_issues | Issues detected by an audit. | crawl_id |
get_crawl_duplicates | Duplicate titles, descriptions and content. | crawl_id |
get_page_score | Latest audit of one page: score out of 100, every check, points lost and how to fix. | P, pathname or url |
get_crawler_avg_load_time | Average page load time vs the previous period. | P, D |
get_crawler_errors_summary | Crawl errors (404, 500…) with counts. | P, D |
get_crawler_broken_links | Broken internal and external links. | P, D |
Social media (organic)
The list tools take limit (default 50, max 500).
| Tool | Returns | Parameters |
|---|---|---|
get_meta_organic_overview | Facebook page: reach, impressions, engagement, followers, posts. | P, D |
get_meta_posts | Top Facebook posts. | P, D, limit |
get_instagram_media | Top Instagram posts and reels. | P, D, limit |
get_tiktok_overview | TikTok account summary. | P, D |
get_tiktok_videos | Top TikTok videos. | P, D, limit |
get_youtube_overview | YouTube channel summary. | P, D |
get_youtube_videos | Top YouTube videos. | P, D, limit |
E-commerce
source picks the data: auto (default: Shopify if connected, else Stripe, else the tracker's purchase events), tracker, shopify or stripe.
| Tool | Returns | Parameters |
|---|---|---|
get_ecommerce_overview | Orders, revenue, average order value, carts, abandoned carts, cart-to-order rate. | P, D, source |
get_ecommerce_daily | Carts, orders and revenue per day. | P, D, source |
get_stripe_overview | Stripe gross and net revenue, refunds, fees, payments, customers. | P, D |
get_stripe_daily | Stripe payments per day. | P, D |
get_shopify_overview | Shopify orders summary. Without the read_all_orders scope, Shopify only serves the last 60 days. | P, D |
get_shopify_daily | Shopify orders per day. | P, D |
Leads & CRM
Leads follow the project's lead source: detected forms, or the custom event chosen on the Leads page, plus CRM contacts. CRM tools take source: auto (default), hubspot or pipedrive.
| Tool | Returns | Parameters |
|---|---|---|
get_leads_overview | Total leads. | P, D |
get_leads_daily | Leads per day. | P, D |
get_leads_by_source | Leads by page and form. | P, D, limit (default 20, max 500) |
get_crm_total | CRM contacts created. | P, D, source |
get_crm_deals_overview | Won deals: count, revenue, average value. | P, D, source |
get_crm_deals_daily | Won deals per close date. | P, D, source |
get_crm_deals_by_stage | Deals per pipeline stage. | P, D, source |
list_crm_won_deals | Won deals, biggest first. | P, D, limit (default 10, max 100) |
get_crm_lifecycle_stages | HubSpot contacts per lifecycle stage (all time). | P |
Goals, tasks, campaigns & reports
| Tool | Returns | Parameters |
|---|---|---|
list_goals | Goals with live progress: target, current value, % reached. | P, status (active · completed · archived) |
list_tasks | Tasks with their board columns (description truncated). | P, section_id, priority (low · medium · high · urgent) |
get_task | One task in full, with its comments. | task_id |
list_campaigns | Campaigns: budget, dates, channel, status, UTM parameters. | P, status |
list_reports | Reports: template, audience, period, KPIs, sharing and schedule. | P, access_type (private · users · public) |
list_report_templates | The report templates and the KPIs they contain. | — |
Custom KPIs & definitions
| Tool | Returns | Parameters |
|---|---|---|
list_custom_kpis | Custom KPIs of the project: formula, label, format. | P |
get_custom_kpi_value | A custom KPI's value, previous value, change and daily series. | P, indicator_id, D |
list_custom_kpi_metrics | The vocabulary custom KPI formulas are written with. | — |
explain_kpi | How a Sublim metric is calculated: definition, formula, unit, source, pitfalls, and which tools return it. | kpi (comma-separated), category, query, include_related |
Ask for definitions
When two figures don't match, for example Search Console clicks and organic sessions, ask the assistant to explain how each is calculated. It will call explain_kpi instead of guessing.