minirag-mcp

by sfrangulov

Overview Schema Source Related Servers Discussions Admin

Python

Local

list_files

List files found on disk under the document roots, plus indexed data/url sources.

Instructions

List files found on disk under the document roots, plus indexed data/url sources.

Each disk file is reported with a state: "ingested" (index matches disk), "stale" (changed on disk since it was indexed), "stale_scheme" (unchanged on disk, but indexed under an older chunking scheme, so its vectors are not comparable with current ones), "not_ingested" (never indexed), or "unreadable" (indexed and still on disk, but of a type this installation cannot read because an optional extra is absent — images need [ocr]). Everything but "ingested" and "unreadable" needs a sync_start; an "unreadable" source is kept as indexed and no sync can refresh it here. "stale_scheme" is the per-source view of what status reports as staleChunkCount. Data and url sources have no disk state to compare against, so they are "ingested" or "stale_scheme".

unlistedFolders names each folder the scan could not see into (no read permission, a missing or unmounted drive), with what to do about it. Indexed files under one are listed as "unlisted": still indexed and searchable, not checked against the disk.

labels, dateFrom and dateTo filter as in query_documents; sort="date" lists newest first, documents without a date last. Rows carry labels and date when present.

Input Schema

Name	Required	Description	Default
`sort`	No
`scope`	No
`dateTo`	No
`labels`	No
`dateFrom`	No

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.0Oct 22, 2026

addedInput schema / properties / dateFrom

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / dateTo

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / labels

Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        ]
+      },
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

addedInput schema / properties / sort

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null
+}

First observedv0.1.0Aug 7, 2026

TDQS

A4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and does so thoroughly: it defines each of the five states, explains that 'unreadable' cannot be refreshed by any sync, ties stale_scheme to status.staleChunkCount, and describes unlistedFolders (permission/mount failures) with how those files appear. Auth/read-permission failure handling is disclosed, which is exactly the kind of context annotations would otherwise lack.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The state definitions are front-loaded and dense with necessary information for what is genuinely a multi-state model. It runs long, but nearly every clause conveys distinct semantics; the only slack is the reference-based explanation of the date/label filters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return structure needn't be spelled out, yet the description still notes that rows carry labels and date when present. Given no annotations, five optional parameters and a nuanced filesystem/index state model, the description covers everything an agent needs to interpret and call the tool correctly, except the undocumented scope parameter.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must compensate. It explains labels, dateFrom and dateTo (though only by reference: 'filter as in query_documents') and gives sort semantics ('sort="date" lists newest first, documents without a date last'). But 'scope' is never explained at all, leaving one of five parameters fully opaque.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: lists disk files under the document roots plus indexed data/url sources. Its scope is clearly an inventory listing rather than a content search, though it never names query_documents as the alternative for content queries, so sibling differentiation is left implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied rather than stated: the state vocabulary (ingested/stale/not_ingested) tells an agent this is for auditing index-vs-disk health, and it notes that everything except 'ingested'/'unreadable' needs a sync_start. But there is no explicit 'use this when you want X, use query_documents when you want Y' routing, which sibling tools like query_documents make necessary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server