Skip to content

Media through an agent

Uploading through `upload_media` means base64-encoding a whole file into one tool call — the server’s filename and allowlist checks fire after that.

There's no multipart form on this side of the tool boundary. upload_media takes the whole file as a base64 string. The tool decodes it before it ever reaches the site, then hands the raw bytes to the SDK from there — the file travels through the tool call as text, roughly a third larger than the source.

upload_media calljson
{
  "name": "upload_media",
  "arguments": {
    "data": "iVBORw0KGgoAAAANSUhEUgAA…",
    "mimeType": "image/png",
    "filename": "hero-northwind.png"
  }
}

The risk isn’t a missing mimeType — it’s a wrong one

Neither value is optional to begin with: filename and mimeType are both required strings on the tool, so an agent cannot leave either out. They are what the server reads to decide the file's type and name — the bytes arrive raw, with those two values carried as headers, not as a form field the server can inspect for itself.

Which means the server has no way to tell that a declared type is wrong. It checks the filename's extension against one allowlist and the declared MIME type against another, separately, and never compares the two to each other; a generic application/octet-stream defers to the extension entirely. So photo.jpg declared image/png is accepted by both gates and stored with the wrong type on its record, where every later consumer of that record believes it. Take the type from the file rather than from what the agent inferred from the surrounding conversation.

A rejected upload tells you why

An extension the server's allowlist doesn't recognize comes back as the server's own reason, not a raw exception — the tool catches the SDK's error and rewraps it, so the agent (and whoever is reading its output) sees the actual cause rather than a stack trace to interpret.

Listing media is uncapped, unlike listing content

Omit limit on list_media and the site's entire library comes back in one response — the opposite of list_content, which caps by default. On a library of any size that is a large answer arriving in an agent's context whether or not it needed all of it, so pass a limit when you know roughly what you are looking for. What the two tools do share is hasMore: once a limit is in play, a true hasMore means the answer is partial and the next page has to be asked for. page is only meaningful alongside a limit — sent on its own it is an error, not a silent page one.