Feedback from agent

[endolith]

Good question. Here's what I found working well and what could be improved:

What worked well

• search_in_message + center_at drill-down is clever and effective once you know to use it
• search_message_bodies with implicit AND is intuitive
• aggregate is useful for quick orientation

What tripped me up

1. search_messages defaults to newest-first with no sort option

This was the biggest problem. When searching [part number] — 121 results, newest-first — the first relevant email (May 13, 2025) was on page 3 (offset 50+). I never paginated far enough because I assumed the early results would be sufficient.

Fix: Add a sort parameter — e.g., sort=asc for oldest-first when doing historical research. Or at minimum document in the description that results are newest-first and encourage using before: / after: filters.

2. search_message_bodies returns total: -1

I have no idea if I'm looking at 5 results or 500, so I don't know whether to paginate or stop. The has_more flag helps but only after fetching.

Fix: If a real total isn't feasible, at least document total=-1 in the parameter description so I know not to rely on it.

3. FTS requires at least one free-text term

If I want to search message bodies for everything from a specific sender in a date range, I can't — the tool rejects from:xxx after:yyyy-mm-dd as a filter-only query. So I have to search metadata first (search_messages), then dig into individual bodies.

Fix: Allow filter-only queries, or add a note in the description that bodies require free-text terms and direct users to search_messages for metadata-only queries (you already do this, but it's buried).

4. Context snippets are useful but hit-or-match on long threads

The 300-byte window might land on a repeated quote rather than the actual new content. The search_in_message + center_at workaround is great but requires knowing the drill.

Fix: Might just be documentation — the workflow instructions I was given already describe this, I just didn't follow them consistently.

5. Missing: a "search by conversation/thread" body search

If I find one interesting message in a thread, there's no easy way to say "show me all messages in this conversation ordered by date." I can use list_messages(conversation_id=...) which shows dates/subjects but not bodies.

Fix: This might already be fine — list_messages gives the thread map, then I fetch individual messages. Just took me a while to learn that pattern.

---

TL;DR: The single biggest improvement would be a sort parameter on search_messages (oldest-first as an option). Everything else is manageable with better documentation of existing patterns.

[endolith]

3. FTS requires at least one free-text term

If I want to search message bodies for everything from a specific sender in a date range, I can't — the tool rejects from:xxx after:yyyy-mm-dd as a filter-only query. So I have to search metadata first (search_messages), then dig into individual bodies.

Fix: Allow filter-only queries, or add a note in the description that bodies require free-text terms and direct users to search_messages for metadata-only queries (you already do this, but it's buried).

search_metadata already does filter-only, paginated, with a real total (it supports from:/to:/subject:/label:/before:/after: etc.). A body tool with no free-text term can't return a snippet — there's nothing to anchor the excerpt on — and I explicitly don't want whole/multiple bodies. So there's no coherent "filter + bodies, no term" feature to build; the agent's real want (messages from a sender in a range) is exactly search_metadata → then get_message the interesting ones. Drop that idea. No new tool.

[endolith]

This was the biggest problem. When searching [part number] — 121 results, newest-first — the first relevant email (May 13, 2025) was on page 3 (offset 50+). I never paginated far enough because I assumed the early results would be sufficient.

Fix: Add a sort parameter — e.g., sort=asc for oldest-first when doing historical research. Or at minimum document in the description that results are newest-first and encourage using before: / after: filters.

Only the keyword search can be ordered by date. Vector/hybrid search is sorted by best match. Giving a total number of matches would just as easily allow the AI to get the last page of results for oldest results, and we should provide that anyway so it knows if it searched something overly broad, so I think this is not necessary.

I have no idea if I'm looking at 5 results or 500, so I don't know whether to paginate or stop. The has_more flag helps but only after fetching.

Keyword search should provide a total number of results. Vector/hybrid cannot, since the number is unbounded: every chunk in the database matches to some extent. Maybe the two should be split into separate functions...

[endolith]

The 300-byte window might land on a repeated quote rather than the actual new content.

Not sure what we could do about this. Documentation to encourage looking only at the latest mail in the conversation? Deduplicate exact snippet matches? (but those will be rare. Ones with "one two three four" != "one two > three four" are more common.)

[endolith]

If I find one interesting message in a thread, there's no easy way to say "show me all messages in this conversation ordered by date." I can use list_messages(conversation_id=...) which shows dates/subjects but not bodies.

I explicitly do not want to return complete bodies, ever, it will overwhelm the context window. Certainly don't want to return all the complete bodies of an entire conversation. Showing dates/subjects but not bodies is the correct way.