Skip to main content
Glama

Describe, move or delete a media file

manage_media_file
Destructive

[Admin] With action update (the default): change a file's name, alt text, focal point or poster, or move it to another folder ("" is the top). Fields left out keep their value. alt replaces the whole set of languages. A null focal_x, focal_y or poster_url clears it. A move gives the file a new url: live pages keep the old one and page drafts move at once (drafts_updated). With action delete and only media_id: delete the file for good; this cannot be undone. Refused while a page, brand, CSS file, style setting, company logo or branding, interview, position, blog post, avatar or coaching catalogue uses it: the error lists what does, and those uses are changed separately.

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": {
      "media_id": "<media_id>"
    },
    "name": "manage_media_file"
  }
}

Input Schema

NameRequiredDescriptionDefault
altNoAlt text per language code. Replaces the whole set, so send every language.
actionNo`update` (default) changes the fields you send. `delete` deletes the file: send only media_id. It is refused with 409 while a page, brand, CSS file, style setting, company logo or branding, interview, position, blog post, avatar or coaching catalogue uses it (the answer lists what does); it cannot be undone.
folderNoMove the file to this folder; "" is the top. The file gets a new address in that folder; the old address keeps working for published pages, and page drafts move to the new one.
focal_xNoHorizontal focal point, 0 (left) to 1 (right). Null clears it.
focal_yNoVertical focal point, 0 (top) to 1 (bottom). Null clears it.
media_idYesThe file to change.
file_nameNoDisplay name in the library.
llm_modelNoYour model id, e.g. "claude-opus-4-8"; "unknown" if unsure. For analytics.
poster_urlNoStill image shown before a video plays: the `url` of an image in this company's library. Null removes it.
conversation_idNoThe 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.

Output Schema

