postly_list_postsLists recent Postly posts, optionally filtered by workspace and status. Returns sanitized post summaries for the authenticated connection.
| Name | Required | Description | Default |
|---|---|---|---|
| skip | No | ||
| limit | No | ||
| status | No | Optional status such as draft, scheduled, queued, processing, pending_approval, or unknown. | |
| workspace_id | No | Optional Postly workspace ID. |
| Name | Required | Description | Default |
|---|---|---|---|
| posts | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal read-only and idempotent. Description adds that results are sanitized and scoped to the authenticated connection, providing useful behavioral context without contradicting annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action, then states optional filters and return type. No unnecessary words, perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and strong annotations, the description covers purpose, filters, and the scope of results. It's complete for a list operation, and the mention of sanitized summaries adds useful context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers status and workspace_id with descriptions. Description reinforces these as filters but does not clarify skip/limit semantics; however, their names and defaults are self-explanatory. With 50% schema coverage, the description partially compensates but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists recent Postly posts with optional filters, using a specific verb and resource. It distinguishes from siblings like postly_get_post and postly_list_scheduled_posts by emphasizing 'recent' and 'sanitized summaries'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use for listing posts with optional workspace/status filters. However, it doesn't explicitly mention alternatives or when not to use it, such as for retrieving a single post or scheduled posts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
Each tool targets a distinct resource and action: posts, analytics, media, schema, validation, targets, and organizational metadata are clearly separated. Even similar getters (post, post_status, post_analytics, publishing_activity) have explicit scopes that prevent misselection.
All tools follow the consistent `postly_<verb>_<noun>` pattern in lowercase snake_case. Verbs like create, get, list, update, delete, upload, validate, and resolve are used uniformly, making the API predictable and easy to navigate.
At 18 tools, the set is slightly above the typical 3-15 range, but every tool serves a distinct purpose in the social media publishing lifecycle. The count is justified for a comprehensive MCP, though a few could potentially be consolidated without loss of clarity.
The tool surface covers the full post lifecycle (create, read, update, delete, list), scheduling, publishing activity, analytics for both accounts and posts, media upload, channel schema validation, and target resolution. No obvious dead ends or critical missing operations for the intended domain.