Skip to main content
Glama

pinbridge

by io.pinbridge
OverviewDiscussionsAdmin

Upload image or video

upload_asset

Upload an image or video to PinBridge and get an asset_id for create_pin.

    Use when the media was generated in this session or Pinterest cannot
    fetch it from a public URL; otherwise pass image_url to create_pin
    directly. Provide exactly one of file, content_base64 or source_url.
    For a file attached to or generated in the conversation use file, never
    a file path in content_base64. Videos must be uploaded assets.

    Returns id (use as asset_id), public_url, asset_type, content_type,
    size_bytes, created_at. Files are capped at 200 MB (plans cap lower).
    Fails with payment_required on plans without uploaded_media_assets
    (see get_billing_status), validation_error for unsupported media, and
    invalid_image when the file is truncated or corrupted (re-encode the
    exact original bytes; never retype base64 by hand).

Input Schema

NameRequiredDescriptionDefault
fileNoAn image or video attached to or generated in the conversation, handed over by the client as a download link.
filenameYesFile name with extension, e.g. "hero.png".
asset_typeNoKind of media being uploaded.image
source_urlNoPublic http(s) URL the server downloads instead of content_base64; no redirects, private hosts are refused.
content_typeNoMIME type, e.g. "image/png"; inferred when omitted.
content_base64NoBase64-encoded file bytes (data: prefix allowed).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • addedInput schema / $defs
      Added value: +{
+  "ChatFile": {
+    "description": "A file handed over by the client as a download link.",
+    "properties": {
+      "download_url": {
+        "description": "Temporary URL the server downloads the file from.",
+        "title": "Download Url",
+        "type": "string"
+      },
+      "file_id": {
+        "description": "The client's id for the file.",
+        "title": "File Id",
+        "type": "string"
+      },
+      "file_name": {
+        "description": "Original file name.",
+        "title": "File Name",
+        "type": "string"
+      },
+      "mime_type": {
+        "description": "MIME type, e.g. \"image/png\".",
+        "title": "Mime Type",
+        "type": "string"
+      }
+    },
+    "required": [
+      "download_url",
+      "file_id"
+    ],
+    "title": "ChatFile",
+    "type": "object"
+  }
+}
    • addedInput schema / properties / file
      Added value: +{
+  "$ref": "#/$defs/ChatFile",
+  "description": "An image or video attached to or generated in the conversation, handed over by the client as a download link.",
+  "title": "File"
+}
  2. Changed5 schema fields changed
    • addedInput schema / properties / asset_type / description
      Added value: +"Kind of media being uploaded."
    • addedInput schema / properties / content_base64 / description
      Added value: +"Base64-encoded file bytes (data: prefix allowed)."
    • addedInput schema / properties / content_type / description
      Added value: +"MIME type, e.g. \"image/png\"; inferred when omitted."
    • addedInput schema / properties / filename / description
      Added value: +"File name with extension, e.g. \"hero.png\"."
    • addedInput schema / properties / source_url / description
      Added value: +"Public http(s) URL the server downloads instead of content_base64; no redirects, private hosts are refused."
  3. Added

TDQS

A4.8/5.0
Behavior5/5

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

Annotations only cover the generic safety profile (readOnly=false, non-idempotent, non-destructive, open-world). The description adds specific operational context: a 200 MB cap with plan-level variance, the payment_required failure gated on the uploaded_media_assets feature via get_billing_status, validation_error for unsupported media, and invalid_image for truncated bytes with re-encoding guidance.

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 selection guidance, then return/error behavior — a sensible order. Four short paragraphs each carry distinct information, though the error-code enumeration is dense and could be trimmed slightly without losing agent-critical detail.

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?

Despite no output schema, the description enumerates the returned fields (id, public_url, asset_type, content_type, size_bytes, created_at) and states how to use the result (id as asset_id). Size limits, error modes, and billing gates are all covered, leaving nothing an agent needs missing for a 6-parameter upload 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 coverage is 100%, so the baseline would be 3, but the description adds genuine semantic constraints the schema does not encode: mutual exclusivity of file/content_base64/source_url and a rule for which representation to prefer for conversational attachments. The 'never retype base64 by hand' note further clarifies content_base64 usage. The filename parameter is left to the schema, keeping it just short of a 5.

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 specific verb and resource ('Upload an image or video to PinBridge') plus the concrete outcome ('get an asset_id for create_pin'), immediately tying it to the sibling that consumes the result. An agent can distinguish it from create_pin's direct image_url path without opening either 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?

Gives explicit when-to-use criteria ('media generated in this session or Pinterest cannot fetch it from a public URL') and names the alternative explicitly ('otherwise pass image_url to create_pin directly'). It also resolves the internal choice among parameters: exactly one of file, content_base64 or source_url, and 'use file, never a file path in content_base64' for conversational attachments.

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

All pinbridge toolsInspect
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