Skip to content

Connector

Tool reference

All 22 tools, grouped by the scope they need. A connection granted only the default scopes is offered 20 of them.

The examples are executed, not written out

Every public tool below carries a call you can paste. They were run against production on 2026-09-10, and the fields listed under each one are the keys that came back. A checker re-runs them and fails when a response changes shape, so an example here has been executed more recently than it was written. The two that are not re-run say so, with the reason.

Generated from the server's manifest

This page is built from the same three sources the server uses to decide what to advertise: the tool manifest, the endpoint map and the scope map. A tool added to one and not the others fails the build rather than appearing here half described.

Read your ad performance

read:marketing · on by default · 13 tools

Spend, ROAS, campaigns, anomalies, forecasts, budgets and profit for the brands you choose. Read only.

list_brandsPOST/api/mcp/brands

Every brand on the account with its connected platforms and last sync.

Cost: One request against your API key's per minute allowance.

list_campaignsPOST/api/mcp/campaigns

Every campaign that delivered in a window, with its id, platform and spend.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling shared by every caller of that brand.

get_campaign_metricsPOST/api/mcp/metrics

Spend, ROAS, CPA, CTR and more, by account, campaign, adset or ad.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling shared by every caller of that brand.

compare_campaignsPOST/api/mcp/compare

Campaigns, adsets or ads side by side for A/B calls and budget decisions.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling. The comparison runs one query per entity id server side and still counts as a single request.

detect_anomaliesPOST/api/mcp/anomalies

CPA spikes, ROAS drops and spend surges, with severity and likely cause.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

get_pacing_statusPOST/api/mcp/pacing

Whether spend is on pace against monthly targets, with end-of-month projections.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

forecast_performancePOST/api/mcp/forecast

A stored forecast with its confidence interval, or an explicit statement that none exists.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling. It reads a stored forecast and does not train one, so it costs no more than any other read.

get_benchmarksPOST/api/mcp/benchmarks

Industry benchmark CTR, CVR, CPC and ROAS to compare a brand against.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

get_budget_recommendationPOST/api/mcp/budget-recommendation

Suggested budget shifts under CAC, ROAS and minimum-spend constraints.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

ask_cresvaPOST/api/mcp/ask

The fallback: a marketing question in plain language when no specific tool fits.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling. This one reaches a language model, so it is the slowest and the most expensive to serve: prefer a specific tool when one fits.

get_profitPOST/api/mcp/profit

Did the brand make money: contribution margin, break-even ROAS and the SKUs losing money.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

get_memoryPOST/api/mcp/memory

What Cresva has learned about a brand: patterns, past decisions and how they turned out.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

list_approvalsPOST/api/mcp/approvals

What is waiting on a human decision, and what was recently decided.

Cost: One request against your API key's per minute allowance, plus the per brand ceiling.

Read your public storefront

read:commerce · on by default · 7 tools

Products, prices, trust signals and the catalogue an AI shopper already sees. This information is public.

discover_storefrontGET/.well-known/osp.json?brand=<brand>no key needed

What a brand's agent-readable storefront publishes, and what it supports.

Cost: One request against the anonymous per address allowance.

curl "https://cresva.ai/.well-known/osp.json?brand=demo_acp_store_v1"

Returns: acp_version, brand_id, brand_name, capabilities, documentation, is_storefront, rate_limits, storefront_url, supported_currencies, supported_languages, type. Run against production on 2026-09-10.

search_productsGET/api/storefront/{brandId}/searchno key needed

Search a storefront's catalogue the way a shopper would ask.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling.

curl "https://cresva.ai/api/storefront/demo_acp_store_v1/search?q=court"

Returns: meta, products, query. Run against production on 2026-09-10.

list_productsGET/api/storefront/{brandId}/productsno key needed

Page through a storefront's catalogue with the offer fields agents read.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling.

curl "https://cresva.ai/api/storefront/demo_acp_store_v1/products?limit=2"

Returns: meta, products. Run against production on 2026-09-10.

