Postly MCP

List Media

postly_list_media

Read-onlyIdempotent

Lists durable stored media, or recovers one upload by idempotency_key. Recovery distinguishes processing, completed, and unknown. Respect retry_after_seconds; use media only when storage confirms completion. Requires media.read.

Input Schema

Name	Required	Description
`limit`	No	Maximum number of files to return.
`offset`	No	Number of stored files to skip.
`idempotency_key`	No	Recover a specific upload using its returned key instead of listing files. An unknown result may still be in progress; retry uploads only with this same key.

Output Schema

Name	Required	Description	Default
`code`	No
`files`	No
`status`	No
`message`	No
`pagination`	No
`media_library`	No
`idempotency_key`	No
`retry_after_seconds`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 10, 2026
- addedOutput schema / properties / media_library
```
Added value: +{
+  "type": "object"
+}
```
Changed1 schema field changedSep 29, 2026
- addedOutput schema / properties / retry_after_seconds
```
Added value: +{
+  "type": "integer"
+}
```

Changed3 schema fields changedSep 17, 2026

addedInput schema / properties / idempotency_key

Added value: +{
+  "description": "Recover a specific upload using its returned key instead of listing files. An unknown result may still be in progress; retry uploads only with this same key.",
+  "type": "string"
+}

addedOutput schema / properties / idempotency_key
```
Added value: +{
+  "type": "string"
+}
```
addedOutput schema / properties / status
```
Added value: +{
+  "type": "string"
+}
```

AddedSep 16, 2026

TDQS

A3.7/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), and the description still adds real value: the recovery state vocabulary (processing/completed/unknown), retry_after_seconds behavior, and the 'unknown may still be in progress' nuance. The media.read permission requirement is also disclosed, which annotations do not cover.

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?

Four tight sentences with the primary list behavior and the recovery mode front-loaded, and no wasted words. The telegraphic 'Respect retry_after_seconds' phrase is slightly compressed but still earns its place.

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

Completeness4/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 not be explained, and the description covers both modes, recovery states, retry behavior, and the auth requirement. Pagination semantics for limit/offset are left to the schema, a minor gap for a list tool.

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 limit, offset, and idempotency_key are already documented in the schema, setting the baseline at 3. The description echoes the idempotency_key recovery semantics and references retry_after_seconds (an output field) but adds no format or syntax detail beyond what the schema already provides.

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?

States a specific verb and resource ('Lists durable stored media') and adds a clearly distinct second mode ('recovers one upload by idempotency_key'). This separates it from the upload siblings (postly_upload_media, postly_upload_media_batch), though no sibling is named explicitly, so it falls just short of a 5.

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?

'use media only when storage confirms completion' and the idempotency_key recovery path give conditional usage rules beyond the schema. However there is no explicit when-to-use-vs-alternatives statement (e.g. vs postly_get_post or the upload tools), so guidance is implied rather than spelled out.

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

All Postly MCP 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.

Resources

Need Help?