MCP agent

Tools reference

Every MCP tool the TrustData server exposes, with scope, purpose, and example arguments.

Your agent sees only the tools your token's scopes grant. Below is the full catalog.

Analytics primitives

`query_metrics`: `read:metrics`

Aggregated marketing metrics for a date range and set of dimensions.

{
  "start_date": "2026-04-01",
  "end_date": "2026-04-15",
  "dimensions": ["channel", "campaign"],
  "metrics": ["spend", "conversions", "revenue"],
  "property_id": "a3f4-...",
  "limit": 100
}

`get_timeline`: `read:timeline`

Date-aggregated series for one metric. Useful for charts and anomaly spotting.

{ "start_date": "2026-04-01", "end_date": "2026-04-22",
  "metric": "conversions", "granularity": "day" }

`get_attribution`: `read:attribution`

Multi-touch attribution journeys and Sankey diagram data. Models: last_click, linear, shapley.

`get_geo`: `read:geo`

Country / region / city breakdown for one metric.

`get_retention`: `read:retention`

Cohort retention heatmap and per-channel comparison. cohort_type: weekly or monthly.

`get_ltv`: `read:ltv`

Cumulative LTV curves and per-channel breakdown.

`list_change_events`: `read:change_events`

Known annotations (GTM publishes, manual markers, config changes) for a date range.

`list_analytics_queries`: `read:metrics`

Describes every registered query_type the calling token can reach. Metadata only, so it returns instantly without touching your analytics data. Agents should call this before crafting ad-hoc analyses.

Bootstrap (resource enumeration)

Every property-scoped tool takes a UUID the agent has no other way to discover. These list_* tools let the agent enumerate the resources it needs.

`list_properties`: `read:metrics`

Attribution properties the caller's org can see. Returns id, name, website_url, is_rollup.

`list_data_sources`: `read:metrics`

Ad-platform DataSources (Google / Facebook / TikTok Ads, Shopify, …) with connector type and last-sync timestamp. Filter by property_id.

{ "property_id": "a3f4-..." }

`list_attribution_ids`: `read:metrics`

Tracking-stream UUIDs (the JS SDK's attribution_id). Needed for segment / cohort drill-downs.

`list_brand_prompts`: `read:geo_visibility`

BrandPrompts tracked for GEO probes. Returns the prompt IDs needed for target_prompt_ids on create_recommendation (treatment group for outcome tracking). Pass property_id to include both org-level and property-scoped prompts.

{ "property_id": "a3f4-...", "only_active": true }

`list_competitors`: `read:geo_visibility`

Tracked competitor slugs for the org. Used for share-of-voice and citation-gap filters.

AI Visibility (GEO) & SEO

`get_geo_visibility`: `read:geo_visibility`

AI search KPIs (mention rate, citation count, share of voice) plus optional GSC / AI-Overview gap list.

{ "property_id": "a3f4-...", "days": 30, "include_gaps": true, "gap_limit": 20 }

`list_seo_keywords`: `read:seo_keywords`

GSC + DataForSEO + revenue join, one row per keyword with position, volume, KD, SERP features, trend, opportunity score, and first-party revenue uplift. Filter for quick wins:

{ "property_id": "a3f4-...", "days": 30,
  "min_position": 4, "max_position": 10,
  "min_revenue_uplift": 500, "limit": 50 }

`list_citation_gaps`: `read:geo_visibility`

Domains cited by LLMs that don't yet link to the brand. High-leverage outreach targets.

`run_probe`: `run:probes` (billed)

Run a GEO probe against AI engines on demand. Billed per engine call against your GEO add-on's monthly allowance.

{ "prompt": "Best CRM for French SaaS startups under 50 employees",
  "property_id": "a3f4-...",
  "probe_type": "with_search" }

Recommendations & experiments

`list_recommendations`: `read:recommendations`

Open AI-generated recommendations for a property. Filter with include_dismissed, include_followed.

`list_concluded_experiments`: `read:recommendations`

Recommendations whose measurement window has closed, with a verdict (winner / likely_winner / no_effect / inconclusive). Call this before proposing new hypotheses so the agent learns from prior outcomes.

{ "last_n_weeks": 12, "verdict": "winner" }

`create_recommendation`: `write:recommendations`

Create a new recommendation sourced from the calling agent. Tagged source=mcp_agent in the dashboard.

{
  "property_id": "a3f4-...",
  "title": "Add FAQ schema to /pricing",
  "action": "Publish FAQPage JSON-LD with the 6 top pricing questions",
  "hypothesis": "If we add FAQPage JSON-LD to /pricing, ChatGPT citation rate on 'best CRM pricing' queries will rise because AI Overviews preferentially surface structured Q&A.",
  "channel": "geo",
  "category": "on_page",
  "urgency": "high",
  "effort_level": "quick_win",
  "target_prompt_ids": ["42", "87"]
}

hypothesis must be ≥ 20 chars in "If we X, then Y because Z" form.
target_prompt_ids (optional): BrandPrompt IDs forming the treatment group. Outcome tracking compares mention-rate delta on those prompts vs the rest of your org (control).
If you include change_url at creation, the rec is atomically marked followed ("I did this, track it" flow).

Tags the rec with source="mcp_agent" (dashboard shows a 🤖 badge).
Snapshots the current context (prompts, mention rates, SEO metrics).
Enters the rec into the outcome-tracking queue.

Every Monday 06:30 UTC, the track_recommendation_outcomes task:

Computes treatment_delta = post-change mention rate − pre-change for the prompts listed in target_prompt_ids.
Computes control_delta = same measurement on all other org prompts.
Verdict is adjusted_delta = treatment_delta − control_delta:
Delta Verdict
≥ 10pp winner
≥ 5pp likely_winner
≤ −5pp no_effect
else inconclusive

Delta	Verdict
≥ 10pp	winner
≥ 5pp	likely_winner
≤ −5pp	no_effect
else	inconclusive

Next time the agent runs, it can call list_concluded_experiments(verdict="winner") to learn what's working before proposing the next batch.

Quickstart

Issue a token, connect your agent, and run your first tool call in about 2 minutes.

SEO × GEO playbook

An 8-step system prompt that turns your agent into a weekly SEO × GEO operator.