mailwarden

download_attachment

Save a Gmail attachment to a local file path, restricted to MAILWARDEN_DOWNLOAD_DIR when set; existing files get a numeric suffix so nothing is overwritten.

Instructions

Download an attachment to a local file path. If MAILWARDEN_DOWNLOAD_DIR is set, destPath is resolved inside (and restricted to) that directory. USE WHEN: the user wants an attachment saved to disk (IDs come from get_thread's attachment metadata). SIDE EFFECTS: writes a local file; never overwrites — an existing file gets a numeric suffix (file-1.pdf). The response's 'saved' field is the path actually used. Mailbox unchanged.

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": {
      "messageId": "<messageId>",
      "attachmentId": "<attachmentId>",
      "destPath": "<destPath>"
    },
    "name": "download_attachment"
  }
}

Input Schema

Name	Required	Description	Default
`destPath`	Yes
`messageId`	Yes
`attachmentId`	Yes

Output Schema

Name	Required	Description	Default
`saved`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.25.0Oct 29, 2026
- removedInput schema / additionalProperties
```
Removed value: -false
```
First observedv0.1.8Jul 24, 2026

TDQS

A4.4/5.0

Behavior5/5

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

Annotations already flag readOnlyHint=false and destructiveHint=false, and the description goes well beyond them: it discloses the MAILWARDEN_DOWNLOAD_DIR path resolution and restriction, that existing files are never overwritten (numeric suffix), and that the mailbox is unchanged. That is exactly the mutation-context an agent needs before writing to disk.

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?

Four short sentences, each carrying distinct information: purpose first, then path-resolution constraint, then USE WHEN, then side effects. No filler and the most decision-relevant facts are front-loaded.

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?

For a 3-required-param file-writing tool, the description covers purpose, targeting, path constraint, overwrite behavior, and mailbox safety. An output schema exists and the description still points at the 'saved' field, so return-value behavior is covered without redundancy.

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 0%, so the description must compensate, and it does: destPath semantics are explained via MAILWARDEN_DOWNLOAD_DIR resolution and restriction, and the source of messageId/attachmentId is stated (get_thread attachment metadata). It stops short of clarifying the messageId vs attachmentId distinction explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Download an attachment to a local file path'), making the write-to-disk outcome unambiguous. It doesn't explicitly contrast with the sibling read_attachment, which is the closest alternative, so it falls short of a 5.

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?

An explicit 'USE WHEN: the user wants an attachment saved to disk' clause plus provenance of the IDs ('IDs come from get_thread's attachment metadata') tells the agent when this is the right call. It never names read_attachment as the non-saving alternative, so selection between the two still requires inference.

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