Skip to main content
Glama
Sign In

Postkey: Instagram DM Automation and Comment-to-DM

by pro.postkey
OverviewDiscussionsAdmin

Attach a library file to a post

postkey_attach_library_item

Postkey: Adds one Library file to a draft post, after the media it already has (the same file twice changes nothing). The id comes from postkey_list_library, or from postkey_finish_upload for a new file. A post that waits in Approvals goes back to a draft. A text post that gets its first file becomes an image or video post. To replace or reorder media, send library_item_ids to postkey_update_post.

Input Schema

NameRequiredDescriptionDefault
post_idYesThe post id (a UUID) from postkey_list_posts or postkey_create_post.
library_item_idYesThe Library file id (a UUID) from postkey_list_library or postkey_finish_upload.

Output Schema

NameRequiredDescriptionDefault
okYesfalse: refused (isError; code, message, guide_topic, url); no change.
noteNoPresent when nothing changed.
statusNoThe post's status after the save.
post_idNoThe post id.
attachedNofalse when the file was already on the post.
warningsNoThings to fix before it can be sent.
media_filesNoFiles on the post now.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • 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."
  2. Changed3 schema fields changed
    • changedInput schema / properties / library_item_id / description
      Previous value: -"The library file id from postkey_list_library."New value: +"The Library file id (a UUID) from postkey_list_library or postkey_finish_upload."
    • 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."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "attached": {
+      "description": "false when the file was already on the post.",
+      "type": "boolean"
+    },
+    "media_files": {
+      "description": "Files on the post now.",
+      "type": "number"
+    },
+    "note": {
+      "description": "Present when nothing changed.",
+      "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"
+    },
+    "status": {
+      "description": "The post's status after the save.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "warnings": {
+      "description": "Things to fix before it can be sent.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}
  3. First observed

TDQS

A4.4/5.0
Behavior4/5

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

The description goes well beyond the annotations by disclosing three non-obvious side effects: re-attaching the same file is a no-op, a post sitting in Approvals is demoted back to draft, and a text post acquiring its first file changes post type. The approval reset is the kind of consequence an agent can't infer from readOnlyHint=false and destructiveHint=false, so this is the main value-add. Slight gap: it doesn't say whether the attach fails or is partial if the file type is unsupported.

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-loaded with the core action and free of filler; each sentence carries a distinct behavior. The leading "Postkey:" vendor prefix is wasted tokens, and the parenthetical about duplicates would read more cleanly as its own clause, but the density is appropriate for a mutation with side effects.

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?

With an output schema present, return values need no explanation, and both parameters are fully covered by the schema. What remains — idempotency, state transitions, post-type mutation, and the correct sibling for editing media — is exactly the information an agent needs before invoking a write operation here.

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 both UUID parameters are already documented in-schema with their source tools, so the description adds little parameter-level meaning. It reinforces the library_item_id origin but does not, for example, clarify ordering or whether duplicates are keyed on id or content.

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?

A specific verb and resource: "Adds one Library file to a draft post, after the media it already has." It states append-position as part of the purpose, which immediately separates it from postkey_update_post, and the closing sentence explicitly names that sibling for replace/reorder cases.

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?

Explicit routing in both directions: use this to append one file, use postkey_update_post to replace or reorder media. It also tells the agent where the id comes from (postkey_list_library for existing files, postkey_finish_upload for new ones), removing the most likely precondition failure.

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 toolsInspect
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