get_productGET/api/storefront/{brandId}/products/{productId}no key needed

One product in full, including price, currency and availability.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling.

curl "https://cresva.ai/api/storefront/demo_acp_store_v1/products/demo_prod_court_one"

Returns: content_score, product, review_details. Run against production on 2026-09-10.

compare_productsGET/api/storefront/{brandId}/compare?ids=<ids>no key needed

Two to five products from one brand, side by side on the fields agents read.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling.

curl "https://cresva.ai/api/storefront/demo_acp_store_v1/compare?ids=demo_prod_court_one,demo_prod_daybag_22"

Returns: comparison, meta, products. Run against production on 2026-09-10.

get_trust_scoreGET/api/storefront/{brandId}/trustno key needed

The trust signals a storefront publishes about itself, and its tier.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling.

curl "https://cresva.ai/api/storefront/demo_acp_store_v1/trust"

Returns: _cache, badges, brand_id, brand_name, calculated_at, certification, components, measured_components, measured_weight, member_since, provisional, score, tier, trend, verified_transactions. Run against production on 2026-09-10.

scan_storePOST/api/public/mcp/scan-storeno key needed

Whether an AI agent can find, understand and buy from any storefront. No API key, works on stores you do not own.

Cost: One request against the anonymous per address allowance. Results are cached for an hour per URL, so a repeat scan of the same store inside that window is served from cache.

curl -X POST "https://cresva.ai/api/public/mcp/scan-store" \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}'

Not run by our checker: scan_store spends a daily allowance that is SHARED by every anonymous caller: the MCP server sends no install id, so all of them key on one bucket. A verifier running on a schedule would exhaust a quota that belongs to real users, and every call also fetches a third party's site, which is the binding constraint on this tool.

Negotiate prices on your behalf

write:negotiation · off by default, granted only if the person turns it on · 1 tool

Open real price negotiations on your storefront. A negotiation can end in an accepted order at a discount, so this one changes things rather than reading them.

negotiate_pricePOST/api/storefront/{brandId}/negotiatewritesno key needed

Opens a live negotiation with the brand. Can return an accepted order.

Cost: One request against the anonymous per address allowance, plus the per brand ceiling. It also opens or advances a negotiation, which is state the brand can see, and a negotiation has a bounded number of rounds.

curl -X POST "https://cresva.ai/api/storefront/demo_acp_store_v1/negotiate" \
  -H "content-type: application/json" \
  -d '{"product_id":"demo_prod_court_one","offer":100}'

Not run by our checker: negotiate_price is the one tool that is not a read. It opens a real price negotiation on the merchant's storefront and can come back with an accepted order, so it is not something a documentation check runs on a schedule.

Propose changes for you to approve

write:proposals · off by default, granted only if the person turns it on · 1 tool

Put a suggested change into your approvals queue, where you read it and decide. It cannot approve anything, and it cannot change an ad account: approving and running both stay in your dashboard.

propose_budget_changePOST/api/mcp/propose-budgetwrites

Puts a budget change into your approvals queue for you to decide. It cannot approve or run one.

Cost: One request against your API key's per minute allowance. Repeating the same proposal is free: it is idempotent on brand, campaign and amount, so a second call returns the row already in the queue rather than adding another.

Save ad analyses you ask for

write:analyses · off by default, granted only if the person turns it on · 0 tools

When you click Analyse with Cresva on an ad, analyse that one ad and save the result to your Competitor Intel. It uses one of your tool runs, and it changes nothing anywhere else.

Approve, reject and pause your agents' proposals

approve:proposals · off by default, granted only if the person turns it on · 0 tools

Approve or reject proposals waiting in your approvals queue, and pause the agents on a brand. Approving a proposal makes the change at your ad account or store, under the same rules as approving in your dashboard. Irreversible changes and resuming paused agents stay in your dashboard.

Calling a tool directly

Every tool above is also an HTTP endpoint on cresva.ai, which is how the local package reaches them. A direct caller authenticates with an API key rather than OAuth. See Authentication for the difference, and Errors for the one envelope every failure uses.