Koast

Create a notification in the user's Home inbox — a sign-off request, a to-do, or a deferred-work item. Use `SIGN_OFF` when you have prepared a workflow execution that needs the user's approval before it runs: pass its `workflowExecutionId`, and approving the notification RUNS that execution. Use `TODO` for a task you want the user to remember, and `DEFERRED` for work you have parked for later. NEVER pass brandId/organizationId — the notification is scoped automatically to the current account context. The notification lands PENDING in the user's queue.

create-notification

Create a new pipeline card (ticket/batch) on the board. WRITE. Optionally set the starting stage, attach creatives, and assign teammates.

create-pipeline-ticket

Create a new structure template from an engine StructureState you constructed for the user. Validates the rules against the engine before saving and requires at least one audience. Use after translating the user's natural-language description into a representable StructureState (validate it first). WRITE.

author-structure-template

Permanently delete a monitoring automation by automationId. WRITE — destructive.

delete-automation

Permanently delete a Koast batch (campaign launch) or pipeline card, together with the campaigns, ad sets and ads it holds in the Koast tree. A pipeline card IS a batch, so this removes either. This does NOT touch anything on the ad platform: already-published campaigns keep running and keep spending — pause them with update-node first if that is the intent. Irreversible. WRITE — destructive.

delete-batch

Delete a saved CAMPAIGN-SNAPSHOT template. This cannot be undone. Does not affect structure templates.

delete-snapshot-template

Permanently delete a saved STRUCTURE template by templateId. Cards already populated from it are not affected. Irreversible. WRITE — destructive.

delete-structure-template

Permanently delete a workflow by workflowId. WRITE — destructive.

delete-workflow

Distribute a single creative across multiple ad sets or campaigns. Either creates a new ad per target (newAdPerTarget) or replaces the first existing ad (replaceFirstAd).

distribute-creative

Duplicate an ad set or ad, including all its settings and children. Supports batch duplication with count parameter — use count instead of calling this tool multiple times.

duplicate-node

Duplicate a campaign/ad set/ad N times, varying ONE specific settings path across the copies. `vary.path` is a dotted path into the settings schema — call `get-settings-schema` first to confirm the path is valid. Common paths: 'targeting.ageRange', 'targeting.locations', 'targeting.interests', 'optimization.bidAmount', 'optimization.bidStrategy', 'budget.dailyAmount', 'budget.lifetimeAmount'. `vary.values` must be the list of variant values (one per copy, length must equal `count`).

duplicate-and-vary

Update an existing structure template's rules/audiences/settings. Pass the full new StructureState in `config` (validated before save). Omit templateId to edit the template open in the builder. WRITE.

edit-structure-template-rules

Generate ad copy (headlines, primary text, descriptions) and store it as a copyGenerationId. The id is what the user later approves and attaches via update-node — generation alone does not change any ad. Brand context (name, URL, business type, voice) is auto-loaded server-side — never ask the user for any of that.

generate-copy

Configured naming convention templates for an account (campaign/adset/ad). It is the source for how campaigns, ad sets and ads in that account are named. Pass `accountId` explicitly when account scope was resolved via list-my-ad-accounts (multi-account / all-accounts dashboard); omit only when a single account is already locked-in by the dashboard context. Do NOT infer the convention from campaign/adset/ad names in get-campaign-tree — the real convention lives here and may differ from historical names.

get-account-naming-convention

Roll up spend and results across the Koast batches on an ad account — NOT the whole ad account: campaigns that were never launched through Koast are not counted, and at most 10 batches are sampled (the payload reports batchesSampled). For a true account-wide figure, or for campaigns launched outside Koast, use list-account-campaigns. Pass `accountId` explicitly when account scope was resolved via list-my-ad-accounts (multi-account / all-accounts dashboard); omit only when a single account is already locked-in by the dashboard context.

get-account-overview

Check ad review and delivery status on the ad platform for the current campaign launch. Surfaces disapprovals, limited delivery, and ads still in review — the silent killers of delivery. One call covers all three levels at once: `issues` holds one entry per ad that has a review or delivery problem (ads with none are absent), and `adsetStatuses` and `campaignStatuses` hold the status of every live ad set and campaign. There is no level parameter — review issues only ever attach at the ad level on the platform.

get-ad-delivery-status

Full ad details: creative, copy, links, CTA, tracking. Use when the user asks about a specific ad.

get-ad-details

Full adset details: settings, targeting, budget, schedule, placements, optimization, assets, links. Use when the user asks about a specific adset by ID, name, or 'this ad set'. Do NOT use get-campaign-tree for adset details — it returns only names and IDs.

get-adset-details

Look up available options for any asset or targeting type. Use this when the user wants to select a pixel, facebook page, audience, interest, location, or conversion event. Types: pixels, facebookPages, instagramAccounts, audiences, interests, locations, conversionEvents.

get-available-options

Get one monitoring automation (rules + actions + frequency + scope) by automationId. Read-only.

get-automation

Returns the Koast-tracked campaign STRUCTURE (campaign → adset → ad tree with IDs and names only) for a given campaign launch. Use ONLY to discover IDs or verify what's in Koast. Do NOT use for: ad/adset details (use get-adset-details / get-ad-details), campaigns not yet in Koast (use list-account-campaigns), naming conventions (use get-account-naming-convention), or creative fatigue (use compute-creative-fatigue). Does NOT include settings, metrics, or creative data. `campaignLaunchId` is required on every call.

get-campaign-tree

