Skip to main content
Glama

Start a Playground reference upload

playground_media_upload_begin

Create a short-lived signed URL for one image, video, or audio reference. Upload bytes to signedUrl with the declared Content-Type, then call playground_media_upload_complete. The URL is scoped to your user, project, and OAuth client. For a file attached in chat, prefer playground_asset_import with file. If your environment cannot reach signedUrl, stop and ask the user to choose Add image on the Berrys canvas (playground_canvas_open) instead of retrying. Returns an upload ID, signed upload URL, MIME type, byte limit and expiry.

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": {
      "projectId": "<projectId>",
      "filename": "<filename>",
      "mimeType": "<mimeType>"
    },
    "name": "playground_media_upload_begin"
  }
}

Input Schema

NameRequiredDescriptionDefault
filenameYesOriginal filename of the media being uploaded, including its extension.
mimeTypeYesMedia content type of the bytes to upload, such as image/png.
projectIdYesID of the Playground project chosen for this task; obtain it from project creation, an explicit project link or current context.

Output Schema

NameRequiredDescriptionDefault
maxBytesYes
mimeTypeYes
uploadIdYes
expiresAtYesSerialized ISO timestamp.
signedUrlYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A4.3/5.0
Behavior4/5

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

Annotations declare readOnlyHint=false, destructiveHint=false, and idempotentHint=false, so the agent already knows this is a non-destructive write. The description adds substantial context beyond that: the URL is short-lived, scoped to user/project/OAuth client, and there is explicit guidance not to retry on unreachable signedUrl. It falls short of a 5 only because it doesn't clarify whether repeated calls mint separate upload IDs or what happens to an abandoned upload ID.

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 purpose, then workflow, then alternative, then failure fallback — a logical order where nearly every sentence earns its place. The closing sentence enumerating return fields (upload ID, URL, MIME type, byte limit, expiry) is partially redundant since an output schema exists, which slightly dilutes an otherwise tight definition.

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?

For a multi-step upload flow, the description covers the here-to-there handoff, the scoping constraint, and the failure path an agent would otherwise stumble on. With an output schema present, return values need no explanation, so the remaining deletion of that sentence is minor and the definition is otherwise complete.

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%, with all three parameters documented including the MIME type enum and the UUID pattern for projectId, so the schema already carries the semantics. The description references 'the declared Content-Type' but adds no format or constraint detail beyond what the schema provides, which is the baseline case for a fully documented 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?

The first sentence names a specific verb and resource — 'Create a short-lived signed URL for one image, video, or audio reference' — which is unambiguous and clearly distinct from playground_media_upload_complete and playground_asset_import. An agent can identify the tool's role 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 Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description lays out both the required follow-up step ('Upload bytes to signedUrl with the declared Content-Type, then call playground_media_upload_complete') and an explicit alternative ('For a file attached in chat, prefer playground_asset_import with file'). It also gives a hard stop condition with a fallback path (playground_canvas_open) instead of retrying, which is exactly the kind of exclusions that prevent wrong tool selection.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.