Postkey: Instagram DM Automation and Comment-to-DM

Report what happened on X

postkey_x_record_action

Postkey: Records the outcome of an X action or attempt that postkey_x_check_before_send allowed: whether it worked, with the X post or message id on success. On failure give the error class: rate_limited, forbidden or suspended pause every X action for this profile until a person resumes it in Postkey; not_allowed (this one person does not take DMs) puts them on the STOP list; other changes nothing else. Postkey cannot see X, so it knows only the outcomes recorded here, failed attempts included; a cancelled attempt is recorded as outcome failed with error class other. Refused unknown_event when there is no check for the grant or event. 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	The same kind you checked.
`outcome`	Yes	"ok": X accepted it. "failed": it did not go out, or you cancelled it.
`event_id`	No	For replies: the inbound event id you checked.
`grant_id`	No	The grant_id from the allow answer. Needed for a post; for replies event_id works too.
`result_id`	No	On success: the id of the X post or message that was created. Postkey keeps only a hash.
`error_class`	No	With outcome failed: what kind of error X gave (see above for what each one does). When unsure, use other.

Output Schema

Name	Required	Description
`ok`	Yes	false: refused (isError; code, message, guide_topic, url); no change.
`note`	No	Present when the grant had run out.
`paused`	No	true: X actions are now paused for this profile.
`message`	No	What happened.
`recorded`	No	true: the outcome is in the ledger.
`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 / error_class / description

Previous value: -"On failure: what kind of error X gave. When unsure, use other."New value: +"With outcome failed: what kind of error X gave (see above for what each one does). When unsure, use other."

changedInput schema / properties / outcome / description

Previous value: -"Whether X accepted it."New value: +"\"ok\": X accepted it. \"failed\": it did not go out, or you cancelled it."

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "message": {
+      "description": "What happened.",
+      "type": "string"
+    },
+    "note": {
+      "description": "Present when the grant had run out.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
+      "type": "boolean"
+    },
+    "paused": {
+      "description": "true: X actions are now paused for this profile.",
+      "type": "boolean"
+    },
+    "recorded": {
+      "description": "true: the outcome is in the ledger.",
+      "type": "boolean"
+    },
+    "usage_note": {
+      "description": "Near the month's X allowance: pass on as it is.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}

First observedOct 23, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only say readOnlyHint=false, destructiveHint=false, openWorldHint=false; the description goes well beyond that by disclosing the downstream side effects of each error class (rate_limited/forbidden/suspended pause all X actions for the profile until a human resumes it; not_allowed adds the person to the STOP list; other changes nothing). It also discloses that Postkey cannot observe X and therefore knows only what is recorded here, and that only a hash of result_id is retained.

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

Conciseness3/5

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

The purpose is front-loaded and roughly the right length for a tool with this many side effects, but the error-class sentence is a semicolon-chained run-on ('rate_limited, forbidden or suspended pause every X action for this profile until a person resumes it in Postkey; not_allowed ... other changes nothing else') that is hard to parse on first read. A short bulleted mapping would carry the same content far more clearly.

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 non-destructive mutation with six parameters and an output schema (so return values need no explanation), the description covers prerequisites, per-value consequences, refusal behavior, and the boundary that this tool never touches X itself. An agent has everything needed to invoke it correctly without consulting siblings.

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 earns more because the schema's error_class field literally defers to the description ('see above for what each one does') — the meaning of each enum value and its consequence exists only in the prose. It also clarifies the cancelled-attempt mapping to outcome=failed plus error_class=other.

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 first sentence names a specific verb and resource — 'Records the outcome of an X action or attempt' — and explicitly ties it to the sibling gate postkey_x_check_before_send, so an agent can distinguish it from postkey_send_reply, postkey_create_post, and postkey_x_status without opening any 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 states the prerequisite (a prior check must have allowed the action), the branch conditions (give result_id on success, error_class on failure), the cancelled-attempt convention (record as failed/other), and the refusal case (unknown_event when no check exists). It also rules out an alternative interpretation by saying no X send tool exists and the agent must act with the customer's own X access.

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?