Skip to main content
Glama

My documents and files

documents_list
Read-onlyIdempotent

Your own documents gathered from your Barmaan account: calibration certificates, invoices, quotations and proformas, order summaries, files attached to your service requests and messages, project deliverables and application files. Newest first. Filter by folder (contracts, quotations, invoices, drawings, reports, certificates, uploads, other), kind, source, status (active, expired, withdrawn), q (title, number, extension) or an issued date range (from/to, YYYY-MM-DD). Also returns per-folder counts. partial_sources lists sources that failed to load (an empty list means every source answered). Page with next_cursor.

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": "documents_list"
  }
}

Input Schema

NameRequiredDescriptionDefault
qNoTitle, document number or file extension.
toNoIssued on or before (YYYY-MM-DD).
fromNoIssued on or after (YYYY-MM-DD).
kindNo
sortNo
limitNo
cursorNoValue of next_cursor from the previous page.
folderNo
sourceNo
statusNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Added

TDQS

A3.7/5.0
Behavior4/5

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

Annotations already establish readOnly/idempotent/non-destructive, but the description adds real behavioral context beyond them: default ordering (newest first), partial-failure disclosure via partial_sources with the explicit meaning of an empty list, per-folder counts in the response, and cursor-based paging. It stops short of stating limits, cost, or what a failed source means for the returned set.

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?

Front-loaded with scope and contents, then filters, then return-shape notes, then pagination — a sensible order with no filler sentences. The long document-type enumeration is verbose but earns its place by helping an agent recognize whether a needed document type lives here.

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?

For a read-only, filter-heavy list tool with no output schema, the description covers scope, filtering axes, ordering, partial-result semantics, and paging — enough to call it correctly. The missing pieces are sort/limit behavior and an explicit hand-off to sibling document tools.

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?

With only 40% schema description coverage, the description does compensate for several undocumented params: it spells out folder values, status values, source/kind intent, that q matches title, number, or extension, and that from/to are issued dates in YYYY-MM-DD. It leaves sort (newest/oldest/name), limit (default 10, max 25), and cursor semantics unaddressed, which is a meaningful gap across 10 parameters.

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?

Names the resource precisely ("Your own documents gathered from your Barmaan account") and enumerates the document types it covers, including certificates, invoices, quotations, deliverables, and attachments, so an agent knows exactly what population is returned. It never names a sibling (e.g. my_order_documents or certificates_list) to draw the boundary, 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?

The filtering sentence implies the intended use case (browse/search the caller's document archive) and the scope phrase "your own documents" implies personal rather than company-wide scope. There is no explicit when-to-use versus when-to-pick-a-sibling statement and no exclusions, so an agent must infer the alternative.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources