campaign_plan_create

Write down what you intend to run: the channels, the audience, the money and the dates.

Ask the agent to write down what you intend to run. It creates a Campaign Plan as a draft, and it buys nothing.

“Create a Campaign Plan for the Acme spring sale: €5,000 in euros, from 1 March to 31 May 2026.”

The agent calls campaign_plan_create. You see the new Campaign Plan, its slug and its figures. The brand, the envelope, the dates and the body can come later. The body is one markdown document: why this split, and how the result will be judged. Each amount is in whole units of the currency: you give euros, not cents.

Plan a campaign walks the whole job.

Reference

Create a Campaign Plan: what this organization intends to run, on which channels, for whom, for how much, over what period. Only a name, a description (a one-line summary) and a currency are required — the window, the budget envelope, the brand and the body are all authored incrementally. The body is one markdown document: why this money goes to these channels, and how success will be judged. Amounts are whole units of the plan’s currency: send 40.5 for €40.50, never 4050. The plan starts as a draft. A Campaign Plan is AdCrunch’s own planning document — it is not a campaign on Meta or Google. For those, use list_campaigns and get_campaign.

Input

Argument	Type	Required	Description
`body`	string, 1 to 50000 characters	no	The long markdown document of the plan: why this money goes to these channels, how success will be judged, and anything else a reviewer reads. It is what a person approves. Up to 50,000 characters.
`brand_name`	string	no	The slug of the brand this plan is for. Optional and changeable later — a plan may precede its brand, or cover several.
`currency`	string, 3 characters	yes	ISO 4217, e.g. EUR. Changeable until a Line Item carries a budget, frozen after that.
`description`	string	yes	One-line summary used to pick this plan from a list.
`end_date`	string	no	Omit for an always-on plan. Line Items inherit this when they set no end of their own — and a line with no effective end reads as a daily rate.
`name`	string	yes	Display name, e.g. “Q4 Acquisition”.
`slug`	string	no	Optional explicit slug handle; normalized to kebab-case. Defaults to one derived from the name.
`start_date`	string	no
`total_budget`	number, at least 0	no	The envelope: what you have, in whole units of the plan currency (40.5 is 40.50). Omit for “no declared constraint” — which is not the same as zero.

Output

A successful call returns this object in structuredContent.

