JobMojito

Start a media upload

start_media_upload

Destructive

[Admin] First step of an upload for a client that can send a file itself: returns a signed upload_url. The file is PUT there with the declared Content-Type, and finish_media_upload completes it. A client that cannot send a file to an address uses upload_media_file.

Every argument in full, with examples: get_tool_reference.

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": {
      "file_name": "<file_name>",
      "content_type": "<content_type>",
      "size_bytes": "<size_bytes>"
    },
    "name": "start_media_upload"
  }
}

Input Schema

Name	Required	Description
`folder`	No	Library folder to upload into; default the top ("").
`file_name`	Yes	Display name in the library. It is never part of the address.
`llm_model`	No	Your model id, e.g. "claude-opus-4-8"; "unknown" if unsure. For analytics.
`size_bytes`	Yes	Size of the file in bytes, at most 52428800 (50 MB). A larger file answers 413.
`merchant_id`	No	Optional company to upload for. Admins and sub-merchant operators only; other callers always use their token's company.
`content_type`	Yes	Type of the file: image/jpeg, image/png, image/webp, image/gif, image/avif, image/svg+xml, video/mp4, audio/mpeg, audio/mp4, audio/x-m4a, font/woff2. Video must be H.264 MP4.
`conversation_id`	No	The conversation_id this server returned earlier in this conversation, unchanged, including after later user messages. Omit it if you have none. Recorded for the server developer's analytics.
`replace_media_id`	No	Replace this file instead of adding one. Must be the same kind. The file keeps its id, name and alt text and gets a new address when finish_media_upload accepts it.

Output Schema

Name	Required	Description
`path`	Yes
`token`	Yes
`media_id`	Yes
`upload_url`	Yes
`cache_control`	Yes
`_mcp_instructions`	No	Server-issued metadata for this conversation.

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedNov 9, 2026

changedInput schema / properties / replace_media_id / description

Previous value: -"Replace this file instead of adding one. Must be the same kind. The file keeps its id, name and alt text and gets a new address when media-upload-finish accepts it."New value: +"Replace this file instead of adding one. Must be the same kind. The file keeps its id, name and alt text and gets a new address when finish_media_upload accepts it."

changedInput schema / properties / size_bytes / exclusiveMinimum
```
Previous value: -1New value: +0
```
removedInput schema / properties / size_bytes / minimum
```
Removed value: -0
```

Changed14 schema fields changedNov 9, 2026

changedInput schema / properties / content_type / description

Previous value: -"Type of the file: image/jpeg, image/png, image/webp, image/gif, image/avif, image/svg+xml, video/mp4, audio/mpeg, audio/mp4, audio/x-m4a, font/woff2. Video must be H.264 MP4. Upload the file with this same content type."New value: +"Type of the file: image/jpeg, image/png, image/webp, image/gif, image/avif, image/svg+xml, video/mp4, audio/mpeg, audio/mp4, audio/x-m4a, font/woff2. Video must be H.264 MP4."

removedInput schema / properties / content_type / example
```
Removed value: -"image/jpeg"
```
removedInput schema / properties / file_name / example
```
Removed value: -"team-photo.jpg"
```

changedInput schema / properties / folder / description

Previous value: -"Library folder to upload into; default the top (\"\"). The folder need not exist yet. Ignored when replacing: a new version stays in the folder of the file."New value: +"Library folder to upload into; default the top (\"\")."

removedInput schema / properties / folder / example
```
Removed value: -"team"
```

addedInput schema / properties / llm_model

Added value: +{
+  "description": "Your model id, e.g. \"claude-opus-4-8\"; \"unknown\" if unsure. For analytics.",
+  "type": "string"
+}

removedInput schema / properties / merchant_id / example

Removed value: -"28106cba-1c27-4e53-b149-32113e5e8e31"

removedInput schema / properties / size_bytes / example
```
Removed value: -120000
```

removedOutput schema / properties / cache_control / description

Removed value: -"Seconds to send as the cache lifetime: a file name is never reused, so a year is safe."

removedOutput schema / properties / cache_control / example
```
Removed value: -31536000
```

removedOutput schema / properties / media_id / description

Removed value: -"Send this to media-upload-finish after the upload."

removedOutput schema / properties / path / description

Removed value: -"Object name in the public bucket: <merchant_id>/[<folder>/]<media_id>-v<version>.<ext>."

removedOutput schema / properties / token / description

Removed value: -"The token inside upload_url, for clients that upload with the Supabase library (`uploadToSignedUrl`)."

removedOutput schema / properties / upload_url / description

Removed value: -"Signed address, valid for two hours. PUT the file here with the Content-Type you declared and `Cache-Control: max-age=<cache_control>`."

AddedNov 8, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true, non-idempotent, openWorld, so the bar is lower; the description still adds the key mechanics (a signed upload_url is returned, the file is PUT with the declared Content-Type, completion is a separate call). It does not say what happens if the upload is never finished or whether upload_url expires, nor does it flag that replace_media_id overwrites an existing file—the latter is only in 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.

Conciseness4/5

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

Two tight sentences that front-load the purpose and the workflow, with the alternative named second. The closing pointer to get_tool_reference is useful but slightly marketing-flavoured; otherwise no waste.

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 8 parameters, an output schema, and rich annotations, the agent has most of what it needs; the description correctly frames this as a multi-step flow. The remaining gaps—upload_url lifetime, cleanup of abandoned uploads, and the destructive replace behaviour—are minor but real for a two-call workflow.

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 the schema already explains every parameter, including the 50 MB cap, the Content-Type enum, and replace_media_id semantics. The description adds only the linkage that the declared Content-Type is what must be sent to the upload_url, which is a marginal gain over 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?

States a concrete verb+resource ("First step of an upload ... returns a signed upload_url") and immediately distinguishes itself from the sibling upload_media_file and from finish_media_upload. An agent can tell which tool starts the flow versus which one completes it without reading any schema.

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?

Explicit routing rule: use this when the client can PUT a file to an address; use upload_media_file when the client cannot send a file to an address. It also names the completing step (finish_media_upload), and the [Admin] prefix signals the required privilege level.

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

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