Tool catalog

19 tools across 7 categories. Every tool is callable over the MCP protocol today. The REST gateway is not yet deployed — see the note on each tool.

Call caramel.v1.meta.capabilities at startup to get the live catalog with per-tool tier_required values. Cache the result for the session.

Note Legacy tool names (e.g. list_businesses, generate_campaign) continue to work and are aliased to their caramel.v1.* equivalents. Both names dispatch to the same handler.

business

Tools for reading the businesses the authenticated user belongs to.

Tool	v1 alias	Description	Tier	Scope
list_businesses	caramel.v1.business.list	List all businesses you have access to. Always call this first — most other tools require a business_id. Takes no parameters.	Starter	(any)

Usage

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "list_businesses",
    "arguments": {}
  }
}

audience

Tools for managing the contacts in a business audience.

Tool	v1 alias	Description	Tier	Scope
caramel.v1.contact.upsert	—	Add or update a contact. The email is the unique key — repeated calls with the same email update the record. Writes an audit log entry.	Business	audience:write

Plan caramel.v1.contact.upsert requires Business tier.

Coming soon audience:read scope and a caramel.v1.contact.list tool are planned.

Parameters — caramel.v1.contact.upsert

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses
email	string	Yes	Contact email (lowercased; unique per business)
first_name	string	No	Contact first name
last_name	string	No	Contact last name

forms

Tools for listing and submitting forms.

Tool	v1 alias	Description	Tier	Scope
caramel.v1.form.list	—	List all forms for a business. Returns each form’s ID, name, status, and submission count. Use the ID with form.submit or to embed the form.	Starter	forms:read
caramel.v1.form.submit	—	Submit data to an active form. Triggers all configured handlers: customer creation, campaign enrollment, and notifications.	Starter	forms:write

Parameters — caramel.v1.form.list

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses

Parameters — caramel.v1.form.submit

Parameter	Type	Required	Description
form_id	string	Yes	Form ID from caramel.v1.form.list
data	object	Yes	Form field values keyed by field name
source_url	string	No	URL where the submission originated
utm	object	No	UTM tracking parameters

Important caramel.v1.form.submit has a per-form rate limit of 10 submissions per 60 seconds per IP in addition to the gateway limits. Every call creates a new submission row — it is not safe to retry blindly. See Errors.

campaign

Tools for generating, refining, deploying, and managing marketing campaigns. All 9 tools back the same Edge Function.

Tool	v1 alias	Description	Tier	Credits
get_campaign_suggestions	caramel.v1.campaign.suggest	Get AI-powered suggestions for campaign type, timing, and audience. No credits used.	Starter	None
list_campaigns	caramel.v1.campaign.list	List campaigns with optional status filter. Returns summaries, statuses, and IDs.	Starter	None
get_campaign	caramel.v1.campaign.get	Get full details of a campaign: quality score, validation state, content summary.	Starter	None
delete_campaign	caramel.v1.campaign.delete	Permanently delete a draft. Cannot delete deployed campaigns — pause first.	Starter	None
generate_campaign	caramel.v1.campaign.generate	Generate a campaign using AI from a natural-language prompt.	Growth	Yes
refine_campaign	caramel.v1.campaign.refine	Refine a draft with natural-language feedback. Conversation history is preserved across iterations.	Growth	Yes
deploy_campaign	caramel.v1.campaign.deploy	Deploy an approved campaign. It starts running automatically when triggered by customer activity.	Growth	None
pause_campaign	caramel.v1.campaign.pause	Pause a running campaign. Customers mid-campaign receive no further messages until resumed.	Growth	None
resume_campaign	caramel.v1.campaign.resume	Resume a paused campaign. Customers continue from where they left off.	Growth	None

Plan Generation, refinement, deployment, and lifecycle operations (generate_campaign, refine_campaign, deploy_campaign, pause_campaign, resume_campaign) require Growth tier or higher.

Campaign state machine

Campaigns move through a fixed set of states:

draft → pending_review → approved → deployed ⇄ paused

From	To	Via
(new)	draft	generate_campaign
draft	draft (refined)	refine_campaign
draft	pending_review	Automatic when quality score clears
pending_review	approved	Platform review
approved	deployed	deploy_campaign
deployed	paused	pause_campaign
paused	deployed	resume_campaign
any non-deployed	deleted	delete_campaign

Selected parameters — generate_campaign

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses
prompt	string	Yes	Natural-language description: goal, audience, tone, timing. Example: “Re-engage customers who haven’t visited in 3 months. Warm tone. 20% discount.”
campaign_type	string	No	journey (automated sequence) or broadcast (one-time send). Default: journey.

Selected parameters — refine_campaign

Parameter	Type	Required	Description
campaign_id	string	Yes	Draft campaign ID from generate_campaign
feedback	string	Yes	Natural-language instruction. Example: “Shorten all subject lines to under 8 words.”

templates

Tools for browsing and deploying pre-built campaign templates.

Tool	v1 alias	Description	Tier	Scope
list_template_library	caramel.v1.template.library.list	Browse pre-built templates filtered by tier and industry. Returns journeys, message templates, and segment definitions.	Starter	(any)
deploy_template	caramel.v1.template.library.deploy	Activate a library template into the business’s campaign automation. Provisions segments, message templates, and journeys in dependency order.	Growth	provisioning:write
caramel.v1.template.list	—	List message templates already deployed in the business. Distinct from the pre-built library.	Starter	(any)

Important deploy_template is not idempotent — repeated calls create duplicate workspace entities. Track on your side whether a template has been deployed.

Parameters — list_template_library

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses
limit	integer	No	Maximum results. Default: 20.
type	string	No	journey, template, or segment. Omit for all types.

meta

Tools for API discovery and usage inspection. No business ID required for capabilities.

Tool	v1 alias	Description	Tier	Rate limited?
caramel.v1.meta.capabilities	—	List all available tools, categories, and version. Free — no credits, no business ID, not rate-limited. Cache for the session.	Starter	No
caramel.v1.meta.usage	—	Get this month’s usage for a business: messages sent, forms submitted, AI credits remaining, tier limits.	Starter	Yes

Parameters — caramel.v1.meta.usage

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses

Tip Poll caramel.v1.meta.usage once per day for dashboard widgets — not once per minute. The result includes tier, limits, and remaining quota across all dimensions.

provisioning

Tools for checking and managing sender domains.

Tool	v1 alias	Description	Tier	Scope
caramel.v1.domain.status	—	Check the verification status of sender domains. Returns DNS records, DKIM keys, and approval state per domain.	Starter	provisioning:write

Parameters — caramel.v1.domain.status

Parameter	Type	Required	Description
business_id	string	Yes	Business ID from list_businesses
domain	string	No	Specific domain to check. Omit to return all sender domains for the business.

Deferred tools

These tool names appear in the catalog but are not callable today.

Tool	Status	Blocker
caramel.v1.email.send	Not yet live	Per-tenant sender credential infrastructure
caramel.v1.sms.send	Not yet live	Per-tenant sender credential infrastructure
caramel.v1.whatsapp.send	Not yet live	Meta Tech Provider approval
caramel.v1.push.send	Not yet live	Per-tenant sender credential infrastructure

When these ship they will require Growth tier minimum and messaging:send scope.

Next steps

• Rate limits — understand the per-token and per-IP caps before you build.
• Errors — the full error catalog and retry strategy.
• Tiers and scopes — exact tier and scope requirements per tool.
• Authentication — how to get an OAuth token.