docs(mcp): clarify tool schemas for search, body search, and aggregate

Document supported search_messages query operators (subset of Gmail syntax),
metadata-only default search vs search_message_bodies for body FTS, body
query syntax (ANDed terms, quoted phrases, filter vs free-text), and
matches_truncated on capped excerpt lists.

Clarify aggregate group_by=time buckets by calendar year. Add schema
contract tests and toolPropertyDescription helper for mcp-go map schemas.
Update docs/usage/chat.md.

Co-authored-by: endolith <endolith@gmail.com>

Author: cursoragent

docs/usage/chat.md

@@ -47,15 +47,15 @@ The MCP server exposes the following tools to connected AI clients:
 
 | Tool | Description | Parameters |
 |---|---|---|
-| `search_messages` | Search with Gmail-like query syntax. When [vector search](/usage/vector-search/) is configured, supports semantic and hybrid modes. | `query` (string, required), `mode` (string: `fts`/`vector`/`hybrid`, default `fts`), `explain` (bool), `limit` (int), `offset` (int), `account` (string) |
+| `search_messages` | Search with a subset of Gmail query syntax (not full Gmail compatibility). When [vector search](/usage/vector-search/) is configured, supports semantic and hybrid modes. | `query` (string, required), `mode` (string: `fts`/`vector`/`hybrid`, default `fts`), `explain` (bool), `limit` (int), `offset` (int), `account` (string) |
 | `find_similar_messages` | Nearest-neighbor search from a seed message's embedding. Requires vector search to be configured and an active index generation. | `message_id` (int, required), `limit` (int), `account` (string), `after` (string), `before` (string), `has_attachment` (bool) |
 | `search_by_domains` | Find messages where any participant (`from`, `to`, or `cc`) belongs to one of several domains, regardless of direction. | `domains` (comma-separated string, required), `limit` (int), `offset` (int), `after` (string), `before` (string) |
 | `get_message` | Get full message details by ID | `id` (int) |
 | `list_messages` | List messages with filters | `from` (string), `to` (string), `label` (string), `after` (string), `before` (string), `has_attachment` (bool), `limit` (int), `offset` (int), `account` (string) |
 | `get_attachment` | Get attachment content by ID | `attachment_id` (int) |
 | `export_attachment` | Save attachment to filesystem | `attachment_id` (int), `destination` (string) |
 | `get_stats` | Archive overview statistics. Includes vector index state when configured. | — |
-| `aggregate` | Grouped statistics (top senders, domains, labels, time series) | `group_by` (string: sender/recipient/domain/label/time), `limit` (int), `after` (string), `before` (string), `account` (string) |
+| `aggregate` | Grouped statistics (top senders, domains, labels, or message volume by calendar year) | `group_by` (string: sender/recipient/domain/label/time), `limit` (int), `after` (string), `before` (string), `account` (string) |
 | `stage_deletion` | Stage messages for deletion (creates manifest only) | `query` (string) OR structured filters: `from` (string), `domain` (string), `label` (string), `after` (string), `before` (string), `has_attachment` (bool); optional: `account` (string) |
 
 `search_messages` and `list_messages` return paginated JSON:
@@ -76,6 +76,29 @@ backend cannot report a full result count, `total` is `-1`; use
 `has_more` as the pagination signal. `list_messages` uses this
 `total = -1` shape because it does not run a separate count query.
 
+### `search_messages` query syntax
+
+Supported operators: `from:`, `to:`, `cc:`, `bcc:`, `subject:`, `label:` (or `l:`), `has:attachment`, `before:`/`after:` (YYYY-MM-DD), `older_than:`/`newer_than:` (e.g. `7d`, `2w`, `1m`, `1y`), `larger:`/`smaller:` (e.g. `5M`). Bare domains on `from:`/`to:` match any address at that domain. Multiple terms are ANDed.
+
+Not supported: negation (`-has:attachment`), `OR`, or parentheses grouping.
+
+Free text matches subject, snippet, and sender fields first. If that returns no results, the server falls back to full-text search including message bodies (when the FTS index is available).
+
+### `aggregate` response
+
+`group_by=time` buckets messages by **calendar year** only. Each row's `Key` is a year string (e.g. `"2024"`). Month or day granularity is not available via MCP.
+
+All `group_by` values return a JSON array of objects with these fields:
+
+| Field | Description |
+|---|---|
+| `Key` | Grouping value (email, domain, label name, or year) |
+| `Count` | Number of messages in the group |
+| `TotalSize` | Sum of `size_estimate` in bytes |
+| `AttachmentSize` | Sum of attachment sizes in bytes |
+| `AttachmentCount` | Number of attachments |
+| `TotalUnique` | Total number of distinct groups (same on every row) |
+
 `find_similar_messages` is only registered when the server starts with vector search configured. `search_messages` is always available, but `mode=vector` and `mode=hybrid` return `vector_not_enabled` when the server is not configured for vector search. Vector and hybrid queries require at least one free-text term (operator-only queries return `missing_free_text`). They support `offset`/`limit` pagination inside the configured hybrid ranking window; when `[vector.search].max_page_size_hybrid` is positive, an `offset` at or beyond that cap returns `pagination_limit`. Use `mode=fts` for deeper pagination or adjust that config cap.
 
 In `mode=vector` and `mode=hybrid`, the paginated response also includes

