Campaigns and analytics: MCP tool reference

The Valkiria MCP server at https://valkiria.pro/mcp gives a connected assistant 56 tools for campaigns across platforms, spend and conversion reports, account health, rules, recommendations and billing usage. 42 of them only read. The assistant picks the tool itself; this page lists what exists, under the names it reports in its tool calls.

Checked:

01

Tools that read (42)

These only return data. They are not counted against the monthly allowance.

  • projects_list: List owned projects within the selected client and project scope.
  • marketing_metrics_calculate: Calculate CPC = spend / clicks and ROAS = revenue / spend from explicit user-supplied inputs only. Supply money as nonnegative decimal strings (at most 15 integer and 6 fractional digits). Results use six decimal places, half-up rounding; ROAS is a ratio (3 means 3x, not 3%). Zero denominators and missing revenue return null. Spend and revenue must already share the same currency and unit; never combine cross-currency values. If unit compatibility is unknown, omit revenue (ROAS remains null) and ask for clarification; never invent an FX rate. Currency is an optional unverified uppercase three-letter label, never an inferred currency or conversion. Reads no account/project/provider facts; inputs are not measured evidence.
  • ads_campaigns_list: Owned campaigns of every connected platform (Google, Meta, TikTok, LinkedIn, Reddit, ChatGPT Ads, Microsoft, Snapchat, Telegram Ads), read from the same tables as the Campaigns screen, deleted ones left out. Without a selected project or client the result has inventory.totals and inventory.byPlatform (per status): quote campaign numbers only from these, never count the list yourself. byPlatform.*.chatActions says whether pause and budget changes can be prepared from the chat (with confirmation) or the platform can only be viewed. With a project or client selected it falls back to a bounded Google/Meta sample with countsBySource.
  • ads_analytics: Read canonical owned dated provider facts, separate native currencies, missing-data coverage and source dates. Never infer ROAS, complete synchronization or zero activity from absent facts.
  • ads_budget_change: Budget mutation is unavailable through this tool. Open campaigns to review and explicitly confirm the requested change.
  • get_started: Start here. Returns who is connected (assistant, auth kind, scopes), how many ad platforms are linked, three good first questions and the dashboard URL. Read-only, no parameters.
  • list_clients: List the agency portal clients this credential may see (id, name, company, attached campaign ids). Read-only.
  • get_client_report: The report a portal client sees: metrics, daily chart, platform breakdown, published monthly reports. Read-only.
  • list_campaigns: List advertising campaigns with optional filters by platform and status
  • get_campaign: Get detailed information about a specific campaign including recent metrics
  • get_campaign_performance: Get performance metrics (impressions, clicks, spend, conversions, ROAS) for a campaign
  • list_connected_platforms: List all connected ad platforms and their status
  • get_account_overview: Get a high-level overview of the advertising account (campaigns, platforms, spend)
  • klaviyo_campaigns: Read-only Klaviyo email/SMS campaigns (status, send time, audiences, opens, clicks, conversions, revenue) plus list and flow counts, from the last sync
  • list_meta_lead_forms: List Meta Instant Forms known to Valkiria with lead counts
  • list_meta_leads: List Meta Instant Form leads captured from Facebook and Instagram lead ads
  • get_provider_analytics_report: Read canonical dated Google/Meta/TikTok/LinkedIn/Snapchat provider facts used by client analytics: explicit date range, per-currency spend, campaigns, recorded days, source tables and last sync. Conversion summaries group platform/action types; conversions is null for mixed or unknown types. Never sum different groups or replace unknown totals with zero. No revenue or undated snapshot assumptions. Use this for native connected account statistics; legacy dashboard is a separate source.
  • get_dashboard_stats: Get dashboard statistics with currency-separated money and top five campaigns per currency; mixed or missing monetary totals are null, not zero
  • get_spend_summary: Get source-currency spend/revenue timelines with byCurrency breakdown. Missing evidence yields null, including partially missing clicks/conversions; never interpret null as zero. Mixed currencies have no aggregate money/profitability.
  • get_conversion_report: Get conversion metrics by campaign, preserving fractional attribution and source currency; aggregate CPA is null when currency is mixed/unknown or conversions are zero
  • compare_campaigns: Compare owned campaigns in requested order with explicit currency and null missing metrics; complete/unavailableCount indicate inaccessible selections
  • get_campaign_recommendations: AI commentary on locally recorded campaign statistics (an AI call, can take up to a minute). For recommendations on connected ad cabinets use list_campaign_recommendations
  • optimize_budget: Suggest an exact native-currency budget allocation based on recorded ROAS; does not change campaigns
  • list_rules: List automation rules, newest first (default 100, max 500)
  • get_rule_templates: Get pre-built automation rule templates (e.g., pause low CTR, scale high ROAS)
  • get_rule_history: View execution history for an automation rule
  • get_campaign_health: Get health score (0-100) and issues for a specific campaign
  • get_account_health: Get overall account health score with issues ranked by severity
  • list_campaign_recommendations: List what the system recommends changing in your ad cabinets, with the reason, the guard and how to undo each change
  • validate_campaign_recommendation: Have the ad platform check every request a recommendation would make, without changing anything. Approving does this first on its own
  • get_correction_learning: What the system has learned from corrections made across the cabinets it looks after (aggregated over every client; cabinet ids are shown only to operators who see every cabinet) — by its own recommendations, by operators and working sessions, and by people in the ad platform itself: how often each kind of change is made, in how many cabinets, how conversions and cost per conversion moved in the 7 days after, how often it is approved or rejected when proposed, and which frequent corrections no recommendation covers yet. Also each kind's adequacy verdicts with reasons (undone within a week, unsafe budget jump, raised without conversions, closed cabinet...), and the rules the system learned from adequate corrections proven to work (candidate / active / retired, with sample size, cabinets, share improved, Wilson bound and sign test) — active rules guide campaign setup, the AI chat and the recommendation order
  • get_business_location: Where the business of one of your cabinets physically is: the confirmed address, or the addresses found on the client's site and the web (each with source URL, evidence and confidence, waiting for confirmation), whether it is a physical business at all, the agreed geo scope and the options for it (radius, city, city and region, districts, wider). Reads what is stored and changes nothing; to search the site and the web again use discover_business_location
  • list_campaign_findings: List the open findings of the standing campaign audit for one of your cabinets
  • get_campaign_review: Get the latest stored review of a cabinet: what limits delivery, what was spent on what, and what to do first
  • list_client_exclusions: List what the client of a cabinet does not do: terms that became negative keywords in every grammatical form and are reported by the audit. Read-only
  • billing_plans_info: List subscription plans available to this account with prices (native currency), limits and a pricing page URL. Plan names may carry translations; the account language is respected.
  • billing_usage: Current plan, subscription status and quota usage (limit -1 = unlimited, used null = not readable right now). Read-only.
  • attribution_report: Multi-touch attribution of recorded conversions by channel for a date range and model. Read-only; amounts stay in the recorded currency.
  • predictions_list: Stored AI predictions (ROI, conversions, spend, revenue, trend, anomaly) of this account with confidence and, when known, actuals. Read-only; does not generate predictions.
  • get_account_playbook: Operating playbook for one connected ad account, built from its last 90 days: account state, grounded facts, rules and ready prompts (SKILL.md and PROMPTBOOK.md text). Built on first call if missing; free. Follow it when working on that account.
  • get_referral_link: Return this account's invitation link and its status: how many invited people signed up, completed a first task and were rewarded, and the bonus AI-chat actions still available with their nearest expiry. A new account that signs up through the link gets bonus AI-chat actions; the inviter gets bonus AI-chat actions after the invited account completes its first task. Read-only.
  • external_changes_list: What somebody changed in the connected ad accounts outside Valkiria (platform UI, editor, rules, another app): entity, field, old and new value, who and when, and whether a restore was proposed. Read-only.

