mcp-server-mattermost

download_file

Download a Mattermost file attachment by its ID and save it to a local directory, returning the saved path for further processing. Supports rename/overwrite conflict policies.

Instructions

Download a file attachment and save it to a local directory.

Counterpart of upload_file: fetches the content of a file by its ID (from a post's file_ids or get_file_info) and writes it to disk. Returns the local path so the file can be read or processed further. Use on_conflict="rename" to save all same-named attachments without replacing any. Always use the returned path; parallel calls may assign numbers in any order. Each repeated call in rename mode saves another copy. overwrite=True cannot be combined with on_conflict="error" or "rename". Files larger than 100 MB are refused.

Input Schema

TableJSON Schema

Name	Required	Description
`file_id`	Yes	26-character file identifier (e.g., 'o5w8h47pdfbzjc4d8w7dhnhren')
`filename`	No	Override the saved file name
`overwrite`	No	Replace an existing file with the same name
`on_conflict`	No	Name conflict policy; null uses overwrite. rename keeps all files with numbered names
`destination_dir`	Yes	Local directory to save the file into (created if missing); a leading '~' is expanded

Output Schema

TableJSON Schema

Name	Required	Description
`name`	Yes	Saved file name
`path`	Yes	Absolute local path the file was saved to
`size`	Yes	Saved size in bytes
`file_id`	Yes	Downloaded file identifier
`mime_type`	No	MIME type reported by Mattermost

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.6.1Sep 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

With no annotations provided, the description carries the full burden and does so well: it discloses filesystem writes, returns the local path, warns that parallel calls may assign numbers in any order, explains repeated rename-mode copies, states the overwrite/on_conflict incompatibility, and notes the 100 MB size cap.

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?

The purpose is front-loaded, and every subsequent sentence adds operational detail—file source, return value, conflict behavior, concurrency caveat, and size limit. There is no filler or repetition that wastes an agent's attention.

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?

The description covers how to obtain the file ID, where to save, conflict resolution, parallel-call behavior, and the size restriction. Since an output schema exists, return-value details are already covered structurally, so nothing critical is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, and the description adds valuable interaction semantics beyond the schema: on_conflict='rename' preserves all same-named attachments, repeated calls in rename mode save another copy, and overwrite=True cannot be combined with on_conflict='error' or 'rename'. This materially helps an agent choose correct parameter values.

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 and resource: 'Download a file attachment and save it to a local directory.' It also distinguishes itself from upload_file by explicitly calling itself the counterpart and explaining that it fetches content by file ID from a post's file_ids or get_file_info.

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 makes the usage context clear: use this tool to fetch file content by ID and write it to disk, and it positions itself as the counterpart of upload_file. It does not explicitly name alternatives like get_file_link or state when not to use this tool, so it stops short of a 5.

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