Tools

create_automation

Watch a YouTube channel: every new long-form upload is clipped with the user's Clips Template (charged in Clips hours like a pasted link), and the best clips are posted to the chosen accounts at the posting times, or held for the user's approval in Heavenly. Or, with source "twitch", watch the user's own Twitch channel (connected on the Integrations page): after each stream, the clips viewers made and the streamer's markers (each at most 60 seconds) are clipped and posted the same way; the whole stream is never downloaded. BEFORE calling it, show the user the channel (from find_youtube_channel, or the Twitch account from list_automations), accounts, times, mode and clip choices and get a clear yes.

Access token · publish · Changes account data

Parameters

source string required

"youtube" (default) watches a channel's uploads; "twitch" watches the user's own Twitch streams.

View schema

{
  "description": "\"youtube\" (default) watches a channel's uploads; \"twitch\" watches the user's own Twitch streams.",
  "default": "youtube",
  "type": "string",
  "enum": [
    "youtube",
    "twitch"
  ]
}

channel string required

YouTube: the channel, its id from find_youtube_channel is best. Twitch: the connected account's id from list_automations, or blank when one is connected.

View schema

{
  "examples": [
    "@yourchannel"
  ],
  "description": "YouTube: the channel, its id from find_youtube_channel is best. Twitch: the connected account's id from list_automations, or blank when one is connected.",
  "default": "",
  "type": "string",
  "maxLength": 300
}

accounts array required

Where to post, by network as list_connected_accounts names it ("x", "instagram", "youtube-shorts", "linkedin"...), or "network@accountId" when a network has several accounts. TikTok only with mode "approve".

View schema

{
  "description": "Where to post, by network as list_connected_accounts names it (\"x\", \"instagram\", \"youtube-shorts\", \"linkedin\"...), or \"network@accountId\" when a network has several accounts. TikTok only with mode \"approve\".",
  "minItems": 1,
  "maxItems": 10,
  "type": "array",
  "items": {
    "examples": [
      "x",
      "instagram"
    ],
    "type": "string",
    "minLength": 1,
    "maxLength": 260
  }
}

times array required

Posting times as 24-hour "HH:MM" in the timezone. One clip goes out at each time, the next free one first.

View schema

{
  "description": "Posting times as 24-hour \"HH:MM\" in the timezone. One clip goes out at each time, the next free one first.",
  "minItems": 1,
  "maxItems": 12,
  "type": "array",
  "items": {
    "examples": [
      "09:00",
      "18:30"
    ],
    "type": "string",
    "pattern": "^(?:[01]\\d|2[0-3]):[0-5]\\d$"
  }
}

timezone string required

An IANA timezone, e.g. "America/Los_Angeles".

View schema

{
  "examples": [
    "America/Los_Angeles"
  ],
  "description": "An IANA timezone, e.g. \"America/Los_Angeles\".",
  "type": "string",
  "minLength": 1,
  "maxLength": 100
}

youtube_made_for_kids boolean optional

Required when posting to YouTube: whether the videos are made for kids.

View schema

{
  "description": "Required when posting to YouTube: whether the videos are made for kids.",
  "type": "boolean"
}

youtube_visibility string optional

YouTube visibility (default private).

View schema

{
  "description": "YouTube visibility (default private).",
  "type": "string",
  "enum": [
    "public",
    "unlisted",
    "private"
  ]
}

pinterest_board string optional

Required when posting to Pinterest: the board id.

View schema

{
  "description": "Required when posting to Pinterest: the board id.",
  "type": "string",
  "pattern": "^\\d{1,30}$"
}

mode string required

"approve" (default) holds each clip until the user approves it in Heavenly; "auto" posts at the next free time.

View schema

{
  "default": "approve",
  "description": "\"approve\" (default) holds each clip until the user approves it in Heavenly; \"auto\" posts at the next free time.",
  "type": "string",
  "enum": [
    "auto",
    "approve"
  ]
}

clip_length string optional

How long each clip runs: auto, 15-30, 30-60 (default), 60-90 or 90-180 seconds (Twitch: up to 30-60).

View schema

{
  "description": "How long each clip runs: auto, 15-30, 30-60 (default), 60-90 or 90-180 seconds (Twitch: up to 30-60).",
  "type": "string",
  "enum": [
    "auto",
    "15-30",
    "30-60",
    "60-90",
    "90-180"
  ]
}

focus string optional

What to favor: auto (default), high-retention, story, insight, emotional, funny, controversial, quotes or product.

View schema

{
  "description": "What to favor: auto (default), high-retention, story, insight, emotional, funny, controversial, quotes or product.",
  "type": "string",
  "enum": [
    "auto",
    "high-retention",
    "story",
    "insight",
    "emotional",
    "funny",
    "controversial",
    "quotes",
    "product"
  ]
}

find string optional

Optional: what to look for in each video, in plain words.

View schema

{
  "description": "Optional: what to look for in each video, in plain words.",
  "type": "string",
  "maxLength": 500
}

max_clips integer optional

Clips posted per video or stream, best first (default 3).

View schema

{
  "description": "Clips posted per video or stream, best first (default 3).",
  "type": "integer",
  "minimum": 1,
  "maximum": 10
}

min_score integer optional

Only clips scoring at least this, 0-100 (default 65). YouTube only: a Twitch stream's moments are its viewers' and markers' picks.

View schema

{
  "description": "Only clips scoring at least this, 0-100 (default 65). YouTube only: a Twitch stream's moments are its viewers' and markers' picks.",
  "type": "integer",
  "minimum": 0,
  "maximum": 100
}

replays boolean optional

YouTube only: also clip the replays of the channel's live streams, once YouTube has finished them. A stream is hours long and costs Clips minutes for its length (the first two hours), so leave it off for a channel that streams every day unless that is wanted.

View schema

{
  "description": "YouTube only: also clip the replays of the channel's live streams, once YouTube has finished them. A stream is hours long and costs Clips minutes for its length (the first two hours), so leave it off for a channel that streams every day unless that is wanted.",
  "type": "boolean"
}

live boolean optional

Twitch only: also take the streamer's own clips, and viewers' clips that have proved themselves, while the stream is still on, instead of only after it ends. They count toward max_clips. The first stream clipped this way holds every clip for approval.

View schema

{
  "description": "Twitch only: also take the streamer's own clips, and viewers' clips that have proved themselves, while the stream is still on, instead of only after it ends. They count toward max_clips. The first stream clipped this way holds every clip for approval.",
  "type": "boolean"
}

confirm boolean required

Must be true, and only after the user has approved exactly what you show them.

View schema

{
  "description": "Must be true, and only after the user has approved exactly what you show them.",
  "type": "boolean",
  "const": true
}

Request example

{
  "name": "create_automation",
  "arguments": {
    "source": "youtube",
    "channel": "",
    "accounts": [
      "x"
    ],
    "times": [
      "09:00"
    ],
    "timezone": "America/Los_Angeles",
    "mode": "approve",
    "confirm": true
  }
}

Replace example values with ids and arguments read from your own Heavenly account. This example does not execute a tool.

Returns

The tool result from Heavenly’s workspace, encoded as MCP text content. The connector returns isError when an argument, permission, plan or account check fails.

Account access and permissions are checked by Heavenly. See errors for failure handling.