Tools

schedule_clip

Put a clip on the calendar as a video post to connected accounts (list_connected_accounts). Exports it at 1080p first if needed: while it renders this returns export_pending, so call again. The post is HELD until mark_post_ready. BEFORE calling, show the user the clip, caption, networks and time and get a clear yes. run_at is ISO 8601, at least 10 minutes ahead. TikTok is refused: use Heavenly's composer.

Access token · publish · Changes account data

Parameters

caption string required

The post's text.

View schema

{
  "description": "The post's text.",
  "type": "string",
  "maxLength": 20000
}

networks array required

Connected networks to post to (from list_connected_accounts), e.g. x, youtube-shorts.

View schema

{
  "description": "Connected networks to post to (from list_connected_accounts), e.g. x, youtube-shorts.",
  "minItems": 1,
  "maxItems": 12,
  "type": "array",
  "items": {
    "type": "string",
    "minLength": 1,
    "maxLength": 40
  }
}

run_at string required

When it goes out, ISO 8601, at least 10 minutes ahead.

View schema

{
  "description": "When it goes out, ISO 8601, at least 10 minutes ahead.",
  "type": "string",
  "format": "date-time",
  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-]\\d{2}:\\d{2})))$"
}

title string optional

Title, for networks that take one (YouTube).

View schema

{
  "description": "Title, for networks that take one (YouTube).",
  "type": "string",
  "maxLength": 400
}

timezone string optional

IANA timezone the time was chosen in.

View schema

{
  "description": "IANA timezone the time was chosen in.",
  "type": "string",
  "maxLength": 100
}

job_id string required

The Clips job id (from clip_video or list_clip_jobs).

View schema

{
  "description": "The Clips job id (from clip_video or list_clip_jobs).",
  "type": "string",
  "format": "uuid",
  "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000)$"
}

clip_id string required

A clip's id, from list_clips.

View schema

{
  "description": "A clip's id, from list_clips.",
  "type": "string",
  "minLength": 1,
  "maxLength": 150
}

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": "schedule_clip",
  "arguments": {
    "caption": "YOUR_CAPTION",
    "networks": [
      "YOUR_NETWORKS"
    ],
    "run_at": "2030-01-01T12:00:00.000Z",
    "job_id": "00000000-0000-4000-8000-000000000001",
    "clip_id": "YOUR_CLIP_ID",
    "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.