02

Tools that change or generate (14)

A change requested through these tools follows the safety rules below: it is a proposal unless the write policy you set for the account allows it.

  • create_campaign: Create a local draft for a platform; does not publish or activate provider advertising
  • update_campaign: Edit an unpublished local draft. Connected campaigns and status activation require the approved provider workflow; no live provider write is performed here.
  • pause_campaign: Check a pause request. Currently returns provider_action_required without changing advertising; use the approved provider workflow.
  • resume_campaign: Check a resume request. Currently returns provider_action_required without activating advertising; use the approved provider workflow.
  • delete_campaign: Delete an unpublished local draft only. Connected campaigns require the approved provider workflow.
  • sync_meta_leads: Pull Meta Instant Form leads from Meta Graph API into Valkiria
  • ingest_meta_lead: Store a Meta lead payload received from a webhook or integration handoff
  • create_rule: Create an automation rule (e.g., pause campaigns with low CTR, scale high-ROAS campaigns)
  • update_rule: Update an automation rule
  • delete_rule: Delete an automation rule
  • preview_campaign_recommendation: Prepare and show exactly what a recommendation would publish (ad copy, keywords, which ad group keeps a duplicate keyword). Nothing is changed in the ad account; the preview is kept and is what an approval then publishes
  • set_client_exclusions: Add or remove what the client of a cabinet does not do. Added terms become negative keywords in every grammatical form; removal lifts them. Requires campaigns:write
  • billing_checkout_link: Create a hosted Stripe checkout page for a plan and return its URL. Does not charge; the owner completes payment in the browser. Not offered inside clients whose policy forbids checkout links (returns pricing_info_url instead).
  • refresh_account_playbook: Rebuild the playbook of one connected ad account from fresh data. Free; changes nothing in the ad account. Returns the build status: read the result with get_account_playbook once status is completed.

03

How changes stay safe

  • Two scopes, chosen by you at sign-in: read, and propose. With read alone the assistant cannot request any change.
  • A change requested from an assistant is a proposal. It waits in Approvals in Valkiria until the account owner approves it, unless the write policy you set for that account allows that kind of change by itself.
  • New campaigns are created paused. Starting new spend and deleting always wait for a person.
  • The assistant can list what is waiting for approval and reject a proposal. It cannot approve one: approval stays with the owner in Valkiria.
  • The change history shows who or what made each change and the value before and after, with Undo where the change can be reversed.
  • You can disconnect an assistant at any time on the Connect AI page; a developer API key can be deleted the same way.

04

Limits

  • The assistant sees only your own Valkiria workspace, and only the ad accounts connected there.
  • Numbers are as fresh as the last sync or import; the assistant can tell you when that was.
  • Money stays in each account's own currency. Different currencies are not converted or added up.
  • Reading data is not counted against the monthly allowance; changes and AI generations are. Allowances per plan are on the pricing page.

05

FAQ

Connect an assistant and call the first tool

Create a free account, connect an ad account and add the connector. The first pass only reads.

Drag to move. Alt + arrow keys move the button; Alt + Home resets its position.

Cookie Preferences

We use cookies to enhance your experience. Essential cookies are always active. You can manage optional cookies below.

Essential
Analytics
Marketing
Third-Party