Skip to main content
Glama

按 id 读文档

gwl_get_document_by_id
Read-onlyIdempotent

Read a document's full text by ID without increasing its view count and return its version for optimistic-lock updates; use this before editing.

Instructions

按文档 id 读取全文,不增加浏览数,是编辑前的推荐读法。 返回里的 version 就是乐观锁基线,更新时原样带回 data.version。 软删除的文档只有作者或超管能看到,其他人 404。

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": {
      "doc_id": "<doc_id>"
    },
    "name": "gwl_get_document_by_id"
  }
}

Input Schema

NameRequiredDescriptionDefault
doc_idYes文档 id(路径参数)。

Output Schema

NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A4.4/5.0
Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses three behavioral facts an agent could not otherwise know: reads do not increment view count, the returned version is the optimistic-lock baseline to pass back as data.version, and soft-deleted documents 404 for anyone but the author or super admin. That is exactly the kind of context annotations cannot carry.

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 short sentences, each carrying distinct information: read semantics, locking contract, permission rule. The most decision-relevant facts (read mode, recommended before editing) are front-loaded with no filler.

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?

A one-parameter read tool with full schema coverage, an output schema, and rich annotations needs little else. The description still covers the locking workflow and the 404 permission edge case, so nothing an agent needs in order to call it correctly is missing.

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% for the single doc_id parameter, so the baseline is 3. The description still adds meaning by explaining which doc_id values resolve for this caller (soft-deleted docs resolve only for author/super admin, otherwise 404), which is parameter-relevant behavior not present in the schema.

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 names a specific verb and resource ("按文档 id 读取全文") and adds a distinguishing trait ("不增加浏览数") that implicitly separates it from the sibling gwl_get_document, which presumably counts a view. It never names that sibling explicitly, so the differentiation must be inferred rather than read.

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 clearly states the recommended context ("是编辑前的推荐读法"), which routes an agent to this tool ahead of gwl_update_document, and adds the precondition that only authors or super admins can read soft-deleted docs. It gives no explicit "do not use when" or named alternative, so it stops just short of full guidance.

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