From 74c26656eae559b61bafbdd31918e4c63258cee0 Mon Sep 17 00:00:00 2001
From: Ziyang Guo <121015044+RerankerGuo@users.noreply.github.com>
Date: Tue, 29 Sep 2026 20:50:44 +0800
Subject: [PATCH] docs(stat): say which consumers actually see mime and
 frontmatter

Review feedback on #566: the module docstring told the agent it gets
"mime type and ... the parsed frontmatter alongside in metadata", which
reads as though an agent can use those fields to decide whether to
download or parse a file. It cannot: the MCP service returns only
`response.answer` (`mcp_tools.py` -> `return response.answer`), so
`metadata["mime"]` and `metadata["frontmatter"]` reach direct `Response`
consumers but never an MCP caller.

Spell the split out instead of implying one audience: the answer carries
path, type, size and mtime, and an agent that needs the frontmatter has
to read the file rather than stat it. The envelope description below is
unchanged, since it already lists the full metadata shape.
---
 reme/steps/file_io/stat.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/reme/steps/file_io/stat.py b/reme/steps/file_io/stat.py
index ca3c3f51..f82203b5 100644
--- a/reme/steps/file_io/stat.py
+++ b/reme/steps/file_io/stat.py
@@ -1,9 +1,11 @@
 """``file_stat`` — peek at file metadata under the workspace without copying it.
 
-Cheap inspection alternative to ``file_download``: the agent gets
-size and mtime in the answer, with mime type and (for markdown files)
-the parsed frontmatter alongside in metadata — enough to decide whether
-to download / parse / skip without paying the copy cost.
+Cheap inspection alternative to ``file_download``. The answer carries the
+path, type, size and mtime, and the answer is all an MCP caller receives:
+MCP returns only ``response.answer``. ``mime`` and, for markdown files,
+the parsed frontmatter stay in ``metadata`` with the rest of the envelope,
+so they reach direct ``Response`` consumers but never an MCP caller — an
+agent that needs the frontmatter must read the file, not stat it.
 
 Returns a uniform envelope: