Upload-Post

Official

Overview Schema Source Related Servers Discussions Admin

Create media upload

create_media_upload

Stages local media (video, image, or document) for publishing: returns upload_id and temporary upload_url, then requires PUT of raw bytes before completing the upload.

Instructions

Step 1 of staging a local file for publishing. Returns upload_id and a short-lived upload_url; the caller must then PUT the raw file bytes to upload_url (same Content-Type and size as declared here) and call complete_media_upload. Only useful when this client can perform the HTTP PUT itself (for example a coding agent with a shell); the model cannot read chat attachments or /mnt/data paths, so for those ask the user for a public HTTPS URL or send them to https://app.upload-post.com. Staging media is deleted after 24 hours; scheduled posts are safe because upload_video copies the media into durable scheduler storage.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`source`	No	Optional source label identifying the calling client, e.g. mcp_studio.
`filename`	Yes	Original filename, e.g. clip.mp4.
`mediaType`	No	Kind of media being uploaded.	video
`contentType`	Yes	MIME type, e.g. video/mp4.
`contentLength`	Yes	File size in bytes.

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv0.11.1Sep 9, 2026

removedInput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

changedInput schema / properties / source / description

Previous value: -"Optional source label, e.g. mcp_chatgpt or mcp_claude."New value: +"Optional source label identifying the calling client, e.g. mcp_studio."

removedOutput schema / $schema

Removed value: -"http://json-schema.org/draft-07/schema#"

First observedv0.4.0Jul 16, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations are minimal, so the description carries the burden. It discloses the short-lived upload_url, the requirement to PUT raw bytes with matching Content-Type and size, the 24-hour staging deletion, and the safety of scheduled posts via upload_video copying to durable storage. No contradiction with readOnly/destructive hints.

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 dense sentences with no filler: purpose first, then return value and required workflow, then when not to use, then lifecycle/durability. Every sentence earns its place.

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?

Covers return values, next steps, constraints, TTL, and exception path. Given the output schema fills in exact response shape, nothing critical is missing for an agent deciding to call this tool.

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 already documents filename, contentType, and contentLength well, so the baseline is 3. The description adds meaningful behavioral context by requiring that the subsequent PUT uses the same Content-Type and size declared in these parameters, which is valuable beyond the schema.

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?

Clearly identifies itself as 'Step 1 of staging a local file for publishing', states what it returns (upload_id, short-lived upload_url), and distinguishes itself from complete_media_upload and upload_video. An agent can immediately understand its role in the workflow.

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 states when it is useful (client can perform HTTP PUT), when it is not (model cannot read chat attachments or /mnt/data paths), and gives concrete alternatives (ask for a public HTTPS URL or send to app.upload-post.com). Also names the required follow-up call.

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

Deploy Server