Fast indexed search for files and documents on disk using macOS Spotlight (mdfind).
spotlight_search uses macOS Spotlight (mdfind) to search the system's pre-built file index. Searches are extremely fast (milliseconds) because they query an existing index rather than scanning files.
Use recently_used=True to find files the user actually opened/worked on. This uses macOS's kMDItemLastUsedDate tracking, which records when files were opened by any application.
spotlight_search(recently_used=True, exclude_apps=True, days=1)spotlight_search(recently_used=True, exclude_apps=True, days=7)spotlight_search(recently_used=True, content_type="pdf", days=7)Always use exclude_apps=True with recently_used unless the user specifically asks about applications. Without it, results are cluttered with system apps.
Mail.app uses Core Spotlight, a separate private index that is NOT accessible via mdfind. To search emails in Mail.app, always use search_emails (AppleScript-based). This tool can find .eml files stored on disk (e.g., in OneDrive, Downloads), but not messages in Mail.app mailboxes.
Search by:
file_name — file name pattern (partial match, case-insensitive)query — full-text content search across file contentsbody — alias for content text searchcontent_type — filter by file typedays — limit to recently modified files (or recently opened when recently_used=True)directory — restrict search to a specific directory| Type | What it matches |
|---|---|
pdf | PDF documents |
image | All image formats (PNG, JPG, HEIC, etc.) |
document | Text documents, Word, Pages, etc. |
presentation | Keynote, PowerPoint |
spreadsheet | Numbers, Excel |
email | .eml files on disk (NOT Mail.app inbox) |
spotlight_search(recently_used=True, exclude_apps=True, days=1)spotlight_search(recently_used=True, exclude_apps=True, days=7)spotlight_search(file_name="X", content_type="pdf")spotlight_search(content_type="document", days=1)spotlight_search(query="X", directory="~/Downloads")spotlight_search(query="budget", content_type="spreadsheet")spotlight_search(recently_used=True, content_type="presentation", days=14)For files: Shows Name, Path, Type, Size, Modified date, and Last opened date (when available).