Scans a local directory read-only to count readable files and extractable fact entries, confirming data volume before a retrospective without writing or uploading.
只读扫描本地目录，统计可读文件与可提取的事实条数；不写盘、不上传。用于复盘前的体量确认。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 要扫描的目录 | |
| max_files | No |
Changes observed during successful MCP inspections.
v0.13.0Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations supplied, the description carries the full safety burden and does well: it explicitly declares read-only behavior, no disk writes, and no uploads. It omits what happens when the directory exceeds max_files (silent truncation?) and gives no hint of cost or runtime on large trees.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight clauses with the safety guarantees front-loaded and the usage context trailing; no filler, no repetition of the name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema scan, the description covers purpose, safety, and workflow position, which is most of what an agent needs. The gap is the undocumented cap behavior on max_files, which matters for a counting tool because a truncated scan yields misleading counts.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%: 'path' is documented in the schema, but max_files (default 20000) is undocumented and the description never mentions a file cap or truncation behavior. The truncation semantics are the one thing the description could have added beyond the schema and it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb and resource ('只读扫描本地目录') plus an explicit output ('统计可读文件与可提取的事实条数'), so an agent can tell it apart from the heavier mkt_retro_analyze. It stops short of naming the sibling outright, leaving that inference to the '复盘前' phrase.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The clause '用于复盘前的体量确认' places the tool in a workflow and implies it is a pre-check rather than the retro analysis itself. It never states exclusions or names mkt_retro_analyze as the follow-up step, so the routing is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.