Skip to main content
Glama

文档列表(分页)

gwl_list_documents
Read-onlyIdempotent

Lists document metadata by scope with folder, tag, author, and deleted filters, returning paginated results without full content.

Instructions

按范围列出文档元信息(不含正文),逐条判权后分页。 返回 {items,page,size,total,has_more};items 是 meta 视图,取正文用 gwl_get_document_by_id(不加浏览数)或 gwl_get_document(会 +1 浏览数)。 folder_id:0=根目录(默认)、-1=该范围下全部文件夹、正整数=指定文件夹。 deleted=1 只看回收站里的(需相应权限);author_id 只在 scope=public 生效。 tags 最多 8 个,tag_mode=all 表示同时命中,any 表示任一命中。

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

Input Schema

NameRequiredDescriptionDefault
pageNo页码,从 1 开始。非法值由上游回落到 1,不报错。
sizeNo每页条数,1~100;超过 100 上游按 100 处理。
tagsNo标签过滤(最多 8 个),上游按逗号解析。
scopeNo文档范围,默认 public。public
deletedNo0=只看未删除(默认),1=只看已软删除。非法值由上游回落。
tag_modeNo标签命中方式:all=同时具备,any=任一具备。
author_idNo只看某作者的文档;仅 scope=public 生效。
folder_idNo文件夹过滤:0=根目录,-1=全部文件夹,正整数=指定文件夹。

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), yet the description still adds real substance: results are permission-filtered per item ('逐条判权后分页'), body text is excluded, deleted=1 requires extra permission, and author_id is silently inert outside scope=public. The page/size/total/has_more envelope restates what the output schema likely covers, so it earns less credit.

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?

Dense and front-loaded: purpose first, then return shape, then cross-tool routing, then per-parameter constraints. Sentences are short and purposeful, with only mild redundancy against the JSON schema for folder_id and tag_mode.

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 an 8-parameter read tool with full annotation and output-schema coverage, the description does what structural fields cannot: it explains permission-based filtering, body/metadata separation, and parameter precedence quirks. The remaining gap is disambiguation from near-name list siblings (my documents, trash, search), which matters given the overlapping deleted/folder filters.

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 schema already documents page, size, tags, scope, deleted, tag_mode, author_id, and folder_id. The description largely paraphrases those same semantics (folder_id 0/-1/positive, tags max 8, tag_mode all/any), adding only the permission requirement for deleted=1 and reinforcement that author_id is scope=public-only. Baseline 3 is appropriate when the schema does the heavy lifting.

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 opens with a specific verb plus resource and scope ('按范围列出文档元信息(不含正文)'), and it explicitly separates itself from the get tools by noting items are a meta view and pointing to gwl_get_document_by_id / gwl_get_document for body content. It does not, however, distinguish itself from other listing siblings such as gwl_list_my_documents, gwl_list_trash, or gwl_search, so an agent must infer which list variant fits its case.

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?

Useful conditional guidance is present: deleted=1 only surfaces trash items and needs permission, author_id only applies when scope=public, and content retrieval requires switching to a get tool. What is missing is any explicit 'use this instead of X when…' statement toward the sibling list tools, so the guidance is clear but not exclusionary.

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