Skip to main content
Glama

The documents and the folders

docs

List stored documents with folder, archive/lock status, and content metadata to choose what to open and avoid duplicating existing work before writing.

Instructions

Everything written down to consult — not the words a task keeps with it, which come with the task — the one written most recently first, with the folder each one sits in, whether it was put away, whether it is locked, and for each one what it is about: how many words it holds, how many sections, and the words it leans on. That is enough to pick which document to open without opening any of them; the print of the one you go on to edit comes back from read_doc or outline_doc. Ask for it before writing, so you do not write again what is already kept.

Input Schema

NameRequiredDescriptionDefault
deepNoWith `folder`: the documents of the folders below it too
afterNoSkip this many. With `total` higher than what came back, ask again with `after` set to how many you have
limitNoAt most 200, 50 by default
scopeNoDefaults to either
folderNoOnly the documents that sit in this one folder, by its name, its whole path or its id. Pages are left out — they are kept where their document is — and what the folders below it hold is theirs, not this one's: the answer names them under `below`, and `deep` brings their documents
foldersNoSend every folder back too, with its id, path, icon and how much it holds. The answer already names them all in its text, so ask for this only when a name is not enough
page_ofNoOnly the pages of this one document, by its id, in reading order

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observed

TDQS

A3.8/5.0
Behavior4/5

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

With no annotations, the description carries the full burden and does well: default ordering (most recently written first), the exact fields disclosed per document, the subfolder handling ('the answer names them under `below`'), and the repagination loop via `after` and `total`. It stops short of stating permissions or result-size limits beyond the schema's 200/50 default.

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

Conciseness3/5

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

Three sentences with the return shape front-loaded, but the phrasing is florid and indirect — 'the `print` of the one you go on to edit' and 'the words it leans on' require decoding — which slows an agent scanning for a listing tool.

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

Completeness4/5

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

No output schema exists, yet the description characterizes the returned record fields and ordering well enough to use results without trial. Given seven optional parameters and folder/archive/scope interplay, it is nearly complete, though the interaction between `folders` and the textual folder listing could be tightened.

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 100%, so all seven parameters are already documented, including defaults and enum values. The description adds only the pagination resume pattern and the meaning of `below`, so per the high-coverage baseline a 3 is appropriate.

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?

The description makes clear this returns all documents with per-document metadata (folder, archived state, lock, word/section counts, key terms), and explicitly excludes task-attached notes. It distinguishes itself from read_doc and outline_doc by framing the result as enough to choose a document without opening it.

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

Usage Guidelines4/5

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

It gives an explicit trigger — 'Ask for it before writing, so you do not write again what is already kept' — and routes the agent to read_doc / outline_doc once a document is chosen. No exclusions versus other listing tools like find or lists are stated.

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