Prompt - Colossal

The Prompt step runs an LLM over your store data. It can read orders, customers, products, and analytics, and — when you opt in — write back through the same tools. Each write tool is gated by an approval policy you set on the step. Use AI reasoning when simple conditions aren’t enough: deciding if a customer is a VIP, screening an order for fraud, or letting the agent pick which Notion page to update based on what it finds.

Configuration

configuration

object

Show properties

prompt

string

required

Instructions for the AI (10-4000 characters). Supports data access variables.

output_schema

object

required

JSON Schema defining the expected output. Must include type or properties.

enabled_tools

string[]

default:"[]"

Allowlist of tools the agent can call. Empty means reasoning only.

tool_safety

object

default:"{}"

Per-app write-action approval policy. See Tool approval below.

skills

string[]

default:"[]"

Craft skills the agent loads on demand. See Skills below.

max_iterations

integer

default:"10"

Maximum tool call rounds (1-25)

timeout_minutes

integer

default:"5"

Maximum execution time (1-15 minutes)

Tools

Tools come in two kinds: read (fetch data) and write (modify data). Both kinds are listed in the same catalog and selected the same way through enabled_tools. Write tools are off by default — you opt them in per step. Selectors you can put in enabled_tools:

A bare name picks one built-in tool (e.g. "get_order_details")
"colossal__{service}__*" picks every built-in in that service group (e.g. "colossal__orders__*")
"app__{integration}__*" picks every tool from a connected integration
"app__{integration}__{action}" picks one tool from that integration

Built-in tools

See the tools catalog for the full input and output schema of each. Read tools are always safe to enable. Write tools are off by default and gated by tool_safety.

Integration tools

Every action from a connected integration shows up in the catalog under app__{integration}__{action}. Read actions (HTTP GET) are tagged read; everything else is tagged write. Notion, Slack, Zendesk, Supabase, and any other installed integration contribute their full action list.

Tool approval

tool_safety sets the approval policy for each app’s write tools. Read tools never consult this field.

{
  "tool_safety": {
    "app__notion": { "default": "always_ask", "overrides": {} },
    "colossal__orders": { "default": "never_ask", "overrides": {} }
  }
}

Each entry has:

Field	Type	Description
`default`	`"always_ask"` \| `"never_ask"` \| `"custom"`	App-wide default for write calls
`overrides`	`object`	Per-tool overrides. Only consulted when `default` is `"custom"`. Each value is `"ask"` or `"auto"`.

always_ask is the safe default. Leaving tool_safety empty ({}) means every app falls back to always_ask — every write call pauses for human review.

What happens at runtime

When the agent calls a write tool that resolves to ask:

Run pauses

The run status flips to Paused.

Approval requested

The step appears in the activity log with status Awaiting approval, showing the tool name, arguments, and the agent’s reasoning excerpt.

Approve or deny

Approve runs the tool with the agent’s chosen arguments and the run resumes. Deny sends a denial message back to the agent (which keeps reasoning) — the run does not cancel.

When the call resolves to auto, the tool runs inline with no pause. Multiple write tool calls in a single agent turn each get their own approval row. The run resumes once every decision is in.

This is different from the approval step. Approval steps pause at a fixed point in the graph — useful when the workflow has already computed the action. Per-tool approval pauses inside the AI reasoning step — useful when the agent picks the action at runtime.

Output schema

The output_schema defines the structure the AI must return. It must be a valid JSON Schema with either type or properties at the top level:

{
  "type": "object",
  "properties": {
    "is_vip": { "type": "boolean" },
    "reason": { "type": "string" }
  }
}

The output is validated. If validation fails, the AI retries with feedback. Subsequent steps reference output fields as {{steps.<step_id>.<field>}}.

Skills

The skills field names craft guidance the agent can load while it works. Skills are writing craft, not data access. Use enabled_tools for data.

Skill	Use when
`colossal-seo-content`	The step writes editorial or SEO copy: a guide, roundup, comparison, or article body, usually feeding a storefront builder step

The agent sees each skill’s name and description, and reads the full instructions only when relevant. An empty list means no extra skills.

Examples

Reasoning only
Read-only investigation
Write tool with approval

No tool calls — pure prompt-and-output.

{
  "id": "summarize_order",
  "type": "ai_reasoning",
  "prompt": "Write a one-line summary of this order for the activity log.",
  "output_schema": {
    "type": "object",
    "properties": { "summary": { "type": "string" } }
  },
  "enabled_tools": []
}

Reads available; no writes.

{
  "id": "vip_check",
  "type": "ai_reasoning",
  "prompt": "Decide if this customer is a VIP based on order history.",
  "output_schema": {
    "type": "object",
    "properties": { "is_vip": { "type": "boolean" }, "reason": { "type": "string" } }
  },
  "enabled_tools": ["colossal__orders__*", "colossal__customers__*"]
}

Default approval policy is always_ask. Each write call pauses the run for human approval.

{
  "id": "tag_priority",
  "type": "ai_reasoning",
  "prompt": "Look at the customer's history and tag this order with a fulfillment priority by calling update_order_metadata.",
  "output_schema": {
    "type": "object",
    "properties": {
      "fulfillment_priority": { "type": "string", "enum": ["high", "normal"] },
      "reason": { "type": "string" }
    }
  },
  "enabled_tools": [
    "colossal__orders__*",
    "colossal__customers__*",
    "update_order_metadata"
  ],
  "tool_safety": {}
}

Result

Each AI reasoning step produces:

result

object

Show properties

success

boolean

Whether the step completed successfully

output

object

The structured output matching your schema

error

string

Error message if the step failed

iterations_used

integer

Number of tool call rounds used

execution_time_ms

integer

Total execution time in milliseconds

tool_calls

array

List of tools invoked with their arguments

model

string

The model that was used

Use cases

VIP detection: ai_reasoning outputs a structured {is_vip, reason}, a downstream action step writes the order metadata.
Fraud screening: ai_reasoning decides whether the order is suspicious, an approval step gates the action that creates the Zendesk ticket.
Smart routing: ai_reasoning categorises the request, a choice step branches.
Inventory cleanup: ai_reasoning step calls archive_product directly per matching variant — the agent picks which products to act on at runtime.

The first three use ai_reasoning to produce a structured decision; downstream action/choice steps execute on it. Use that shape when the write target is fixed by the trigger and the decision should be observable in steps.<id>.output. Use the inline write-tool shape (the inventory cleanup case) when the agent must search for the target or make a variable number of writes per run.

Next steps

Approval step. Pause at a fixed point for a human-confirmed deterministic action
App action. Run a deterministic write with known inputs
Data access. Reference trigger and step data in prompts and output schemas

​Configuration

​Tools

​Built-in tools

​Integration tools

​Tool approval

​What happens at runtime

​Output schema

​Skills

​Examples

​Result

​Use cases

​Next steps

Configuration

Tools

Built-in tools

Integration tools

Tool approval

What happens at runtime

Output schema

Skills

Examples

Result

Use cases

Next steps