Skip to main content
Glama
Sign In

PostPen

by ai.postpen
OverviewDiscussionsAdmin

List posts

list_posts
Read-only

Lists this account’s drafts, scheduled posts, or sent posts. Each row includes has_media, media_count, media_type (photo, video, or pdf), and media_urls stored on the content row, which show whether media is attached, media_alt_text (the alt text of each image, aligned with media_urls, null for an image without it; null when there are no images), plus first_comment and auto_react when set, mentions (the company pages tagged in the text), created_via (where the post was written: the PostPen editor or the agent that saved it; null when not recorded), preview_url (a link that opens the post in PostPen), publish_to_linkedin (false when it only goes to other networks), and networks: each network the post goes to with its destination id, the text it publishes there, status (draft, scheduled, processing, published, or failed), url once published, error, failed_at (when it failed), and deleted_at (when someone deleted the published post on X, Facebook, Instagram, Threads or YouTube; PostPen checks published posts from time to time, and url is then null; LinkedIn posts are not checked), and first_comment: what happened to the post’s first comment on that network ({ status: posted, skipped or failed, note saying why, url where the network gives one }; null on LinkedIn or when there was none).

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "status": "<status>"
    },
    "name": "list_posts"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoHow many rows to return. Defaults to 50.
statusYesWhich queue to read.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

B3.4/5.0
Behavior4/5

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

Annotations already declare readOnlyHint/openWorldHint/destructiveHint, so safety is covered. The description still adds genuine behavioral context beyond that: periodic checks of published posts, url becoming null after deletion, and LinkedIn posts explicitly not being checked — real caveats an agent cannot get from the schema.

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

Conciseness2/5

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

The description is a single ~200-word run-on sentence that front-loads the purpose but then buries the reader in dense, comma-chained field enumeration with nested parentheticals. No structure, bullets, or grouping makes the return-shape information hard to parse, and much of it repeats itself (media_urls/media_alt_text alignment, first_comment described twice).

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

Completeness3/5

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

With no output schema, documenting return fields is justified, and the description covers many of them plus data-freshness caveats. However, it omits ordering and pagination behavior (only 'limit' is in the schema) and the second, nested description of first_comment per-network conflicts in granularity with the earlier one, leaving the return contract somewhat muddled.

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 parameters (limit, status) are fully documented in the schema with bounds and enum. The description adds nothing about parameter semantics, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first clause gives a specific verb and resource: 'Lists this account's drafts, scheduled posts, or sent posts', which maps cleanly onto the required status enum. It is clearly distinguishable from siblings like get_post_stats or list_comments, though it never names them explicitly.

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

Usage Guidelines3/5

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

Usage is only implied through the status values (draft, scheduled, sent) restated in the opening sentence; there is no explicit when-to-use, when-not-to-use, or pointer to alternatives such as get_post_stats for metrics. The agent must infer that this is the enumeration tool for queues.

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

All PostPen 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