Skip to main content
Glama

The documents and the folders

docs
Read-onlyIdempotent

Lists local Markdown documents newest first with folder, open or archived status, and content clues to pick one to read. Returns document pages in reading order when needed.

Instructions

The documents, newest first, with each one's folder, whether it is put away or locked, and what it holds (words, sections, key words): enough to pick one unopened. A task's words come with the task. Ask before writing, so nothing is kept twice.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "docs"
  }
}

Input Schema

NameRequiredDescriptionDefault
deepNoWith `folder`: the folders below it too
afterNoSkip this many, to page on while `total` is higher
limitNoAt most 200, 50 by default
scopeNoDefaults to either
folderNoOnly the documents in this folder, by name, path or id, without pages; the folders below are named under `below`
foldersNoEvery folder too, with id, path, icon and size; the text already names them
page_ofNoOnly the pages of this document, by id, in reading order

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv1.43.2
    • changedInput schema / properties / after / description
      Previous value: -"Skip this many. With `total` higher than what came back, ask again with `after` set to how many you have"New value: +"Skip this many, to page on while `total` is higher"
    • changedInput schema / properties / deep / description
      Previous value: -"With `folder`: the documents of the folders below it too"New value: +"With `folder`: the folders below it too"
    • changedInput schema / properties / folder / description
      Previous value: -"Only 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"New value: +"Only the documents in this folder, by name, path or id, without pages; the folders below are named under `below`"
    • changedInput schema / properties / folders / description
      Previous value: -"Send 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"New value: +"Every folder too, with id, path, icon and size; the text already names them"
    • changedInput schema / properties / page_of / description
      Previous value: -"Only the pages of this one document, by its id, in reading order"New value: +"Only the pages of this document, by id, in reading order"
  2. First observed

TDQS

A3.7/5.0
Behavior4/5

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

The annotations already establish that this is a safe, read-only, idempotent operation. The description adds useful behavioral context beyond that: newest-first ordering, inclusion of folder and lock/archive status, content summaries, and a caution to ask before writing.

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 description is short and front-loads the key information about what is returned and why. Some phrasing is slightly cryptic, such as "A task's words come with the task," but there is little wasted text.

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?

Given the rich schema descriptions and read-only annotations, the description is complete enough for an agent to understand the tool's output shape and safe usage. It could be stronger with explicit sibling routing, but no critical information is missing.

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 description coverage is 100%, so the input schema already documents all seven parameters thoroughly. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline score of 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 clearly identifies the resource as documents, states the ordering (newest first), and lists the metadata returned (folder, archived/locked status, contents). It does not use an explicit verb like "list," but an agent can still infer the operation and distinguish it from write-oriented siblings.

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?

It gives implied usage guidance: enough detail to pick an unopened document, task words come with the task, and one should ask before writing. However, it does not explicitly say when to use this tool versus alternatives such as find, read_doc, or folder.

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