Other Tools / API Reference
media_upload_start
Show the user a drop zone to hand over pictures or videos. CALL THIS WITHOUT BEING ASKED whenever media enters the conversation: * the user attaches or pastes a picture or video * they say they want to upload, send or add one * they ask for anything that needs a creative -- a new image ad, changing an ad's picture, refreshing a tired creative, a carousel, a Page or Instagram post Say what it is for in the same turn, e.g. "drop your images or videos in the box above and I will publish them to your ad", so the box does not appear unexplained. Do not ask them to find a public URL first, and do not wait for a second request. You cannot read an attachment -- you are shown the picture, never handed the bytes -- so this is the only way media reaches an ad. Never base64 a file into a tool parameter: large parameters are truncated in transit and the file arrives corrupt (loudly for PNG, silently for JPEG -- Meta returns a valid-looking image_hash for a damaged creative). In a host that renders inline UI this puts a drop zone in the conversation. DO NOT ASSERT THAT IT APPEARED. Nothing in a tool result tells you whether the iframe rendered, threw, or was never mounted, and a host that shows "Error loading app" gives you no signal at all -- so saying "the uploader is open above" is a guess that has already been wrong in front of users. `say_to_user` ends with the upload link for exactly this reason: say it verbatim, link included, and the user is covered either way. (ChatGPT is NOT a host without a box -- it implements MCP Apps, the same `ui/notifications/tool-result` protocol as Claude. This text used to name it as the no-widget example, which is wrong and would have an assistant skip a drop zone that was sitting right there.) Through a plain dispatcher or API client there is genuinely no iframe, and the same link is in `say_to_user_no_widget`. Hand it over rather than telling the user you cannot accept files; asking them for a public URL instead is a dead end, because this tool is what produces one. SEVERAL FILES AT ONCE ARE FINE, and so is video (MP4/MOV alongside JPG/PNG/GIF/WebP). One drop zone takes a whole carousel, a set of variants to choose between, or an image and a video of the same creative. media_upload_result then returns `files`, `image_urls` and `video_urls` rather than a single url -- do not assume the first one is the one they meant; ask if it is ambiguous. PASS `ad` WHENEVER THE USER MEANS A PARTICULAR AD, e.g. "put this picture on the retargeting ad". The image then goes straight onto that ad the moment they drop it, keeping its existing copy, link, page and CTA, and you need no follow-up call at all. Use whatever the conversation has been calling the ad -- its name, part of its name, or its ID. If several ads match, this returns them so you can ask which one; do not guess, since the wrong choice edits the wrong live ad. Without `ad`, the file is just stored: call media_upload_result with the returned upload_id to get its public URL. Args: purpose: Optional note shown to the user, e.g. "creative for the retargeting ad". Helps them pick the right file. ad: Optional. The ad this picture should land on -- name, partial name, or ID.
This is a read-only tool: it returns media upload start for your connected accounts. It changes nothing.
Ask Claude
You do not call this tool yourself. Ask for the outcome and the client picks the tool:
Media upload start across my connected accounts.
It takes 0 required and 2 optional parameters.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
purpose | string | No | Purpose |
ad | string | No | Ad |
Related Other Tools tools
Start free — 30 tool calls a month
No card required. Connect Google Ads, Meta Ads, GA4 or Search Console and ask Claude for the outcome — it picks the tool.