Skip to main content
Glama
owlpost

owlpost

save_attachment

Idempotent

Download a specific email attachment from a message and save it to a local file path, returning its written path, size, MIME type, and original filename.

Instructions

Download one attachment from a message and write it to the local filesystem.

The mailbox is not modified. Returns the written path, size, MIME type and original filename. An existing file at the target path is overwritten.

Args: account: Account name from list_accounts. folder: Folder containing the message. uid: Message UID. part: 1-based part index from read_email's attachments list. save_to: Destination. A directory (trailing slash, existing directory, or a path without an extension) keeps the original filename; anything else is used as the full file path. ~ is expanded and missing directories are created.

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": {
      "account": "<account>",
      "folder": "<folder>",
      "uid": "<uid>",
      "part": "<part>",
      "save_to": "<save_to>"
    },
    "name": "save_attachment"
  }
}

Input Schema

NameRequiredDescriptionDefault
uidYes
partYes
folderYes
accountYes
save_toYes

Output Schema

NameRequiredDescriptionDefault
mimeYes
pathYes
sizeYes
filenameYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.3.0
    • changedOutput schema / (root)
      Previous value: -nullNew value: +{
      +  "properties": {
      +    "filename": {
      +      "anyOf": [
      +        {
      +          "type": "string"
      +        },
      +        {
      +          "type": "null"
      +        }
      +      ],
      +      "title": "Filename"
      +    },
      +    "mime": {
      +      "title": "Mime",
      +      "type": "string"
      +    },
      +    "path": {
      +      "title": "Path",
      +      "type": "string"
      +    },
      +    "size": {
      +      "title": "Size",
      +      "type": "integer"
      +    }
      +  },
      +  "required": [
      +    "path",
      +    "size",
      +    "mime",
      +    "filename"
      +  ],
      +  "title": "SavedAttachment",
      +  "type": "object"
      +}
  2. First observedv0.1.0

TDQS

A4.8/5.0
Behavior5/5

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

Beyond the annotations, it discloses that the mailbox is untouched, that an existing file at the target path is silently overwritten, that '~' is expanded, and that missing directories are created — all material side effects an agent could not infer from readOnlyHint/idempotentHint. The overwrite behavior is the one point of mild tension with destructiveHint=false, but because it is disclosed explicitly the agent can act on it rather than being misled.

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 definition is front-loaded with the core action and side effects, then moves into a scannable per-parameter block. Every sentence carries information — no restatement of the tool name and no filler.

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 five-required-parameter write tool, the definition covers side effects, path resolution rules, directory creation, and briefly notes the return payload (path, size, MIME type, filename) even though a full output schema exists. An agent has everything needed to call it correctly on the first attempt.

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 description coverage is 0%, yet the Args block fully documents all five parameters: 'part' is annotated as a 1-based index sourced from read_email's attachments list, and 'save_to' gets detailed disambiguation between directory mode (trailing slash, existing directory, or no extension preserves the original filename) and full-path mode. This adds meaning well beyond the bare typed properties and compensates entirely for the coverage gap.

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 names a specific verb and resource ('Download one attachment from a message and write it to the local filesystem') with scope limited to a single attachment. It is clearly distinguishable from siblings like read_email (which lists attachments) and from the mail-mutation tools such as move_email or delete_email.

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 establishes the calling context by tying each input to its source: 'account from list_accounts' and 'part from read_email's attachments list', which tells an agent the prerequisite read step. It also states 'The mailbox is not modified', implying this is not a substitute for move/delete operations. It stops short of explicit when-not-to-use or naming an alternative save mechanism, so it falls 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.