Postkey: Instagram DM Automation and Comment-to-DM

Ask before replying or posting on X

postkey_x_check_before_send

Postkey: Checks one proposed X action before it happens: a reply to a DM, a reply to a post that mentioned the account, or a new post. It checks exactly that text against this profile's STOP list, opt-outs, quiet hours, limits and saved replies. For a reply, pass kind, text, event_id (the id of the DM or of the post that mentioned the account) and contact_id (the sender's numeric X user id, not their @handle); without both ids the answer is deny with code missing_inbound. Example: {"kind":"dm_reply","text":"","event_id":"1846...","contact_id":"88213...","first_in_conversation":true}. The text is expected to be one of the customer's saved replies (postkey_x_list_templates). Postkey keeps only a hash of the text. The answer is allow (with a short-lived grant_id), wait (with retry_at when known), deny (with the reason), or needs_approval (a person must say yes in Postkey first); deny and wait are answers, not errors. When the month's included X actions are used, the answer is deny with code x_free_limit_reached (or wait with code free_daily_limit for the day). A usage_note field may carry the numbers: pass it on as it is. An allow covers exactly that text, and postkey_x_record_action records what happened. Sends nothing to X and no X send tool exists: act with the customer's own X access (full scope: postkey_x_status).

Input Schema

Name	Required	Description
`kind`	Yes	dm_reply: answer a DM the person sent first. mention_reply: answer a post that mentioned or quoted the account. post: a new post.
`text`	Yes	The exact text you plan to send, 1 to 4000 characters. Postkey hashes it and does not keep it.
`event_id`	No	REQUIRED for dm_reply and mention_reply: the id of the inbound DM event, or of the post that mentioned or quoted the account. One reply per id, ever.
`contact_id`	No	REQUIRED for dm_reply and mention_reply: the sender's numeric X user id (not the @handle). Postkey keeps only a hash.
`is_own_post`	No	true if the post you would answer was written by the account itself. Replies to your own posts are refused. Default false.
`inbound_text`	No	Optional: the message you are answering, only so Postkey can look for opt-out words such as STOP. It is checked in this request and dropped.
`first_in_conversation`	No	dm_reply only. Default true. Set false only if the person has already written back; no links are allowed in a first message.
`inbound_looks_like_opt_out`	No	Optional: true if you already found that the inbound message asks to stop (STOP, UNSUBSCRIBE, stop messaging me). The person goes on the STOP list.

Output Schema

Name	Required	Description
`ok`	Yes	false: refused (isError; code, message, guide_topic, url); no change.
`code`	No	wait or deny: why, for example missing_inbound, x_free_limit_reached, free_daily_limit.
`message`	No	The answer in a sentence.
`decision`	No	allow, wait, deny or needs_approval.
`grant_id`	No	allow: pass it to postkey_x_record_action.
`retry_at`	No	Some waits: when to ask again (none for a pause or a check in progress).
`warnings`	No	allow: notes, for example too few saved replies.
`expires_at`	No	allow: when the grant runs out.
`request_id`	No	needs_approval: the request a person answers in Postkey.
`usage_note`	No	Near the month's X allowance: pass on as it is.

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."

Changed3 schema fields changedOct 24, 2026

changedInput schema / properties / is_own_post / description

Previous value: -"True if the post you would answer was written by the account itself. Replies to your own posts are refused."New value: +"true if the post you would answer was written by the account itself. Replies to your own posts are refused. Default false."

changedInput schema / properties / text / description

Previous value: -"The exact text you plan to send. Postkey hashes it and does not keep it."New value: +"The exact text you plan to send, 1 to 4000 characters. Postkey hashes it and does not keep it."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "code": {
+      "description": "wait or deny: why, for example missing_inbound, x_free_limit_reached, free_daily_limit.",
+      "type": "string"
+    },
+    "decision": {
+      "description": "allow, wait, deny or needs_approval.",
+      "type": "string"
+    },
+    "expires_at": {
+      "description": "allow: when the grant runs out.",
+      "type": "string"
+    },
+    "grant_id": {
+      "description": "allow: pass it to postkey_x_record_action.",
+      "type": "string"
+    },
+    "message": {
+      "description": "The answer in a sentence.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
+      "type": "boolean"
+    },
+    "request_id": {
+      "description": "needs_approval: the request a person answers in Postkey.",
+      "type": "string"
+    },
+    "retry_at": {
+      "description": "Some waits: when to ask again (none for a pause or a check in progress).",
+      "type": "string"
+    },
+    "usage_note": {
+      "description": "Near the month's X allowance: pass on as it is.",
+      "type": "string"
+    },
+    "warnings": {
+      "description": "allow: notes, for example too few saved replies.",
+      "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?

Goes far beyond the annotations: explains the four answer types (allow with grant_id, wait with retry_at, deny, needs_approval), the missing_inbound code, quota codes (x_free_limit_reached, free_daily_limit), the usage_note passthrough, and that the text is hashed rather than stored. It also clarifies that deny and wait are answers, not errors.

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?

Front-loads the purpose and flows logically from inputs to answers to the no-send caveat. It is fairly dense with some overlap with the output schema's return values, but nearly every sentence carries operational value.

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?

Given 8 parameters, an output schema, and a mutation-adjacent gate whose answers drive follow-up actions, the description covers inputs, outcomes, quota edge cases, and the key constraint that no X send happens here. Nothing needed to call it correctly is missing.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: contact_id is the sender's numeric X user id, not the @handle; both ids are required for replies; and a full example payload is provided. It reinforces rather than merely repeats the schema.

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?

States a specific verb and scope: 'Checks one proposed X action before it happens' and enumerates the three action kinds. It is clearly distinguishable from sibling send/post tools and names the companion tools (postkey_x_record_action, postkey_x_list_templates, postkey_x_status).

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

Usage Guidelines4/5

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

Explicitly frames this as a pre-send gate and says 'Sends nothing to X and no X send tool exists', which prevents misuse. It also tells the agent the text should come from saved replies. It does not explicitly contrast with postkey_preview_action, but the when-to-use context is clear.

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?