Automation scenarios tools

search_scenarios: List the automation scenarios in a project, or fetch one by ID.
list_scenario_nodes: Get a lightweight node skeleton for a scenario.
get_scenario_node: Get the full configuration of a single node in a scenario.
create_scenario: Create a new scenario as a draft.
update_scenario: Replace the full definition of a draft or inactive scenario.
delete_scenario: Permanently delete a draft or inactive scenario.

🚧
Warning
Write tools change your live configuration. Just like changes made in the Marketing dashboard, actions your users or agents take with these tools can have a substantial impact on your campaigns, automations, and customer communications. There is no automatic rollback and activity logging is limited, so review every change and confirm the target before applying it.

search_scenarios

Searches the scenarios (automation flow campaigns) in a project, or fetches one by ID. Scenarios are multi-step flows with triggers, conditions, waits, and actions. Omit scenario_id to list all scenarios as summary records: name, status, tags, archived flag, and initiative assignment. The node graph is excluded from the list — pass scenario_id, or use the lighter-weight list_scenario_nodes, to explore it.

Pass scenario_id to fetch the complete scenario definition, including the trigger, every node in the flow graph (waits, conditions, actions, A/B splits), the connections array of graph edges, and metadata. Email and SMS design payloads are stripped from nodes by default to keep responses manageable. Set include_node_designs to true to include them, though design blobs can be 70 KB or more per node.

