Browse the user’s Macro workspace to see recent items they have access to. Returns Macro documents, AI conversations, projects, emails, chat channels, call records, and foreign entities. Use this to get an overview of what the user has been working on or to find items by type. Start here for activity-summary questions such as “what happened today”, “what’s going on”, “catch me up”, or “what happened in standup today”; apply precise time, type, channel, or mailbox filters when the user gives that scope. For Macro task requests such as “list my tasks”, “tasks assigned to me”, or “tasks I completed yesterday”, prefer this tool over external task trackers such as Linear unless the user explicitly asks for Linear. Macro tasks are document items with df subtype {“l”:{“dst”:“task”}} and includeTypes [“document”]. Filter task Status and Assignees through propf using entity_type TASK: Status property 00000001-0000-0000-0000-000000000002, Completed option 00000001-0000-0000-0002-000000000004, Assignees property 00000001-0000-0000-0000-000000000001. The current user’s assignee entity id is their Macro user id, usually macro|<their email address from context>. For “completed yesterday”, combine status Completed, assigned-to-me, and a df updatedAt yesterday window with ua gte/lt ISO timestamps. Returned documents, AI chats, projects, emails, and call records include the tags visible to the user as {label, scope} pairs. To filter by tag (e.g. “my items tagged bug-report”), pass the tag labels in the tags argument — ListTags shows which tags exist. For finding specific items by name or content, use the search tool instead.
Filter returned items to specific item types. If not provided, returns all types. Example: [“document”, “email”] returns only documents and emails. Macro tasks are returned as document items, so use includeTypes=[“document”] with df subtype task for task requests. This is folded into the AST and applied as part of cursor-level filtering.
favoritesOnly
boolean
No
Only return items the user has favorited (starred). Use for requests like “my favorites” or “what have I starred”. Combine with includeTypes and the other filters as usual. Favorite or unfavorite an item with SetFavorite.
Full soup AST document filter (df). Use the same shape as /items/soup/ast, e.g. {“l”:{“id”:”…”}}. For Macro tasks, use {“l”:{“dst”:“task”}}; for skills, {“l”:{“dst”:“skill”}}. For “completed yesterday”, AND the task subtype with updatedAt bounds, e.g. {”&”:[{“l”:{“dst”:“task”}},{”&”:[{“l”:{“ua”:{“gte”:“<start>”}}},{“l”:{“ua”:{“lt”:“<end>”}}}]}]} using ISO timestamps.
pf
any
No
Full soup AST project filter (pf).
cf
any
No
Full soup AST AI chat filter (cf).
emailPreset
"signal"
No
High-level email filter preset. Use “signal” for signal emails. Signal emails and important emails are synonymous: if the user asks for important emails, use emailPreset=“signal”. This expands to the email AST {”&”:[{“l”:{“Importance”:true}},{“l”:{“Shared”:“exclude”}}]} and defaults results to emails if includeTypes is omitted.
ef
any
No
Advanced full soup AST email filter (ef). Prefer emailPreset=“signal” for common requests. Signal emails and important emails are synonymous; they use {”&”:[{“l”:{“Importance”:true}},{“l”:{“Shared”:“exclude”}}]}. Supports filtering by thread timestamp: {“l”:{“ca”:{“gte”:“<start>”}}} matches created_at, {“l”:{“ua”:{“gte”:“<start>”,“lt”:“<end>”}}} matches updated_at, using ISO timestamps with gt/lt/gte/lte comparators. For “emails from the last 7 days”, AND a ua (or ca) gte bound set to 7 days before now, e.g. {“l”:{“ua”:{“gte”:“<7-days-ago-ISO>”}}}.
chanf
any
No
Full soup AST channel filter (chanf).
cthf
any
No
Full soup AST channel thread filter (cthf).
callf
any
No
Full soup AST call filter (callf).
fef
any
No
Full soup AST foreign entity filter (fef).
propf
any
No
Full soup AST property filter (propf). Use this for Macro task Status, Assignees, Priority, and other entity properties. For task Status Completed: {“l”:{“pd”:“00000001-0000-0000-0000-000000000002”,“et”:“TASK”,“v”:{“so”:“00000001-0000-0000-0002-000000000004”}}}. For tasks assigned to the current user: {“l”:{“pd”:“00000001-0000-0000-0000-000000000001”,“et”:“TASK”,“v”:{“er”:“macro|user@example.com”}}}. Combine both with &: {”&”:[statusCompleted, assignedToMe]}. Prefer this over Linear tools for unqualified task requests.
emailView
string
No
Which mailbox view to hydrate previews from for email results. Valid values: inbox (default), sent, drafts, starred, all, important, other, or user:<label>. When the user asks about signal or important emails, use emailView=“inbox” together with emailPreset=“signal” — do not set emailView=“important” in that case. Only override the default when the user explicitly asks for a specific mailbox or label view (e.g. “sent”, “drafts”, “my Foo label”).
inbox
string
No
Restrict email results to a single connected inbox, given as that inbox’s email address. Omit to span every inbox the user can access (their own plus any delegated to them). Only set this when the user scopes the request to a specific mailbox (e.g. “my work inbox”, “the shared inbox”); call ListInboxes first to get the exact address. Only affects email results.
tags
TagFilter[]
No
Filter results to items carrying the given tags — any of them by default, every one of them with tagsMatch=“all”. Each entry names a tag by its label, matched case-insensitively against the user’s own tags; only set scope (“personal” or “team”) when the user distinguishes between their personal and team tags. An unknown label fails with the list of available tags — call ListTags first when unsure what tags exist. Only taggable items (documents, tasks, projects, emails, AI chats, call records) can match a tag filter. Prefer this over hand-building a propf filter for tags.
tagsMatch
"any" | "all"
No
How multiple tag filters combine when filtering items.
limit
integer
No
Maximum number of items to return. Defaults to 50; max 500.
