Agent wants message search tools to list attachments

[endolith]

Feature: Attachment metadata in list/search results

Problem

When exploring a conversation or searching metadata, listMessages and searchMetadata return message-level info (subject, from, date, snippet) but no attachment information. To find out whether a message has an attachment (and what it's named), I have to:

1. See a list of 20 messages
2. Pick one that looks promising
3. Call getMessage(id) just to check the attachments array
4. If it's the wrong one, repeat

This is tedious when exploring a long thread.

Proposed change

Add one or more attachment-related fields to the message objects returned by listMessages and searchMetadata:

Option A — Attachment count

{
  "id": 55400,
  "subject": "Re: Revised schematics",
  "from": "vendor@partner.com",
  "date": "2026-05-13T09:15:00Z",
  "attachment_count": 2,
  "snippet": "..."
}

This alone would let me quickly scan a list and see which messages have files attached. If attachment_count is 0, I skip it. If it's 3, I investigate further.

Option B — Filename list (preview)

{
  "id": 55400,
  "subject": "Re: Revised schematics",
  "from": "vendor@partner.com",
  "date": "2026-05-13T09:15:00Z",
  "attachment_count": 2,
  "attachments": [
    "REV260512_schematic.pdf",
    "whine_noise_test_results.xlsx"
  ],
  "snippet": "..."
}

This is richer — I can see what files are attached without any extra round trips. But it adds more data to every list result, so there may be a performance cost on large queries.

Option C — Optional include_attachments parameter

Add a boolean parameter include_attachments (default false) to listMessages and searchMetadata. When true, each result includes an attachments array with [{ID, Filename, SizeBytes}]. When false (default), behavior is unchanged.

This avoids any performance cost for queries where attachment info isn't needed.

Recommendation

If there's no significant performance concern, I'd prefer Option B — always include attachment_count and a list of filenames. It's a small payload addition that saves many getMessage calls.

If there is a performance concern, Option C (optional flag) is the pragmatic compromise.