Detail mode is the most reliable way to learn the connection edge schema before you write a scenario. Read the connections array from a scenario that already works, then mirror that shape in create_scenario or update_scenario. Note that customer_filter is read-only here and effectively always null: audience scoping lives on a Condition node inside the graph, not on the scenario itself.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str \| null`	No	The scenario ID. Omit to list all; provide to fetch one.
`include_node_designs`	`bool`	No	When fetching a single scenario, include the full email or SMS design payload in action nodes. Ignored when `scenario_id` is omitted. Defaults to false.

Response parameters

The tool returns a ScenariosResponse when scenario_id is omitted, or a ScenarioResponse when it's provided.

The ScenariosResponse object has the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`list[ScenarioSummary]`	The scenario summaries.
`error`	`str \| null`	Error message if the request failed.

The ScenarioSummary object has the following fields:

Field	Type	Description
`id`	`str`	The scenario's unique ID.
`name`	`str`	The scenario's display name.
`status`	`str`	One of `draft`, `active`, `inactive`, `finishing`, or `finished`.
`archived`	`bool`	Whether the scenario has been archived.
`tags`	`list[str]`	User-defined tags.
`initiative_id`	`str \| null`	The initiative this scenario belongs to, if any.
`is_global_object`	`bool \| null`	Whether the scenario is a global, shared object.
`created`	`any \| null`	Unix timestamp of when the scenario was created.
`created_by_display_name`	`str \| null`	Display name of the creator.
`edited`	`any \| null`	Unix timestamp of the last edit.
`edited_by_display_name`	`str \| null`	Display name of the last editor.

When scenario_id is provided, the tool returns a ScenarioResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`data`	`Scenario \| null`	The full scenario definition.
`error`	`str \| null`	Error message if the request failed.

The Scenario object adds the following fields on top of the summary record:

Field	Type	Description
`trigger`	`any \| null`	The entry trigger: an event, a schedule, or an API call.
`nodes`	`list[any]`	The scenario node graph. Each node is one step in the flow — a wait, an action, a condition, an A/B split, and so on.
`connections`	`list[any]`	The graph edges. Each entry is `{"source": {"node_id", "connector_index"}, "destination": {"node_id", "connector_index"}}`. A destination `connector_index` is usually `0`, the input port. On a `condition` source, `1` is the match branch and `2` is the don't-match branch. On an `ab-split` source, outputs start at `1`.
`customer_filter`	`any \| null`	Read-only, and effectively always null. Audience scoping belongs on a Condition node, not here.
`max_customers`	`int \| null`	The maximum number of customers allowed in the scenario at one time.

list_scenario_nodes

Returns a lightweight skeleton of a scenario's node graph: just the node IDs, types, names, and the connections (edges) between them. Use this to explore a scenario's structure before pulling individual nodes with get_scenario_node.

The scenario is fetched once and cached for 60 seconds, so back-to-back calls to list_scenario_nodes and get_scenario_node on the same scenario share a single underlying request.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.

Response parameters

The tool returns a ScenarioNodesResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`scenario_id`	`str`	The scenario's ID.
`scenario_name`	`str`	The scenario's display name.
`nodes`	`list[ScenarioNodeSummary]`	A lightweight list of nodes: ID, type, and name only.
`connections`	`list[any]`	The graph edges. Each entry has a `source` (`node_id` plus `connector_index`) and a `destination`. On every node but a trigger, index `0` is the input port, so output branches start at `1`. On a `condition`, `1` is the match branch and `2` is the don't-match branch. On an `ab-split`, `1` is the first variant, `2` the second, and so on.
`trigger`	`any`	The entry trigger configuration for the scenario.
`error`	`str \| null`	Error message if the request failed.

The ScenarioNodeSummary object has the following fields:

Field	Type	Description
`id`	`int`	The numeric node ID, unique within the scenario.
`type`	`str`	The node type, for example `send-email-action`, `condition`, `wait-action`, or `ab-split`.
`name`	`str \| null`	An optional display label set by the scenario author.
`incoming_connections`	`list[any]`	The edges arriving at this node from parent nodes. Empty for entry-point trigger nodes.
`outgoing_connections`	`list[any]`	The edges leaving this node toward child nodes. On branching nodes, `connector_index` identifies which branch, numbered from `1`.

get_scenario_node

Returns the full configuration for a single node in a scenario, along with the incoming and outgoing edges. The scenario is fetched once and cached for 60 seconds, so this is efficient to call repeatedly on the same scenario.

The design payload on action nodes (email or MMS templates) is omitted by default because a single design can run to 70 KB or more. Set include_design to true if you need the template content.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.
`node_id`	`int`	Yes	The numeric node ID. Use `list_scenario_nodes` to discover node IDs.
`include_design`	`bool`	No	If true, include the `design` field on action nodes. Defaults to false.

Response parameters

The tool returns a ScenarioNodeResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the request succeeded.
`scenario_id`	`str`	The scenario this node belongs to.
`node`	`any \| null`	The full node configuration. The shape varies by node type.
`incoming_connections`	`list[any]`	The edges arriving at this node from parent nodes. Empty for entry-point nodes.
`outgoing_connections`	`list[any]`	The edges leaving this node toward child nodes. On branching nodes, `connector_index` identifies which branch, numbered from `1`. Empty for terminal nodes.
`error`	`str \| null`	Error message if the request failed or the node was not found.

create_scenario

Creates a new scenario (automation flow). The scenario is always created as a draft — it does not run until it is activated in the Marketing UI. On success, the tool returns the ID of the new scenario.

The payload requires a name, a nodes list with at minimum one trigger node, a connections list of edges between nodes (empty for a trigger-only scenario), and a last_node_id set to the highest node ID present in nodes. A trigger node's type can be on-event-trigger, on-api-trigger, on-date-attribute-trigger, repeated-trigger, planned-trigger, or now-trigger, and each type has its own required sub-fields.

Every edge in connections must use one exact shape: a source and a destination, each an object holding a node_id and a connector_index. Nothing else works. The backend returns an HTTP 400 for {source, target}, {from, to}, {source_id, target_id}, and a bare [src, tgt] array. To see the shape on a live scenario, call search_scenarios with a scenario_id and read its connections.

Index 0 is a node's input port everywhere except on a trigger, where it's the trigger's single output. So a destination is nearly always 0, and a source is 0 only when the source is a trigger. Anywhere else, 0 as a source fails with Source connector doesn't exist. On a condition source, 1 is the match branch and 2 is the don't-match branch. On an ab-split source, outputs start at 1 for the first variant. A wait-action source uses 1. Most action nodes, send-email-action among them, use 1 for success and 2 for failure.

Keep customer_filter off the scenario top level. The scenario model has no top-level customer_filter field, so the backend used to drop the key without complaint and save the scenario as send-to-everyone. The tool now rejects a top-level customer_filter before it calls the backend. Audience scoping belongs on a Condition node, as a customer_filter on a node whose type is condition, since that's the one place the backend stores and evaluates one. Condition-node filters are shape-checked up front, which catches the frequent slips: equal to is a number operator and strings need equals, attribute.type is property rather than customer_property, and every operand needs {"type": "constant", "value": ...} rather than a bare value.

Recurring schedules have their own rules. repeated-trigger and on-date-attribute-trigger share a backend model, so both need a timezone plus times, or minutes when repeat is hourly. The real field names are repeat, days, times, timezone, from_date, and to_date. times holds a list of {hour, minute} objects rather than a string such as 09:00, and weekly days are numbered 1 to 7. There's no yearly repeat and no every-N-intervals frequency. The names repeat_type, repeat_frequency, repeat_on_days, start_date, end_date, and repeat_at_time never existed on the backend, which dropped them and saved a plain daily schedule, so the tool rejects them along with a missing times or timezone.

Failures return success: false with the detail in error. Pre-flight checks report every problem they find in a single message. A backend rejection arrives as HTTP <status>: <field>: <message>, for example HTTP 400: nodes.0.days: Day 0 is out of range 1 - 7, which tells you the node and field to fix.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`payload`	`dict`	Yes	The scenario definition. Requires `name`, `nodes`, `connections`, and `last_node_id`. Each edge in `connections` must be `{'source': {'node_id': int, 'connector_index': int}, 'destination': {'node_id': int, 'connector_index': int}}`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the newly created scenario.
`error`	`str \| null`	The pre-flight message, or the HTTP status and the backend's field-level validation detail, if the operation failed.

update_scenario

Replaces the full definition of an existing scenario with the payload you provide (PUT semantics), so pass the complete scenario, not just the fields you want to change. The scenario must be in draft or inactive status — running scenarios cannot be modified, and status transitions such as activate and stop must be done through the Marketing UI.

Start by fetching the current definition with search_scenarios(scenario_id=...). Add include_node_designs=True when the scenario has email or SMS action nodes, because PUT semantics would otherwise drop the stripped design payloads and wipe your templates. Modify the fields you need, then pass the whole object here. Keep existing node IDs intact, since the backend matches nodes by ID and treats a changed ID as deleting the old node and creating a new one. Set last_node_id to the highest node ID in the nodes array, and update it whenever you add nodes.

Edges in connections use the same single accepted shape as create: a source and a destination, each with a node_id and a connector_index. A destination is nearly always 0, the input port. On a condition source, 1 is the match branch and 2 is the don't-match branch, and 0 is invalid as a source. On an ab-split source, outputs start at 1.

Two constraints catch people out on update in particular. A top-level customer_filter is rejected before any backend call, so if you fetched an audience-scoped scenario, leave its filter where you found it on the Condition node instead of lifting it to the top. And recurring triggers must use the real field names repeat, days, times, timezone, from_date, and to_date, since the legacy repeat_type, repeat_frequency, repeat_on_days, start_date, end_date, and repeat_at_time names are rejected up front.

Failures return success: false with the detail in error, either the combined pre-flight message or a backend rejection as HTTP <status>: <field>: <message>, for example HTTP 400: nodes.0.times: This field is required.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios` or `create_scenario`.
`payload`	`dict`	Yes	The full updated scenario definition, in the same shape as create. Fetch the current scenario with `search_scenarios(scenario_id=...)` first, then change only what you need.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	The ID of the updated scenario.
`error`	`str \| null`	The pre-flight message, or the HTTP status and the backend's field-level validation detail, if the operation failed.

delete_scenario

Permanently deletes a scenario. The scenario must be in draft or inactive status — running scenarios cannot be deleted. This action is irreversible: the scenario and all its node configuration are removed, and there is no undo through this tool, so verify the target before you run it.

Find scenario IDs with search_scenarios. A refused delete, a running scenario for example, comes back as success: false with the HTTP status and the backend's message in error rather than a bare status code.

Request parameters

Name	Type	Required?	Description
`project_id`	`str`	Yes	The project ID returned by `list_projects`.
`scenario_id`	`str`	Yes	The scenario ID returned by `search_scenarios`.

Response parameters

The tool returns a WriteResponse object with the following parameters:

Parameter	Type	Description
`success`	`bool`	Whether the operation succeeded.
`id`	`str \| null`	Not present for deletes.
`error`	`str \| null`	The HTTP status and the backend's message if the delete failed.