MCP tool
generate_plan
Generate one brand-level media plan on ctv, audio, tv, cinema, dooh, search, social for a persona: budget split with reasoning, adapter-grounded forecasts (reach/impressions/CPM), flighting, and modeled total reach/frequency. Optionally choose the exact native Search and Social buyers; each selected provider receives its own reviewable budget line. Budget is in pounds sterling. Returns the draft plan with its id and line items — review it, then approve_plan to create a campaign.
Input
Pass fields from this schema as the tool arguments. Runtime ownership, product scope and readiness checks still apply.
Input JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"personaId": {
"type": "string",
"description": "persona id to plan for"
},
"budgetPounds": {
"type": "number",
"minimum": 0.01,
"maximum": 19000000,
"description": "total budget in GBP pounds, e.g. 15000"
},
"goal": {
"type": "string",
"enum": [
"awareness",
"consideration",
"performance"
],
"description": "campaign goal"
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "flight start, YYYY-MM-DD"
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "flight end, YYYY-MM-DD (must be after startDate)"
},
"channels": {
"description": "optional narrower channel selection; defaults to this product’s permitted channels",
"minItems": 1,
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
}
},
"commercialBrief": {
"description": "optional commercial and measurement context; monetary fields are integer pence",
"type": "object",
"properties": {
"productOrOffer": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"landingPageUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"primaryKpi": {
"type": "string",
"enum": [
"reach",
"brand-awareness",
"consideration",
"site-visits",
"leads",
"sales",
"app-installs",
"custom"
]
},
"conversionDefinition": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"outcomeSource": {
"type": "string",
"enum": [
"campaign-tracking",
"analytics",
"crm",
"commerce",
"offline",
"none"
]
},
"targetValueMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"baselineWeeklyConversions": {
"type": "integer",
"minimum": 0,
"maximum": 10000000
},
"priorMonthlyMediaSpendMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"existingMediaMix": {
"maxItems": 11,
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social",
"display",
"email",
"print",
"other"
]
}
},
"firstPartyDataAvailability": {
"type": "string",
"enum": [
"none",
"limited",
"ready"
]
},
"creativeReadiness": {
"type": "string",
"enum": [
"needs-production",
"in-progress",
"ready"
]
},
"measurementIntent": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"delivered",
"responded",
"caused",
"remembered"
]
}
},
"exclusions": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
},
"mandatories": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
}
},
"required": [
"productOrOffer",
"primaryKpi",
"outcomeSource",
"existingMediaMix",
"firstPartyDataAvailability",
"creativeReadiness",
"measurementIntent",
"exclusions",
"mandatories"
],
"additionalProperties": false
},
"paidMediaAdapterKeys": {
"description": "exact unique paid-media buyers for this brand plan; Google/Microsoft are Search and Meta/TikTok are Social",
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"google-ads",
"microsoft-ads",
"meta-ads",
"tiktok-ads"
]
}
}
},
"required": [
"personaId",
"budgetPounds",
"goal",
"startDate",
"endDate"
]
}REST mapping and authority
The tool wraps this REST endpoint. The mapping identifies path/query/body transformations and approval or idempotency headers.
Request contract
{
"method": "POST",
"path": "/api/v1/plans/generate",
"pathFields": [],
"pathSchema": {
"type": "object",
"properties": {},
"additionalProperties": false
},
"pathEncoding": "encodeURIComponent for each path field",
"governedAction": null,
"headers": {},
"bodySchema": {
"type": "object",
"properties": {
"personaId": {
"type": "string",
"description": "persona id to plan for"
},
"goal": {
"type": "string",
"enum": [
"awareness",
"consideration",
"performance"
],
"description": "campaign goal"
},
"startDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "flight start, YYYY-MM-DD"
},
"endDate": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "flight end, YYYY-MM-DD (must be after startDate)"
},
"channels": {
"description": "optional narrower channel selection; defaults to this product’s permitted channels",
"minItems": 1,
"maxItems": 7,
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social"
]
}
},
"commercialBrief": {
"description": "optional commercial and measurement context; monetary fields are integer pence",
"type": "object",
"properties": {
"productOrOffer": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"landingPageUrl": {
"type": "string",
"maxLength": 2048,
"format": "uri"
},
"primaryKpi": {
"type": "string",
"enum": [
"reach",
"brand-awareness",
"consideration",
"site-visits",
"leads",
"sales",
"app-installs",
"custom"
]
},
"conversionDefinition": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"outcomeSource": {
"type": "string",
"enum": [
"campaign-tracking",
"analytics",
"crm",
"commerce",
"offline",
"none"
]
},
"targetValueMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"baselineWeeklyConversions": {
"type": "integer",
"minimum": 0,
"maximum": 10000000
},
"priorMonthlyMediaSpendMinor": {
"type": "integer",
"minimum": 0,
"maximum": 2000000000
},
"existingMediaMix": {
"maxItems": 11,
"type": "array",
"items": {
"type": "string",
"enum": [
"ctv",
"audio",
"tv",
"cinema",
"dooh",
"search",
"social",
"display",
"email",
"print",
"other"
]
}
},
"firstPartyDataAvailability": {
"type": "string",
"enum": [
"none",
"limited",
"ready"
]
},
"creativeReadiness": {
"type": "string",
"enum": [
"needs-production",
"in-progress",
"ready"
]
},
"measurementIntent": {
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"delivered",
"responded",
"caused",
"remembered"
]
}
},
"exclusions": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
},
"mandatories": {
"maxItems": 20,
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 300
}
}
},
"required": [
"productOrOffer",
"primaryKpi",
"outcomeSource",
"existingMediaMix",
"firstPartyDataAvailability",
"creativeReadiness",
"measurementIntent",
"exclusions",
"mandatories"
],
"additionalProperties": false
},
"paidMediaAdapterKeys": {
"description": "exact unique paid-media buyers for this brand plan; Google/Microsoft are Search and Meta/TikTok are Social",
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"google-ads",
"microsoft-ads",
"meta-ads",
"tiktok-ads"
]
}
},
"budgetMinor": {
"type": "integer",
"minimum": 1,
"maximum": 1900000000
},
"currency": {
"const": "GBP",
"type": "string"
}
},
"additionalProperties": false,
"required": [
"personaId",
"goal",
"startDate",
"endDate",
"budgetMinor",
"currency"
]
},
"bodyMapping": {
"passthroughOtherFields": true,
"budgetMinor": {
"from": "budgetPounds",
"transform": "Math.round(value * 100)"
},
"constants": {
"currency": "GBP"
},
"channels": "Supplied channels; if omitted on a scoped surface, its permitted channels. Otherwise omitted."
},
"responseMapping": "REST JSON is returned as MCP structuredContent and a compatibility text block; privacy-sensitive tools validate their output schema."
}Output
This is the registered MCP output envelope. Nested fields are only modeled where the schema explicitly defines them.
Output JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"plan": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"plan"
],
"additionalProperties": {}
}Safety annotations
MCP annotations
{
"readOnlyHint": false,
"destructiveHint": false,
"idempotentHint": false,
"openWorldHint": true
}Annotations help a client present the tool. The API independently enforces authorization and exact action approvals. Error and retry guidance →