Skip to main content
Glama

Download Beeper attachments

download_attachment
Destructive

Saves message attachments such as images, videos, audio, and documents to local files and returns their paths. Also batch-saves chat media by time range, skipping files already saved.

Instructions

Save a message attachment (video, image, audio, document) to a local file and return its path. By default it goes to a new file in the addon's download folder; writing elsewhere (outputPath) needs the user's confirmation. Identify it with url (an mxc:// or localmxc:// URL, or a beeper-mcp://attachments/... URI as returned by the official Beeper MCP), or with chatID + messageID (+ index when a message has several attachments). Batch: with chatID + since (+ until) instead of a message, it saves every photo and video (or mediaTypes) of that chat in that period into one folder, oldest first, named by date and message ID, and returns one short line per file (time, sender, message ID → file name). At most maxFiles per call (default 30): nextSince gives where to continue. Files already in the folder are skipped, so a repeated call only fetches what is missing.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "download_attachment"
  }
}

Input Schema

NameRequiredDescriptionDefault
urlNomxc://, localmxc:// or beeper-mcp://attachments/{chatID}/{messageID}/{index}
indexNoAttachment index in the message (default 0)
sinceNoBatch: ISO time; download the chat's media sent from then on (inclusive)
untilNoBatch: ISO time; only media sent before it. Default: now
chatIDNoChat ID (or local chat ID) of the message, or of the chat to download from (batch)
maxFilesNoBatch: at most this many files per call (default 30)
messageIDNoID of the message holding the attachment
outputDirNoBatch: folder to save into (confirm with the user first). Default: one folder per chat in /root/.cache/beeper-mcp-addon/downloads
overwriteNoReplace outputPath if it already exists (default false). Replaces the user's file: confirm first
mediaTypesNoBatch: which kinds (default ["image", "video"]; "file" = documents, audio…). Stickers are skipped
outputPathNoWhere to save the file (confirm with the user first). Defaults to a new file in /root/.cache/beeper-mcp-addon/downloads

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.5.1

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already flag destructiveHint=true and readOnlyHint=false; the description goes further by naming exactly what can be destroyed ('Replaces the user's file: confirm first') and where writes land by default ('/root/.cache/beeper-mcp-addon/downloads'). It also discloses resumability behavior the annotations cannot express ('Files already in the folder are skipped, so a repeated call only fetches what is missing') and the maxFiles/nextSince cap.

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?

Content is front-loaded with the core action, then a clearly labeled 'Batch:' block for the alternate mode. Dense but nearly every clause carries operational information (defaults, confirmation gates, continuation). It runs long relative to a single-purpose tool, though there is little genuinely wasted text.

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?

With 11 optional parameters, no output schema, and a destructive write, this is a complex tool, and the description covers mode selection, default locations, confirmation gates, batching limits, continuation, and even a sketch of the batch return format. An agent has enough to invoke it correctly without opening the schema, with only error/permission behavior left unstated.

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 description coverage is 100%, so the baseline is 3, but the description adds real meaning the schema does not: it explains how `chatID`+`messageID`+`index` combine, that `since`/`until` switch the tool into batch folder mode, and what the outputs of that mode are ('one short line per file', `nextSince`). It does not spell out accepted `url` scheme variations beyond the schema's enum-free string, but the added orchestration semantics are substantial.

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 gives a specific verb and resource ('Save a message attachment ... to a local file and return its path') plus the accepted media kinds. It then delineates two distinct operating modes (single attachment vs. batch) without ambiguity, so an agent knows exactly what the tool does and can distinguish it from siblings like send_file.

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?

The description clearly states which parameter combinations trigger which mode ('Identify it with `url` ... or with `chatID` + `messageID` (+ `index`)' and 'Batch: with `chatID` + `since` ... instead of a message') and calls out the confirmation requirement before writing outside the default folder or overwriting. It does not name any sibling alternative or state when not to use this tool, which keeps it below a 5.

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