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.

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.