Postkey: Instagram DM Automation and Comment-to-DM

Schedule or publish a post

postkey_schedule_post

Destructive

Postkey: Schedules or publishes an existing post (from postkey_create_post) to its social accounts. when "now" publishes right away, "at" at the time in at, "queue" at the next free slot of the profile's posting schedule. This PUBLISHES to real social accounts and cannot be undone once it is live. With publish_policy confirm_in_chat (the default) it goes out with no approval in Postkey: asking for this post at this time is the yes. With publish_policy held_in_postkey it is NOT sent: it goes to Posts > Approvals with the time you asked for, and the result has waiting_for_approval true, which is not an error: do not call it again or say it was sent. A full weekly post limit is refused plan_limit; a held post is checked again when approved. Call postkey_preview_action first. When the profile has more than one social account on a platform, ask the person which; never default to all. Each social account a post goes to counts once against posts_per_week.

Input Schema

Name	Required	Description
`at`	No	Required with when "at", refused otherwise: ISO 8601 with a UTC offset, for example 2026-11-02T09:00:00-05:00 (or Z for UTC). A time without an offset may be read in the wrong zone; the profile's own zone is account.time_zone in postkey_get_started, and for "today" or "tomorrow" use its account.today_local and account.tomorrow_local (the UTC date may already be the next day). The answer says the time back as understood_as.
`when`	Yes	"now": publish right away. "at": at the time in at. "queue": the next free posting slot; refused queue_empty when the profile has no posting times (a person sets them).
`post_id`	Yes	The post id (a UUID) from postkey_list_posts or postkey_create_post.
`preview_id`	No	Optional: the preview_id postkey_preview_action gave for exactly these arguments today (UTC). Approvals then shows the person that you showed them the preview. A preview_id that does not match is ignored, never refused.

Output Schema

Name	Required	Description
`ok`	Yes	false: refused (isError; code, message, guide_topic, url); no change.
`status`	No	The post's status.
`message`	No	What happened.
`post_id`	No	The post id.
`accounts`	No	Each social account's result: platform, handle, ok, status, message.
`warnings`	No	Notes from the posting service.
`published`	No	true: it went out now. false: scheduled, or waiting for approval.
`scheduled`	No	true: it is on the schedule.
`request_id`	No	The held request: read it with postkey_get_approval or postkey_list_waiting_for_approval. A post held in Posts > Approvals has none.
`held_because`	No	Why it waits on a direct connection.
`scheduled_for`	No	When it goes out (UTC).
`understood_as`	No	With when "at": the time read, as utc, local and time_zone.
`posts_left_this_week`	No	On a plan with a weekly post limit: posts left this week.
`waiting_for_approval`	No	true: NOT sent; waits for a person in Approvals.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedNov 9, 2026

changedOutput schema / properties / ok / description

Previous value: -"false: refused (isError true; code, message, guide_topic, url), nothing changed."New value: +"false: refused (isError; code, message, guide_topic, url); no change."

Changed5 schema fields changedOct 24, 2026

changedInput schema / properties / at / description

Previous value: -"Only with when \"at\": the time, ISO 8601 with a UTC offset."New value: +"Required with when \"at\", refused otherwise: ISO 8601 with a UTC offset, for example 2026-11-02T09:00:00-05:00 (or Z for UTC). A time without an offset may be read in the wrong zone; the profile's own zone is account.time_zone in postkey_get_started, and for \"today\" or \"tomorrow\" use its account.today_local and account.tomorrow_local (the UTC date may already be the next day). The answer says the time back as understood_as."

changedInput schema / properties / post_id / description

Previous value: -"The post id."New value: +"The post id (a UUID) from postkey_list_posts or postkey_create_post."

changedInput schema / properties / preview_id / description

Previous value: -"Optional: the preview_id postkey_preview_action gave for exactly these arguments. The person then sees in Approvals that you showed them the preview."New value: +"Optional: the preview_id postkey_preview_action gave for exactly these arguments today (UTC). Approvals then shows the person that you showed them the preview. A preview_id that does not match is ignored, never refused."

changedInput schema / properties / when / description

Previous value: -"When it goes out."New value: +"\"now\": publish right away. \"at\": at the time in at. \"queue\": the next free posting slot; refused queue_empty when the profile has no posting times (a person sets them)."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "accounts": {
+      "description": "Each social account's result: platform, handle, ok, status, message.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "held_because": {
+      "description": "Why it waits on a direct connection.",
+      "type": "string"
+    },
+    "message": {
+      "description": "What happened.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
+      "type": "boolean"
+    },
+    "post_id": {
+      "description": "The post id.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "posts_left_this_week": {
+      "description": "On a plan with a weekly post limit: posts left this week.",
+      "type": "number"
+    },
+    "published": {
+      "description": "true: it went out now. false: scheduled, or waiting for approval.",
+      "type": "boolean"
+    },
+    "request_id": {
+      "description": "The held request: read it with postkey_get_approval or postkey_list_waiting_for_approval. A post held in Posts > Approvals has none.",
+      "type": "string"
+    },
+    "scheduled": {
+      "description": "true: it is on the schedule.",
+      "type": "boolean"
+    },
+    "scheduled_for": {
+      "description": "When it goes out (UTC).",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "status": {
+      "description": "The post's status.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "understood_as": {
+      "description": "With when \"at\": the time read, as utc, local and time_zone.",
+      "type": "object"
+    },
+    "waiting_for_approval": {
+      "description": "true: NOT sent; waits for a person in Approvals.",
+      "type": "boolean"
+    },
+    "warnings": {
+      "description": "Notes from the posting service.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedOct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already flag destructive=true and openWorld=true, but the description adds critical context the annotations cannot convey: the publish is irreversible once live, confirm_in_chat means no in-app approval step exists, held_in_postkey results in waiting_for_approval=true which is not an error and must not be retried, and a full weekly limit returns plan_limit. It also discloses the posts_per_week accounting rule per social account.

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

Conciseness4/5

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

The core action and the irreversibility warning are front-loaded, and every clause carries operational value (approval modes, error semantics, account selection). It is dense and somewhat run-on with minor duplication of the when enum already in the schema, which keeps it just short of a 5.

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

Completeness5/5

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

For a destructive, open-world publish tool this covers the full decision surface: mode selection, preview prerequisite, approval-policy outcomes, the not-an-error waiting state, quota refusal, and multi-account ambiguity. Return values are covered by the output schema, so nothing essential is missing.

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 100% and the schema already documents the when enum, the at ISO-8601-with-offset requirement, post_id UUID format, and preview_id tolerance for mismatches. The description mostly restates those enum meanings rather than adding new parameter-level meaning, so the baseline of 3 applies; the per-account posts_per_week note is behavioral rather than parameter semantics.

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?

"Schedules or publishes an existing post (from postkey_create_post) to its social accounts" gives a specific verb, a specific resource, and explicitly distinguishes creation from scheduling/publishing, which separates it from postkey_create_post and postkey_unschedule_post. The three scheduling modes are named immediately after.

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 spells out exactly when to use each mode ("when 'now' publishes right away, 'at' at the time in at, 'queue' at the next free slot"), instructs to call postkey_preview_action first, and tells the agent to ask the person which account to use rather than defaulting to all. It also names postkey_get_started as the source of the profile time zone, so the agent knows where to route a prerequisite lookup.

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

All Postkey: Instagram DM Automation and Comment-to-DM tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources

Need Help?