Fetch daily-breakdown insights (time_increment=1) for the current campaign launch at campaign/adset/ad level. Returns ONE ROW PER DAY, not one row per entity: `level` chooses which entities are read, then every entity for a date is added together, and `entities` on each day says how many were. There are no per-entity ids in the response, so do NOT report a day as belonging to a single ad. `reach` is null whenever entities > 1, because reach counts unique people and cannot be summed across entities. Each day carries spend, impressions, clicks, reach, entities, frequency, hook_rate, hold_rate, results, resultActionType, cpa (cost per result), ctr, cpm.

get-insights-daily

Get a previously generated copy by its ID. Shows headlines, primary text, descriptions, and variations.

get-copy

Get performance metrics at campaign / adset / ad level for the current launch. Pass `level` to scope the request; optionally pass `id` to scope to a specific entity or omit for all. Returns impressions, clicks, spend, CTR, CPC, conversions and per-level collections.

get-metrics

Get current settings (budget, targeting, schedule, placements, optimization) for one or MANY nodes. To read several nodes, pass them all in `nodes` in a SINGLE call — do NOT call this tool once per node. One call with `nodes: [{nodeId, nodeType}, …]` returns every node's settings at once and is dramatically faster than repeated single-node calls. Use `nodeId`+`nodeType` only for a single node.

get-settings

Get the configurable settings for a given section and node type. Returns setting paths, types, valid values, and example update payloads. Use this BEFORE updating settings to know the exact format. Every path is owned by one level (campaign, ad set or ad) and is written on that level only: nothing cascades, so a value meant for every ad set is written to each ad set. Sections: budget, targeting, schedule, placements, optimization, links, assets, conversion, enhancements, naming, adCategory, leadForm, shop.

get-settings-schema

Get one structure template (config + settings + audiences + accounts) by templateId. Omit templateId to read the template open in the builder (Current Context). Read-only.

get-structure-template

Return a human-readable summary of a structure template's engine rules (creative count, ad sets, placement/split, custom-rule flags, ops) and the distribution it will produce (sets x creatives). Use this to explain what a template does before applying. Read-only.

get-structure-template-rules

Get available targeting options including audiences, locations, demographics, interests, and behaviors. Use this to help users configure targeting.

get-targeting-options

Fetch the team activity log — who changed what and when — for an account or brand. Use for Team Report workflow. Pass `accountId` explicitly when account scope was resolved via list-my-ad-accounts (multi-account / all-accounts dashboard). `brandId` is also accepted when only the brand is known (e.g. legacy locked-in callers). Omit both only when a single brand is already locked-in by the dashboard context.

get-team-activity-log

Get one workflow (spec + nodes + trigger + status) by workflowId. Read-only.

get-workflow

Get the status and per-node results of a single workflow execution. Read-only.

get-workflow-execution

Import existing campaigns from the ad platform into the current campaign launch. Pulls campaign structure including ad sets and ads. Pass `sourceAdAccountId` to pull from a DIFFERENT ad account than the batch's own — resolve that account with list-my-ad-accounts, list its campaigns with list-account-campaigns({ accountId }), then import the chosen ids. The import runs in the BACKGROUND — large campaigns may still be syncing when this tool returns; in that case it reports "still importing", which is NOT a failure.

import-campaigns

Import a live campaign (one that exists in the ad account on the ad platform but NOT yet in Koast) into a Koast batch, so it becomes both reportable AND extendable. Idempotent — if a Koast batch already wraps this `providerCampaignId`, returns its `campaignLaunchId` and `alreadyExisted: true` instead of duplicating. For metrics, fatigue or details on a campaign from `list-account-campaigns` that has no Koast batch yet, call this FIRST to obtain a `campaignLaunchId`, then run normal launch-scoped reporting tools against it. THIS IS ALSO HOW YOU ADD TO A LIVE CAMPAIGN: import it, then add-adset / add-ads against the returned `campaignLaunchId` and launch-campaign, and the new ad sets and ads are published INTO the existing campaign rather than into a new one. Never tell a user that adding an ad set to a live campaign has to be done in the ad platform's own manager — it does not.

import-live-campaign

List Koast batches (campaign launches) — these are the user's drafts and in-progress launches stored in the Koast DB, separate from live campaigns on the ad platform. It is the source for the user's work in Koast, not for what runs on the ad platform. Pass `accountId` to scope to one ad account; otherwise uses the current page/account context. Status filter accepts: PENDING, RUNNING, COMPLETED, COMPLETED_WITH_ISSUES, ACTION_REQUIRED, FAILED, CANCELLED. Read-only.

list-koast-batches

Lists ALL campaigns in the brand's ad account on its ad platform, including those NOT imported to Koast. It is the source for what exists in the ad account itself, as opposed to what Koast tracks. Do NOT use get-campaign-tree — that returns only Koast-tracked data. Pass `accountId` explicitly when account scope was resolved via list-my-ad-accounts (multi-account / all-accounts dashboard); omit only when a single account is already locked-in by the dashboard context.

list-account-campaigns

List monitoring automations (rule-based per-brand watchers that run actions like pause/notify on live campaigns). Read-only. Optionally filter by brandId and status.

list-automations

Lists the brands this connection can work on, with each brand's ad provider and which brand is active. Most tools operate on the active brand; templates, workflows and pipeline columns are shared across the whole organisation.

list-brands

List the user's saved CAMPAIGN-SNAPSHOT templates (full campaign-tree snapshots of an existing launch). These are NOT structure templates (rule-based blueprints) — for those use listStructureTemplates.

list-snapshot-templates

Browse the active brand's creative library — the images and videos available to put in ads. Returns a `creativeId` for each, which is the id add-ads, distribute-creative and swap-creatives take. Newest first; filter with `search` and `kind`, or pass `creativeIds` to look up an explicit set. Read-only: listing changes nothing. To add a creative that is not here yet, use upload-creative.

list-creatives