fix(mcp): trim status docs, drop polling hint, capitalize extraction label

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

apps/mcp/src/server/format.ts

@@ -18,6 +18,10 @@ function day(value: string | null | undefined): string {
 	return value?.slice(0, 10) ?? ""
 }
 
+function memoryExtractionLabel(status: "dreaming" | "done"): string {
+	return status === "dreaming" ? "in progress" : "done"
+}
+
 function paginationSummary(
 	currentPage: number,
 	totalPages: number,
@@ -44,7 +48,9 @@ export function formatDocumentsList(response: DocumentsListResponse): string {
 			`- [${document.id}] "${title}" (${document.type}, ${document.status}, ${day(document.createdAt)})`,
 		]
 		if (document.dreamingStatus) {
-			lines.push(`  dreamingStatus: ${document.dreamingStatus}`)
+			lines.push(
+				`  Memory extraction: ${memoryExtractionLabel(document.dreamingStatus)}`,
+			)
 		}
 		if (document.summary?.trim()) {
 			lines.push(`  Summary: ${compactText(document.summary)}`)
@@ -152,7 +158,9 @@ export function formatDocument(document: DocumentDetails): string {
 		`Type: ${document.type}`,
 		`Status: ${document.system.status}`,
 		...(document.system.dreamingStatus
-			? [`dreamingStatus: ${document.system.dreamingStatus}`]
+			? [
+					`Memory extraction: ${memoryExtractionLabel(document.system.dreamingStatus)}`,
+				]
 			: []),
 		`Created: ${document.system.createdAt}`,
 		`Updated: ${document.system.updatedAt}`,

apps/mcp/src/server/tools/add-memory.ts

@@ -31,7 +31,7 @@ export function register(deps: ToolDeps) {
 		"add_memory",
 		{
 			description:
-				"Accept a document for asynchronous memory extraction in the user's ACTIVE space. A successful response confirms document acceptance, not extracted or searchable memories. Use get_document or list_documents to check dreamingStatus; status=done refers to content processing only. The target space is the one the user selected via select-space; pass namespace only to override it. To remove outdated information, use the separately exposed forget_memory tool. Legacy action='forget' remains supported for existing clients.",
+				"Save content as a document in the user's ACTIVE space. Memories are extracted from it in the background, so they may not be searchable right away. The target space is the one the user selected via select-space; pass namespace only to override it. To remove outdated information, use the separately exposed forget_memory tool. Legacy action='forget' remains supported for existing clients.",
 			inputSchema,
 			outputSchema: addMemoryOutputSchema,
 			annotations: MEMORY_TOOL_ANNOTATIONS,
@@ -43,7 +43,7 @@ export function register(deps: ToolDeps) {
 				const client = deps.getClient(namespace)
 
 				const result = await client.createMemory(args.content)
-				const message = `Document accepted (ID: ${result.id}, space: ${result.namespace}). Memory extraction is asynchronous and may still be queued or pending. Check dreamingStatus with get_document or list_documents; completion does not guarantee extracted or searchable memories.`
+				const message = `Document accepted (ID: ${result.id}, space: ${result.namespace}). Memories are extracted in the background and can take a moment to show up in search.`
 				const structuredContent: AddMemoryOutput = withLegacyNamespace({
 					action: "save",
 					success: true,

apps/mcp/src/server/tools/get-document.ts

@@ -31,7 +31,7 @@ export function register(deps: ToolDeps) {
 		{
 			title: "Get Document",
 			description:
-				"Read one stored document by ID from one space, including its summary, available content, and dreamingStatus when available. status=done means content processing completed, not memory readiness. dreamingStatus=dreaming means memory generation is pending, running, or awaiting recovery after failure; done means generation settled or none was needed, not guaranteed search readiness or nonzero memories. Get document IDs from list_documents or from the document shown on a search_memory result. When the document is in a named space, resolve it with list_spaces and pass namespace; otherwise use the active space.",
+				"Read one stored document by ID from one space, including its summary, available content, and memory extraction status (dreamingStatus) when available. Get document IDs from list_documents or from the document shown on a search_memory result. When the document is in a named space, resolve it with list_spaces and pass namespace; otherwise use the active space.",
 			inputSchema,
 			outputSchema: getDocumentOutputSchema,
 			annotations: READ_ONLY_TOOL_ANNOTATIONS,

apps/mcp/src/server/tools/list-documents.ts

@@ -35,7 +35,7 @@ export function register(deps: ToolDeps) {
 		{
 			title: "List Documents",
 			description:
-				"List documents in one space with their IDs, titles, types, processing status, dreamingStatus when available, dates, and summaries. status=done means content processing completed, not memory readiness. dreamingStatus=dreaming means memory generation is pending, running, or awaiting recovery after failure; done means generation settled or none was needed, not guaranteed search readiness or nonzero memories. This does not return full document content; use get_document with an ID from this result to read one document. When the user names a space, resolve it with list_spaces and pass namespace; otherwise use the active space.",
+				"List documents in one space with their IDs, titles, types, processing status, memory extraction status (dreamingStatus) when available, dates, and summaries. This does not return full document content; use get_document with an ID from this result to read one document. When the user names a space, resolve it with list_spaces and pass namespace; otherwise use the active space.",
 			inputSchema,
 			outputSchema: listDocumentsOutputSchema,
 			annotations: READ_ONLY_TOOL_ANNOTATIONS,

apps/mcp/src/server/tools/output-schemas.ts

@@ -10,14 +10,14 @@ import {
 const documentStatusSchema = z
 	.string()
 	.describe(
-		"Document processing state. done means content processing completed, not that memory extraction or memory-vector writes completed.",
+		"Document processing state. done means the content is processed; memories may still be pending, see dreamingStatus.",
 	)
 
 const dreamingStatusSchema = z
 	.enum(["dreaming", "done"])
 	.optional()
 	.describe(
-		"Memory-generation signal from the API, when available. dreaming means pending, running, or awaiting recovery, including after a failure. done means generation settled or no memories were needed; it does not guarantee a nonzero memory count or search readiness.",
+		"Memory extraction status, present when the API returns it. dreaming: pending, running, or retrying after a failure. done: settled, possibly with no memories. Neither done means memories are searchable yet.",
 	)
 
 const documentSummarySchema = z.object({