Skip to main content
Glama

list_docs

Read-onlyIdempotent

Map all project documents to identify essential resources. Retrieve titles, versions, and navigation paths for each file without downloading full content to efficiently browse project storage.

Instructions

List a project's documents — id, title, slug path, version, who touched them last. Carries NO document bodies, so it is cheap on a whole project and serves as a map of it (get_doc returns one page). Returns path and has_children for navigating the tree. Paged: the reply carries total_count and has_more; when has_more is true, offset reads the rest.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_id": "<project_id>"
    },
    "name": "list_docs"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoPage size (default 50, max 200).
offsetNoDocuments to skip (default 0).
project_idYesProject UUID.
include_archivedNoAlso list archived documents. Default false: only live documents.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.1.6
    • changedInput schema / properties / include_archived / description
      Previous value: -"Include archived documents."New value: +"Also list archived documents. Default false: only live documents."
  2. First observedv0.1.1

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already declare readOnly/idempotent/non-destructive, so the description adds real value by disclosing that no document bodies are transferred and how the result is paged (total_count, has_more, offset for the remainder). It omits nothing dangerous, though it doesn't state the default exclusion of archived docs, which matters for interpreting the map.

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

Conciseness5/5

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

Three tight sentences: scope first, cost/no-bodies benefit second, pagination mechanics last. No repetition of the schema and every clause carries information.

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?

With no output schema, the description carries the burden of return-shape explanation and does so fully: listed fields, path/has_children for tree navigation, and paging metadata. An agent can call it and interpret the response correctly without further assumptions.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description goes beyond it by explaining the offset/has_more interplay as a continuation protocol rather than a bare numeric field. It adds nothing on include_archived, which stays purely schema-documented.

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

Purpose5/5

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

States a specific verb and resource ('List a project's documents') and enumerates what each entry carries (id, title, slug path, version, last editor). It also names the sibling it replaces for single-item reads ('get_doc returns one page'), so an agent can route without opening the schema.

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?

Explicitly frames the use case ('cheap on a whole project, serves as a map of it') and contrasts with get_doc for single-page reads. It does not mention search_docs or the include_archived toggle as an alternative, so the exclusion set is partial but usable.

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