Field	Type	Always present	Description
`campaignPlan`	object	yes	The Campaign Plan as it is now, with the number of its Line Items. `line_item_list` gives the Line Items.
`campaignPlan.allocation`	object	yes	The money of the Campaign Plan. AdCrunch calculates it on each read and does not store it.
`campaignPlan.allocation.allocated`	number or null	yes	The sum of the Line Item budgets, in whole units of the currency. `null` when the Line Items with a budget do not share a unit.
`campaignPlan.allocation.comparable`	boolean	yes	`false` when the Line Items with a budget mix totals and daily rates. Then no sum exists: say “not comparable”, and do not add the budgets.
`campaignPlan.allocation.unallocated`	number or null	yes	The envelope less the allocated sum. It can be negative. `null` when the envelope is not set, when the Line Items do not share a unit, or when the unit is `daily`.
`campaignPlan.allocation.unit`	one of `total`, `daily` or null	yes	The unit that the Line Items with a budget share. `null` when no Line Item has a budget, or when the Line Items do not share a unit.
`campaignPlan.assignees`	array of object	yes	The current members who are accountable for the record, oldest first, at most 10. An Assignee grants no access.
`campaignPlan.assignees[].id`	string	yes	The `usr_…` id of the member.
`campaignPlan.assignees[].name`	string	yes	The name of the member.
`campaignPlan.body`	string or null	yes	The long markdown document of the Campaign Plan: the argument for the split, how the result is judged, and anything else a reviewer reads. `null` when nobody wrote it.
`campaignPlan.brand`	object or null	yes	The Brand that the Campaign Plan is for, or `null` when it has no Brand or its Brand was deleted.
`campaignPlan.brand.name`	string	yes	The display name of the Brand.
`campaignPlan.brand.slug`	string	yes	The slug of the Brand. Each tool takes it as `brand_name`.
`campaignPlan.brandId`	string or null	yes	The Brand that the Campaign Plan is for, `brd_…`, or `null`.
`campaignPlan.commentCount`	number	yes	The number of live Comments on the Campaign Plan, replies included. List them with `campaign_plan_comment_list`.
`campaignPlan.createdAt`	number	yes	Milliseconds since the Unix epoch, UTC.
`campaignPlan.createdBy`	string	yes	The user who created the Campaign Plan, `usr_…`.
`campaignPlan.currency`	string	yes	ISO 4217. Each amount of the Campaign Plan and of its Line Items is in whole units of this currency. It cannot change after a Line Item has a budget.
`campaignPlan.description`	string	yes	One sentence that tells the Campaign Plan apart in a list.
`campaignPlan.endDate`	string or null	yes	The last day of the Campaign Plan, or `null`. With no end date, the Campaign Plan is always on, and the budget of a Line Item with no end date of its own is a daily rate.
`campaignPlan.id`	string	yes	The id of the Campaign Plan, `cpl_…`.
`campaignPlan.lineItemCount`	number	yes	The number of live Line Items of the Campaign Plan. List them with `line_item_list`.
`campaignPlan.name`	string	yes	The display name.
`campaignPlan.revision`	number	yes	The revision of the Campaign Plan. It increments when the Campaign Plan changes. Send it as `base_revision` to `campaign_plan_update` or `campaign_plan_delete`. A Line Item has a revision of its own.
`campaignPlan.slug`	string	yes	The slug of the Campaign Plan. Each tool takes it as `campaign_plan_name`.
`campaignPlan.startDate`	string or null	yes	The first day of the Campaign Plan, or `null`.
`campaignPlan.status`	one of `draft`, `approved`	yes	`approved` when a person approved the content at this revision in the AdCrunch console. It is a record, not a gate: the provider write tools do not check it. A real change to the Campaign Plan, or a Line Item that is added or deleted, returns it to `draft`.
`campaignPlan.totalBudget`	number or null	yes	The envelope: the money that you have, in whole units of `currency`. `null` means no declared limit, not zero.
`campaignPlan.updatedAt`	number or null	yes	When the Campaign Plan last changed, or `null` when it never changed.

Failure codes

A failed call has isError set, and structuredContent.error holds one of these codes. Errors describes the shape of a failed call.

not_found
invalid_slug
invalid_currency
invalid_amount
invalid_window
slug_conflict
organization_unentitled
forbidden
invalid_request
internal_error

Scope

The token must hold campaign_plan:write. Auth & scopes lists each scope.

Annotations

A client reads these hints. A hint that the tool does not declare has the default value of the MCP specification.

Writes. The tool can change data.
Not destructive. The tool makes only additive changes.
Not idempotent. A second call with the same arguments can change more.
Closed world. The tool reads and writes the data of AdCrunch only.

Example

The arguments:

{
  "body": "## Why this split\n\nMeta carries the reach. One Line Item keeps the budget in one place.\n\n## How it will be judged\n\nRevenue in the window, against the spring of 2025.",
  "brand_name": "acme",
  "currency": "EUR",
  "description": "The spring sale of Acme, on Meta, in France and Belgium.",
  "end_date": "2026-05-31",
  "name": "Spring Sale 2026",
  "slug": "spring-sale",
  "start_date": "2026-03-01",
  "total_budget": 5000
}

The result, in structuredContent:

{
  "campaignPlan": {
    "allocation": {
      "allocated": 0,
      "comparable": true,
      "unallocated": 5000,
      "unit": null
    },
    "assignees": [],
    "body": "## Why this split\n\nMeta carries the reach. One Line Item keeps the budget in one place.\n\n## How it will be judged\n\nRevenue in the window, against the spring of 2025.",
    "brand": {
      "name": "Acme",
      "slug": "acme"
    },
    "brandId": "brd_6a9c33",
    "commentCount": 2,
    "createdAt": 1768435200000,
    "createdBy": "usr_5d2b71",
    "currency": "EUR",
    "description": "The spring sale of Acme, on Meta, in France and Belgium.",
    "endDate": "2026-05-31",
    "id": "cpl_4e1a08",
    "lineItemCount": 0,
    "name": "Spring Sale 2026",
    "revision": 1,
    "slug": "spring-sale",
    "startDate": "2026-03-01",
    "status": "draft",
    "totalBudget": 5000,
    "updatedAt": null
  }
}