Keeping an agent inbox usable after ten thousand messages

An agent inbox in week one is twelve messages and everything is obvious. In month six it is ten thousand, and the difference between an agent that still works and one that has quietly degraded is whether anyone taught it to prune and to search rather than to list.

31 July 2026 · 4 min read

List is a queue, not a history#

list_messages answers "what needs attention", and it only keeps answering that if things leave it. An agent that never archives is asking for the first page of a growing pile, which means it re-reads what it already handled and eventually stops seeing what is new.

So archiving is not tidiness, it is what keeps the primary tool truthful. Archive when the exchange is done, and treat it as the last step of handling a message rather than a maintenance task somebody does later. It belongs in the finishing section of your system prompt alongside replying and recording a fact.

Nothing is lost. Archived mail is still searchable and still in the thread; it is out of the queue, not out of the mailbox.

Unread is a signal, so use it deliberately#

mark_unread puts something back in the pile. That sounds trivial and is the cleanest handover primitive in the toolset: an agent that cannot answer something marks it unread and leaves it, and the human working the inbox sees exactly what needs them.

Two rules keep it meaningful. The agent should never mark unread as a way of deferring a decision it could make, because a queue of maybes is worse than a queue of noes. And a human taking over a thread should not have the agent re-enter it afterwards, per the handover discipline in approval a human will still read.

Search instead of listing#

search_inbox is ranked full-text over subjects, senders, and bodies, and it returns highlighted excerpts rather than whole messages, which matters as much for tokens as for accuracy. The query syntax is the one people already know from web search: quoted phrases, OR, and - to exclude.

search_inbox { query: "\"invoice 2291\" OR \"PO 4471\" -newsletter", limit: 10 }

Three habits make it useful rather than decorative.

Search before you assume. Before answering "as discussed last month", find that conversation. Before starting an outreach thread, check whether a colleague or another agent is already in one with that domain, which is the embarrassment prevented in an AI agent for lead follow-up.

Search narrow, then read. An excerpt tells you which thread; get_thread tells you what was said. Reading five whole threads to find one fact is how an agent spends a fortune on context.

Exclude the noise. Notification floods and no-reply senders pollute results. Excluding them in the query is cheap, and excluding them at the door is cheaper, per deciding what reaches your agent.

What belongs in the mailbox and what does not#

The mailbox is a record of correspondence. It is not a database, a CRM, or a memory store, and treating it as one is the most common way agent inboxes become unusable.

Searching mail for something that belongs in a contact record works until it does not, and it degrades exactly as volume grows. The division and what to record where are in giving an email agent memory.

Storage is a real line#

Attachments dominate. Storage counts against your plan, retention on paid plans is unlimited by default, and unlimited by default is a decision you did not make. Archiving keeps the queue clean but does not delete anything, so a deliberate retention period per category is the other half of the job, and it is a data protection question as much as a cost one, per the compliance floor and what email actually costs.

A hygiene routine that survives contact with reality#

1. Archive as the last step of handling a message, always, in the prompt.
2. Mark unread only when a human is genuinely needed.
3. Search before starting a conversation with a domain you may already be in one with.
4. Read the thread, not five threads, once search has found it.
5. Keep person-facts on the contact, not in the mailbox.
6. Set a retention period per category, including attachments.
7. Watch the unread count as an alert rather than a decoration: a queue building up is the earliest sign the agent is failing silently, per what to monitor in production.

Point seven is the one that pays for the rest. A short queue is a working agent; a growing one is a broken webhook, an expired key, or an agent quietly escalating everything.

Questions#

Should an AI agent archive email?

Yes, as the last step of handling each message. list_messages is a queue rather than a history, and it only stays useful if handled mail leaves it.

Does archiving delete anything?

No. Archived mail stays searchable and stays in its thread; it leaves the working queue only.

How should an agent search its inbox?

search_inbox with websearch-style syntax: quoted phrases, OR, and - for exclusions. It returns ranked excerpts, so use it to find the thread and then read the thread.

What is `mark_unread` for?

Handing something back to a human. It is the cleanest handover primitive available, provided the agent does not use it to defer decisions it could make.

Should the mailbox be used as a memory store?

No. Threads record what was said, contacts record what is known about a person, notes record policy, and your own systems record state. Searching mail for facts degrades as volume grows.

What is the earliest sign an agent has stopped working?

A growing unread queue. Silence in an inbox looks identical to a quiet day until you watch the count.