Agent wants to be able to search filenames

[endolith]

Here's the spec:

---

searchAttachments: Find files by attachment name

Why this tool?

Currently there's no way to discover what files exist in the archive. To find a file, I must:

1. Guess a keyword that appears in the email body text
2. Hope that the attachment filename was also typed in the body, or that the storage layer indexed it
3. If I find the right message, call getMessage to see the attachment list

This is unreliable. If someone emailed "Here's the latest schematic" with REV123_SCHEMATIC.pdf attached and didn't type the filename in the body, I'd never find it.

A filename search tool would let me answer questions like:

• "What revision schematics exist for this product?" → search "PRODUCT_REV*.pdf"
• "Did anyone ever send test data?" → search "*test*"
• "Find the budget spreadsheet from last quarter" → search "*budget*2024*"

Parameters

Parameter	Type	Required	Description
pattern	string	yes	Glob-style filename pattern. Supports * (any characters) and ? (single character). Examples: "RXD2*.pdf", "*noise test*", "*budget*.xls*", "REV_???.pdf"
after	string	no	Only messages on or after this date (YYYY-MM-DD)
before	string	no	Only messages on or before this date (YYYY-MM-DD)
limit	integer	no	Maximum results to return (default 50, max 100)
offset	integer	no	Pagination offset (default 0)

Returns

{
  "data": [
    {
      "message_id": 12345,
      "subject": "Re: Revised schematics",
      "from": "vendor@partner.com",
      "date": "2026-05-06T10:23:00Z",
      "attachment_id": 81234,
      "filename": "PRODUCT_REV_SCHEMATIC_260410.pdf",
      "size_bytes": 254000
    }
  ],
  "returned": 5,
  "has_more": false
}

Results are newest-first by message date. has_more indicates additional pages are available.

Design notes

• Glob not regex — glob patterns (RXD2*.pdf, *noise*, *budget*.xls*) cover the real use cases (prefix, suffix, substring matching) without regex complexity. A user who wants to find "all PDFs for product X" will type "ProductX*.pdf", not a regex.
• Case-insensitive matching — filenames like RXD2_SCH.PDF and rxd2_sch.pdf should both match "RXD2*.pdf".
• No content search — just filename metadata. Full-text inside PDFs/DOCXs is a separate (much harder) problem.
• Why message_id instead of conversation_id — a file attachment lives on one specific message. The user can navigate to the conversation from there.

What problem does it solve?

Current situation	With this tool
Guess body keywords to find files	Search filename directly
Miss files if filename wasn't typed in body	Find files regardless of body text
Fetch messages one-by-one to check attachments	See all matching files in one response
Can't discover what files exist at all	Browse by pattern