internal/mcp/handlers.go

@@ -30,7 +30,8 @@ const (
 	maxSearchMessagesLimit = 50
 	defaultSearchLimit     = 20
 	maxContextSnippets     = 5
-	// searchContextChars is the max byte length of each context_snippets entry in search_message_bodies.
+	// searchContextChars is the max byte length of each matches[] snippet in
+	// search_message_bodies and search_in_message.
 	searchContextChars = 300
 	defaultBodyChars   = 2000
 	// maxBodyChars caps the body slice returned by get_message regardless of what
@@ -223,6 +224,8 @@ func (h *handlers) readAttachmentFile(contentHash string) ([]byte, error) {
 type searchMessageItem struct {
 	query.MessageSummary
 
+	// MatchesTruncated is true when more than maxContextSnippets (5) match
+	// excerpts were found; only the first 5 are returned.
 	Matches          []messageMatch `json:"matches,omitempty"`
 	MatchesTruncated bool           `json:"matches_truncated,omitempty"`
 }
@@ -281,7 +284,7 @@ func (h *handlers) searchMessages(ctx context.Context, req mcp.CallToolRequest)
 }
 
 // searchMessageBodies performs full-text search over message bodies and returns
-// context_snippets — short excerpts centered on each matched term. Requires at
+// matches — short excerpts centered on each matched term. Requires at
 // least one free-text term; use search_messages for filter-only queries.
 func (h *handlers) searchMessageBodies(ctx context.Context, req mcp.CallToolRequest) (*mcp.CallToolResult, error) {
 	args := req.GetArguments()
@@ -306,7 +309,11 @@ func (h *handlers) searchMessageBodies(ctx context.Context, req mcp.CallToolRequ
 	}
 
 	if len(q.TextTerms) == 0 {
-		return mcp.NewToolResultError("search_message_bodies requires at least one free-text term; use search_messages for filter-only queries"), nil
+		return mcp.NewToolResultError(
+			"search_message_bodies requires at least one free-text term (bare word or quoted phrase); " +
+				"Gmail operators such as from: or subject: are metadata filters and do not count — " +
+				"use search_messages for filter-only queries",
+		), nil
 	}
 
 	results, err := h.engine.Search(ctx, q, limit+1, offset)

internal/mcp/server.go

@@ -194,28 +194,43 @@ func ServeHTTPWithOptions(ctx context.Context, opts ServeOptions, addr string) e
 	}
 }
 
