yuque-ai-mcp

yuque_list_docs

List documents in a Yuque repository sorted by update time, with pagination, deleted-doc view, and change-time filtering for incremental sync.

Instructions

List documents in a repo, sorted by updated_at desc. limit ≤ 100. Supports deleted (recycle view) and changed_at_gte (incremental sync). GET /repos/:id/docs. 详见 references/api/doc_api.md

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": {
      "book_id": "<book_id>"
    },
    "name": "yuque_list_docs"
  }
}

Input Schema

Name	Required	Description
`raw`	No	Return raw full JSON (default false, returns trimmed fields)
`limit`	No	Page size, max 100, default 100
`offset`	No	Pagination offset, default 0
`book_id`	Yes	Repository ID (numeric) or namespace like group/book_slug (required)
`deleted`	No	Return the deleted-docs view (default false). ⚠️ Yuque treats the mere presence of this param as truthy, so it is only sent when true; response items carry deleted_at / deleted_slug
`changed_at_gte`	No	Only return docs changed at/after this ISO 8601 time (incremental sync), e.g. 2026-10-16T00:00:00Z
`optional_properties`	No	Extra fields, comma-separated. Supports: hits, tags, latest_version_id

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv4.0.0Nov 13, 2026

addedInput schema / properties / changed_at_gte

Added value: +{
+  "description": "Only return docs changed at/after this ISO 8601 time (incremental sync), e.g. 2026-10-16T00:00:00Z",
+  "type": "string"
+}

addedInput schema / properties / deleted

Added value: +{
+  "description": "Return the deleted-docs view (default false). ⚠️ Yuque treats the mere presence of this param as truthy, so it is only sent when true; response items carry deleted_at / deleted_slug",
+  "type": "boolean"
+}

First observedv0.1.0Sep 30, 2026

TDQS

B3.4/5.0

Behavior3/5

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

With no annotations, the description carries the disclosure burden; it adds the sort order, the 100-item cap, and the recycle/incremental-sync modes, which is genuine behavioral context. However, it omits authentication requirements, pagination behavior in practice, and any sense of response volume or field trimming beyond what the schema's 'raw' flag already says.

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?

Roughly four compact clauses with the primary purpose and ordering front-loaded; nothing is padded. The trailing file reference ('详见 references/api/doc_api.md') is a pointer rather than explanatory content and assumes the agent can read Chinese and resolve the path, a minor wart.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter list tool with no output schema, the description covers the key modes and ordering but says nothing about what a returned item looks like or how trimmed fields differ from 'raw', which an agent would want before consuming results. It is adequate but leaves clear gaps.

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 parameters are already fully documented, including the truthiness caveat on 'deleted'. The description adds essentially no meaning beyond the schema — it restates the limit cap and the two mode flags — so the baseline 3 applies.

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?

States a specific verb and resource ('List documents in a repo') plus default ordering ('sorted by updated_at desc') and the underlying endpoint, so the agent knows exactly what it retrieves. It does not explicitly distinguish itself from near-name siblings such as yuque_web_list_docs or yuque_list_recycles, which keeps it below a 5.

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?

Usage context is only implied: it mentions the 'deleted (recycle view)' and 'changed_at_gte (incremental sync)' modes, which hints at when these flags apply, but there is no explicit statement of when to choose this tool over alternatives like yuque_list_recycles or yuque_web_list_docs, nor any prerequisites.

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

Deploy Server