NameRequiredDescriptionDefault
idYes
altNo
urlNo
kindNo
pathNo
widthNo
folderNo
heightNo
statusYes
focal_xNo
focal_yNo
versionNo
warningsNo
file_nameNo
read_onlyNo
created_atNo
poster_urlNo
size_bytesNo
updated_atNo
merchant_idNo
content_typeNo
drafts_updatedNo
duration_secondsNo
_mcp_instructionsNoServer-issued metadata for this conversation.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • changedInput schema / properties / action / description
      Previous value: -"`update` (default) changes the fields you send. `delete` deletes the file exactly as media-delete does: send only media_id. It is refused with 409 while a page, brand, CSS file, style setting, company logo or branding, interview, position, blog post, avatar or coaching catalogue uses it (the answer lists what does); it cannot be undone."New value: +"`update` (default) changes the fields you send. `delete` deletes the file: send only media_id. It is refused with 409 while a page, brand, CSS file, style setting, company logo or branding, interview, position, blog post, avatar or coaching catalogue uses it (the answer lists what does); it cannot be undone."
  2. Changed32 schema fields changed
    • removedInput schema / properties / action / example
      Removed value: -"update"
    • removedInput schema / properties / alt / example
      Removed value: -{
      -  "en": "Our team on deck"
      -}
    • removedInput schema / properties / file_name / example
      Removed value: -"team-photo.jpg"
    • removedInput schema / properties / focal_x / example
      Removed value: -0.5
    • removedInput schema / properties / focal_y / example
      Removed value: -0.3
    • 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"
      +}
    • removedOutput schema / properties / alt / description
      Removed value: -"Alt text per language code, such as {\"en\": \"Our team\"}."
    • removedOutput schema / properties / content_type / description
      Removed value: -"Content type of the file."
    • removedOutput schema / properties / content_type / example
      Removed value: -"image/jpeg"
    • removedOutput schema / properties / drafts_updated / description
      Removed value: -"Page drafts moved to the new address when the file changed folder; 0 otherwise. Published pages keep the old address until they are published again."
    • removedOutput schema / properties / duration_seconds / description
      Removed value: -"Length of a video or audio file in seconds, as sent to media-upload-finish."
    • removedOutput schema / properties / file_name / description
      Removed value: -"Display name in the library."
    • removedOutput schema / properties / file_name / example
      Removed value: -"team-photo.jpg"
    • removedOutput schema / properties / focal_x / description
      Removed value: -"Horizontal focal point, 0 (left) to 1 (right)."
    • removedOutput schema / properties / focal_y / description
      Removed value: -"Vertical focal point, 0 (top) to 1 (bottom)."
    • removedOutput schema / properties / folder / description
      Removed value: -"Library folder; \"\" is the top. It is the directory of the file in storage."
    • removedOutput schema / properties / folder / example
      Removed value: -"team"
    • removedOutput schema / properties / height / description
      Removed value: -"Height in pixels, as sent to media-upload-finish."
    • removedOutput schema / properties / id / description
      Removed value: -"Id of the file (media_id)."
    • removedOutput schema / properties / id / example
      Removed value: -"c9d6f121-1230-48fd-b3a7-8b5a1e8db052"
    • removedOutput schema / properties / kind / description
      Removed value: -"image, video, audio or font."
    • removedOutput schema / properties / merchant_id / description
      Removed value: -"Company whose library holds the file."
    • removedOutput schema / properties / path / description
      Removed value: -"Object name in the public bucket: <merchant_id>/[<folder>/]<file>."
    • removedOutput schema / properties / poster_url / description
      Removed value: -"Still image shown before a video plays."
    • removedOutput schema / properties / read_only / description
      Removed value: -"True for a file of the parent company's library: it can be used on pages but not changed or deleted."
    • removedOutput schema / properties / size_bytes / description
      Removed value: -"Size of the file in bytes, measured after the upload."
    • removedOutput schema / properties / status / description
      Removed value: -"The file's status; `deleted` after action delete (the stored objects go shortly after, in the background)."
    • removedOutput schema / properties / url / description
      Removed value: -"Public address of the file, served by the CDN. It changes when the file is replaced."
    • removedOutput schema / properties / version / description
      Removed value: -"Goes up each time the file is replaced."
    • removedOutput schema / properties / warnings / description
      Removed value: -"Things worth telling the person. The change was made."
    • removedOutput schema / properties / width / description
      Removed value: -"Width in pixels, as sent to media-upload-finish."
  3. Added

TDQS

A4.3/5.0
Behavior4/5

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

The annotations already flag this as destructive, non-idempotent and open-world, and the description adds substantial detail beyond them: omitted fields keep their value, alt replaces the entire language set, nulls clear focal points and poster, a move changes the file's url while live pages keep the old one and drafts move immediately (drafts_updated), and deletion is irreversible. The missing piece is whether updates are reversible or need confirmation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

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

Two dense sentences lead with the update path, then the delete path, then a pointer to get_tool_reference for full detail. Every clause does work and the destructive case is not buried.

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?

An output schema exists, so return values need no explanation, and the description still calls out drafts_updated and the 409-style refusal listing dependent content. For a 10-parameter destructive admin tool, the description plus schema plus annotations cover the decision to call it and what happens when you do.

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 coverage is 100%, so all ten parameters, including the action enum and the null-clearing semantics for focal_x/focal_y/poster_url, are already documented in the schema. The description largely repeats that material; its only genuine additions are PATCH-style 'fields left out keep their value' and the drafts_updated consequence of a move, so it sits at the high end of the baseline rather than clearly above it.

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 description opens with a specific verb set and resource: 'With action update ... change a file's name, alt text, focal point or poster, or move it to another folder' and 'With action delete ... delete the file for good'. That, plus the title's 'Describe, move or delete a media file', clearly distinguishes it from close siblings such as list_media_files, upload_media_file, finish_media_upload and manage_media_folder.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

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

It splits the two modes cleanly: update for field edits and moves, delete only when you send media_id alone, and it states the exact conditions under which a delete is refused. It does not explicitly name alternatives (e.g. list_media_files to find a media_id, or manage_media_folder to change folders), so the agent must infer the surrounding workflow.

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.