+// Shared search_messages schema text. The parser implements a subset of Gmail
+// syntax — not full Gmail compatibility. Keep this in sync with
+// internal/search/parser.go and the SearchFast → Search fallback in handlers.go.
+const (
+	searchMessagesOperatorDoc = "Supported operators: from:, to:, cc:, bcc:, subject:, label: (or l:), has:attachment, " +
+		"before:/after: (YYYY-MM-DD), older_than:/newer_than: (e.g. 7d, 2w, 1m, 1y), larger:/smaller: (e.g. 5M). " +
+		"Bare domains on from:/to: match any address at that domain. Multiple terms are ANDed. " +
+		"Not supported: negation (-), OR, or parentheses grouping."
+	searchMessagesFreeTextDoc = "Without mode, free text matches subject, snippet, and sender/recipient metadata only (not bodies). " +
+		"Use search_message_bodies for full-body keyword search."
+	searchMessagesPaginationDoc = "Paginate with offset/limit (default limit 20, max 50). " +
+		"Response: data, total, returned, offset, has_more."
+)
+
 func searchMessagesTool(vectorAvailable bool) mcp.Tool {
+	searchIntro := "Search emails using a subset of Gmail query syntax (not full Gmail compatibility). " +
+		searchMessagesOperatorDoc + " " + searchMessagesFreeTextDoc + " "
+	queryDesc := "Search query (e.g. 'from:alice subject:meeting after:2024-01-01'). " +
+		"See tool description for supported operators and limitations."
+
 	if !vectorAvailable {
 		return mcp.NewTool(ToolSearchMessages,
-			mcp.WithDescription("Search email metadata (subject, sender, recipients, labels, dates) using Gmail-like query syntax. "+
-				"Supports from:, to:, subject:, label:, has:attachment, before:, after:, and free text (matched against subject/snippet only, not body). "+
-				"For full message body keyword search, use search_message_bodies instead. "+
-				"Paginate with offset/limit (default limit 20, max 50). Response: data, total, returned, offset, has_more."),
+			mcp.WithDescription(searchIntro+searchMessagesPaginationDoc+
+				"For full message body keyword search, use search_message_bodies."),
 			mcp.WithReadOnlyHintAnnotation(true),
 			mcp.WithString("query",
 				mcp.Required(),
-				mcp.Description("Gmail-style search query (e.g. 'from:alice subject:meeting after:2024-01-01')"),
+				mcp.Description(queryDesc),
 			),
 			withAccount(),
 			withLimit("20"),
 			withOffset(),
 		)
 	}
 	return mcp.NewTool(ToolSearchMessages,
-		mcp.WithDescription("Search email metadata (subject, sender, recipients, labels, dates) using Gmail-like query syntax. "+
-			"Supports from:, to:, subject:, label:, has:attachment, before:, after:, and free text (matched against subject/snippet only, not body). "+
-			"For full message body keyword search, use search_message_bodies instead. "+
-			"Paginate with offset/limit (default limit 20, max 50). Response: data, total, returned, offset, has_more. "+
+		mcp.WithDescription(searchIntro+searchMessagesPaginationDoc+
+			"For full message body keyword search, use search_message_bodies. "+
 			"Vector search is configured: set mode=vector for pure semantic search or mode=hybrid to fuse BM25 and vector ranking via RRF. "+
 			"Vector/hybrid hits include matches — embedded body chunks ranked by semantic similarity to the query (up to 5 per message). "+
 			"Vector/hybrid require free-text terms; filter-only queries must omit mode. "+
@@ -224,7 +239,7 @@ func searchMessagesTool(vectorAvailable bool) mcp.Tool {
 		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("query",
 			mcp.Required(),
-			mcp.Description("Gmail-style search query (e.g. 'from:alice subject:meeting after:2024-01-01'); mode=vector|hybrid require at least one free-text term"),
+			mcp.Description(queryDesc+"; mode=vector|hybrid require at least one free-text term"),
 		),
 		withAccount(),
 		withLimit("20"),
@@ -246,13 +261,23 @@ func searchMessageBodiesTool() mcp.Tool {
 	return mcp.NewTool(ToolSearchMessageBodies,
 		mcp.WithDescription("Search message bodies by keyword using full-text search (FTS). Returns messages whose body text contains the search terms, "+
 			"plus matches — short excerpts (up to 5 per message, 300 bytes each) centered on each matched term, with char_offset and line. "+
-			"Requires at least one free-text term; use search_messages for filter-only queries (from:, label:, etc.). "+
+			"When matches_truncated is true on a hit, more than 5 excerpts matched — use search_in_message or get_message to read the full body. "+
+			"Requires at least one free-text term (bare word or double-quoted phrase). "+
+			"Known Gmail operators (from:, subject:, label:, etc.) apply as metadata filters only and do not satisfy the free-text requirement; "+
+			"filter-only queries such as from:alice are rejected — use search_messages instead. "+
+			"Unrecognized word:value tokens (e.g. RXD2:V2) are treated as literal body text, not filters. "+
+			"Query syntax: space-separated words are ANDed (each must appear somewhere in the body); "+
+			"a double-quoted phrase is one exact phrase (e.g. \"RXD2 V2\"); OR and NOT are not supported. "+
 			"Paginate with offset/limit (default limit 20, max 50). Response: data, returned, offset, has_more. "+
 			"(total is not available for body search; use has_more to detect more pages.)"),
 		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("query",
 			mcp.Required(),
-			mcp.Description("Search query with at least one free-text term (e.g. 'quarterly report' or 'from:alice budget')"),
+			mcp.Description("Body keyword query with at least one free-text term (bare word or quoted phrase). "+
+				"Gmail operators (from:, subject:, etc.) are metadata filters, not body search — "+
+				"subject:test alone is rejected; combine with body terms (from:alice budget) or use search_messages for filter-only queries. "+
+				"Unrecognized word:value tokens (RXD2:V2) are literal text. "+
+				"Space-separated words are ANDed; double quotes match an exact phrase; OR/NOT unsupported."),
 		),
 		withAccount(),
 		withLimit("20"),
@@ -375,11 +400,12 @@ func getStatsTool() mcp.Tool {
 
 func aggregateTool() mcp.Tool {
 	return mcp.NewTool(ToolAggregate,
-		mcp.WithDescription("Get grouped statistics (e.g. top senders, domains, labels, or message volume over time)."),
+		mcp.WithDescription("Get grouped statistics (top senders, recipients, domains, labels, or message volume by calendar year). "+
+			"Returns a JSON array of objects with fields Key, Count, TotalSize, AttachmentSize, AttachmentCount, and TotalUnique."),
 		mcp.WithReadOnlyHintAnnotation(true),
 		mcp.WithString("group_by",
 			mcp.Required(),
-			mcp.Description("Dimension to group by"),
+			mcp.Description("Dimension to group by. When 'time', buckets are by calendar year only (Key is a year string like \"2024\")."),
 			mcp.Enum("sender", "recipient", "domain", "label", "time"),
 		),
 		withAccount(),