ShapelessAI

List posts

posts_list

Read-only

The post queue: proposed drafts, scheduled posts, published history, newest first. For "my best posts": sort views ranks every published post by views (metrics.latest.impressions) across the whole history, narrowed by platform, connectionId, minViews and since. Each reading carries its fetchedAt; fresh re-reads the listed posts' numbers older than 6h from the platforms first (slower, up to ~30s). Needs the read scope.

Input Schema

TableJSON Schema

Name	Required	Description
`sort`	No	recent (default) or views: published posts, most viewed first.
`fresh`	No	Re-read stale numbers from the platforms before answering.
`limit`	No	How many posts, 1-200. Default 50.
`since`	No	With sort views: keep posts published at or after this ISO time.
`status`	No	Keep only posts in this state.
`minViews`	No	With sort views: keep posts with at least this many views.
`platform`	No	With sort views: one platform (platforms_list ids).
`connectionId`	No	With sort views: one connected account (connections_list).

Output Schema

TableJSON Schema

Name	Required	Description	Default
`posts`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 14, 2026

addedInput schema / properties / connectionId

Added value: +{
+  "description": "With sort views: one connected account (connections_list).",
+  "type": "string"
+}

addedInput schema / properties / fresh

Added value: +{
+  "description": "Re-read stale numbers from the platforms before answering.",
+  "type": "boolean"
+}

addedInput schema / properties / limit

Added value: +{
+  "description": "How many posts, 1-200. Default 50.",
+  "type": "number"
+}

addedInput schema / properties / minViews

Added value: +{
+  "description": "With sort views: keep posts with at least this many views.",
+  "type": "number"
+}

addedInput schema / properties / platform

Added value: +{
+  "description": "With sort views: one platform (platforms_list ids).",
+  "type": "string"
+}

addedInput schema / properties / since

Added value: +{
+  "description": "With sort views: keep posts published at or after this ISO time.",
+  "type": "string"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "recent (default) or views: published posts, most viewed first.",
+  "enum": [
+    "recent",
+    "views"
+  ],
+  "type": "string"
+}

Changed1 schema field changedOct 7, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "posts": {
+      "items": {
+        "additionalProperties": true,
+        "properties": {
+          "connectionId": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "error": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "handoffNote": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "id": {
+            "type": "string"
+          },
+          "mediaKeys": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          },
+          "platform": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "postText": {
+            "type": "string"
+          },
+          "publishedLocation": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "scheduledAt": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "status"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "posts"
+  ],
+  "type": "object"
+}

First observedSep 29, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Annotations already declare readOnly/non-destructive, yet the description adds real behavior: a fetchedAt per reading, that fresh re-reads numbers older than 6h from the platforms first, that this is slower (up to ~30s), and that the read scope is required. These authentication and latency traits go well beyond the structured safety hints.

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 queue definition, then the alternate ranking mode, then the behavioral caveats. Dense and slightly run-on but every clause carries information; nothing is padding.

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 the description still covers modes, filtering semantics, refresh behavior, latency and the required scope. For an 8-parameter read tool this is complete enough to call correctly.

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 baseline is 3, but the description adds the 6h staleness threshold that qualifies fresh and explains that platform/connectionId/minViews/since only narrow the sort=views ranking. That is genuine meaning beyond the schema's own text.

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 (list) and resource (the post queue spanning proposed drafts, scheduled posts, published history) and exposes a distinct mode ('my best posts' via sort=views). An agent can position it against posts_get, posts_create and the other posts_* siblings without opening the schema.

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?

Clearly frames the two usage modes – the default newest-first queue versus sort=views for ranking published posts by impressions – and names the scoping inputs (platform, connectionId, minViews, since). It does not name an alternative sibling or state a when-not, so it stops short of a full routing rule.

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

All ShapelessAI 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.