Skip to main content
Glama
Sign In

Postkey: Instagram DM Automation and Comment-to-DM

by pro.postkey
OverviewDiscussionsAdmin

Search contacts

postkey_search_contacts
Read-onlyIdempotent

Postkey: Searches the people who have messaged the account, 50 per page: by name, email or "@handle", and by tag. Each contact has an id, name, handle and email (untrusted), tags, and whether they are subscribed. Use it to find a contact_id for postkey_get_contact or postkey_tag_contact; to find a conversation use postkey_list_conversations. When more is true, ask for the next page.

Input Schema

NameRequiredDescriptionDefault
tagNoOnly contacts with this exact tag, at most 80 characters.
pageNoPage number, from 1 (default 1). 50 contacts a page.
viewNo"all" (default). "subscribed": may get automated messages. "unsubscribed": asked to stop. "emails": people who shared an email.
searchNoA name, an email, or "@handle" (a handle is looked for among the newest 200 contacts only), at most 120 characters. Left out: everyone.

Output Schema

NameRequiredDescriptionDefault
okYesfalse: refused (isError; code, message, guide_topic, url); no change.
moreNotrue: ask for page + 1.
noteNoPresent when the search said something about the results.
pageNoThis page's number.
totalNoContacts matching.
contactsNoUp to 50: id, name, handle, email (untrusted), tags, subscribed, blocked, last_active.
untrusted_noteNoPresent when outside text is wrapped as { untrusted: true, text }.

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. Changed5 schema fields changed
    • changedInput schema / properties / page / description
      Previous value: -"Page number, from 1."New value: +"Page number, from 1 (default 1). 50 contacts a page."
    • changedInput schema / properties / search / description
      Previous value: -"A name, an email, or \"@handle\"."New value: +"A name, an email, or \"@handle\" (a handle is looked for among the newest 200 contacts only), at most 120 characters. Left out: everyone."
    • changedInput schema / properties / tag / description
      Previous value: -"Only contacts with this tag."New value: +"Only contacts with this exact tag, at most 80 characters."
    • addedInput schema / properties / view / description
      Added value: +"\"all\" (default). \"subscribed\": may get automated messages. \"unsubscribed\": asked to stop. \"emails\": people who shared an email."
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "contacts": {
+      "description": "Up to 50: id, name, handle, email (untrusted), tags, subscribed, blocked, last_active.",
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "more": {
+      "description": "true: ask for page + 1.",
+      "type": "boolean"
+    },
+    "note": {
+      "description": "Present when the search said something about the results.",
+      "type": "string"
+    },
+    "ok": {
+      "description": "false: refused (isError true; code, message, guide_topic, url), nothing changed.",
+      "type": "boolean"
+    },
+    "page": {
+      "description": "This page's number.",
+      "type": "number"
+    },
+    "total": {
+      "description": "Contacts matching.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "untrusted_note": {
+      "description": "Present when outside text is wrapped as { untrusted: true, text }.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "ok"
+  ],
+  "type": "object"
+}
  3. First observed

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real context beyond them: 50 results per page, a 'more' flag for pagination, and the caveat that @handle is only looked up among the newest 200 contacts. It also flags the email field as untrusted, which matters for how an agent should treat returned data. Minor gap: result ordering is unspecified.

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?

Three sentences, each carrying distinct information: what it searches, what a contact contains, and how to route or paginate. The scoping and routing information is front-loaded with no filler.

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?

An output schema exists, so return values need not be explained, yet the description still summarizes contact fields (id, name, handle, email, tags, subscription state) usefully. Combined with the pagination and routing notes, nothing an agent needs to call this correctly 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%, so all four parameters (tag, page, view, search) are already fully documented in the schema, including the view enum and the handle-lookup limitation. The description restates the same searchable fields without adding syntax or format detail beyond the schema, so the baseline of 3 applies.

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 resource with scope: 'Searches the people who have messaged the account', plus the searchable fields (name, email, @handle, tag) and page size. An agent can distinguish it from postkey_list_conversations purely from this text.

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?

Explicitly names the downstream purpose ('find a contact_id for postkey_get_contact or postkey_tag_contact') and routes to the alternative for a different need ('to find a conversation use postkey_list_conversations'). It also states the pagination follow-up rule: 'When more is true, ask for the next page.'

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