# Tool catalog

> All 19 Caramel Public API tools grouped by category, with tier requirements, OAuth scopes, and brief descriptions.

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`](#meta) 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

```json
{
  "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](errors#idempotency).

## 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](rate-limits) — understand the per-token and per-IP caps before you build.
- [Errors](errors) — the full error catalog and retry strategy.
- [Tiers and scopes](tiers-and-scopes) — exact tier and scope requirements per tool.
- [Authentication](../get-started/authentication) — how to get an OAuth token.