Skip to main content
Glama

schedule_story

Schedule a photo or video to post to Instagram Stories at a future time.

media_url is one publicly fetchable image or video link, the same rule publish_story follows; whether it's a photo or a video story is detected when it's downloaded. scheduled_at is a future, timezone-aware ISO datetime — never guess one: get real slots from get_posting_slots, or use the exact time the user gave you in their own timezone.

One story per call. For several, call this once per file — each is its own story, and several can share one time. They appear in list_scheduled_posts (filter mode="story"); a story has no caption, so identify it by its time. Move one with update_scheduled_post(scheduled_at=...) or remove it with cancel_scheduled_post, both before it goes out.

Stories take media and nothing else — Instagram rejects a caption, hashtags, share-to-feed and comment settings on a story, so this tool doesn't accept them. If the user asks for a captioned story, tell them the text has to be burned into the image or video itself.

automation_id attaches a story-reply automation: once the story is live, replies to it trigger the automation. To post right now, use publish_story.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "workspace_id": "<workspace_id>",
      "ig_account_id": "<ig_account_id>",
      "media_url": "<media_url>",
      "scheduled_at": "<scheduled_at>"
    },
    "name": "schedule_story"
  }
}

Input Schema

NameRequiredDescriptionDefault
media_urlYes
client_tokenNo
scheduled_atYes
workspace_idYes
automation_idNo
ig_account_idYes

Output Schema

NameRequiredDescriptionDefault
modeYes
statusYes
post_idYes
scheduled_atNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare this is a non-read-only, non-destructive, open-world, non-idempotent mutation, but the description adds substantial context: stories reject captions/hashtags/share-to-feed/comments, media type is auto-detected at download, several stories may share one time, and automation_id makes story replies trigger an automation. The gap is client_token, which is presumably the retry-safety mechanism and is unexplained even though idempotentHint is false.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite being multi-paragraph, every sentence carries decision-relevant information and the most critical facts (what it does, media_url rules, scheduled_at rules) are front-loaded. Parenthetical sibling references keep the alternatives compact without bloating the text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, no return-value explanation is needed, and the description fully covers the story-specific behavioral rules an agent must know. It falls short only on the two identifier parameters and the client_token/idempotency story, which matters for a mutation call that could be retried.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description has to carry all parameter meaning, and it covers only three of six: media_url (one publicly fetchable link), scheduled_at (future, timezone-aware ISO datetime, do not guess), and automation_id (story-reply trigger). workspace_id, ig_account_id and especially client_token receive no explanation anywhere, leaving half the surface undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The opening sentence gives a specific verb, resource, target platform (Instagram Stories) and timing (future time), which is exactly what distinguishes it from publish_story. An agent can tell what the tool produces and when it produces it without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes the agent: use publish_story to post right now, get_posting_slots to obtain real time slots rather than guessing, list_scheduled_posts to find stories, and update_scheduled_post / cancel_scheduled_post to manage them. It also states the pre-send constraint on those management paths and instructs the agent to loop this call once per file for multiple stories.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources