yuque-ai-mcp

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

With no annotations provided, the description carries the full disclosure burden, and it does add real behavioral facts: concurrent execution, read-only nature, and a 20-item ceiling. However, it omits return shape (trimmed vs raw handling) and failure behavior for invalid IDs, and the reference to references/api/doc_api.md is not something an agent can dereference.

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

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

Two compact clauses, front-loaded with the verb and the key constraints; almost nothing is wasted. The trailing markdown-file reference is the one element that does not earn its place for an agent.

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

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

For a read-only batch fetch with no output schema, the essentials (batch semantics, read-only, cap) are present, but the concurrency/return-format behavior and what happens on partial failures are left unspecified. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so all three parameters are already documented in the schema, including the 'max 20' bound and the raw/trimmed toggle. The description adds no parameter meaning beyond what the schema provides, making the baseline 3 correct.

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

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

States a specific verb+resource ('Batch get document details') and its scope via 'batch' and 'max 20', which lets an agent distinguish it from the single-doc sibling yuque_get_doc. It does not explicitly name that alternative, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance, no conditions selecting it over yuque_get_doc or yuque_list_docs, and no exclusions. The 'max 20' cap is a constraint, not usage guidance, so an agent must infer the batching rationale on its own.

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

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

No annotations are supplied, so the description carries the burden; it does disclose read-only semantics, concurrency, and a batch cap, which is useful. However it omits partial-failure behavior (what happens if some IDs are invalid) and defers semantics to an external file 'references/api/repo_api.md' that isn't part of the tool definition.

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

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

A single compact sentence plus a pointer, front-loading the core operation and scope. Efficient, though the trailing file reference is a dangling pointer that doesn't earn much of its space.

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

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

For a one-parameter, no-output-schema read tool this covers the essentials (what, safety, cap). It is not complete about behavior under partial failure or about the resolution of string IDs vs numeric IDs, which matters for a batch call with no annotations.

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

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

Only one parameter and schema coverage is 100%, with the example formats ([123,456] or ["group/repo-a"]) already documented in the schema. The description repeats the max-20 constraint without adding format or id-resolution semantics, so baseline 3 applies.

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

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

States a concrete verb+resource: batch retrieval of repo details, with a scope qualifier (max 20). It is distinguishable from yuque_get_repo (single) and yuque_list_repos, though it never explicitly names that contrast. Sibling differentiation is implicit rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to prefer this over yuque_get_repo or yuque_list_repos, nor any prerequisite/permission note. The only usage constraint given is the max-20 cap, which is also in the schema.

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

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

With no annotations the description carries the full burden, and it does meaningful work: the destructive-op safety gate (confirm token), the auto-reuse behavior of createTitle, and name-based lookup via target_title. It omits failure semantics — whether ops are atomic, what happens if one op in the array is invalid — which matters for a batch mutation.

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

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

Dense and front-loaded: the interaction model comes first, then the action list, then the warning, then the alternative tool. Some of the ops enumeration duplicates the schema description, which is the only waste.

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

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

For a 3-required-param batch mutation with no output schema and no annotations, the description covers the destination, the safety gate, action semantics, and the sibling alternative. Missing only return/error behavior, which the absence of an output schema leaves unaddressed.

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

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

Schema description coverage is 100% and the ops/confirm/book_id descriptions already document the accepted action names and the confirm requirement, so the description largely restates structured data. Baseline 3 is correct; it adds no format or syntax detail beyond the schema.

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

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

States a specific verb+resource ('Batch update repo TOC') and immediately clarifies the unusual interaction model ('Agent provides ops plan, tool executes only'), then enumerates the five supported actions. An agent can tell this apart from the singular yuque_update_toc and from the web_* catalog tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes cross-book copy to yuque_copy_doc and states the confirm='RESTRUCTURE' precondition for remove/move. It stops short of explaining when to prefer this batch tool over yuque_update_toc for a single-node change, which is the most likely sibling confusion.

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

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

With no annotations, the description carries the burden. It usefully discloses that the agent must clean the body beforehand and that source_url/source_title get appended as a footer link, plus points to extended_api.md for details. It says nothing about auth requirements, duplication behavior, or failure modes for a mutation tool.

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

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

Two compact sentences that front-load the operation and the workflow. The trailing '详见 references/api/extended_api.md' is a slightly dangling pointer to external docs, but it costs little space.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers the happy-path workflow but omits what the tool returns, whether it creates a new doc or overwrites, and how target_book_id namespaces are resolved. Adequate but with clear gaps.

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

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 all seven parameters including source_url and source_title. The description only echoes the required set (title/body/format/paths) and adds no syntax or format guidance beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource ('Copy a single document to another repo'), which clearly separates it from create_doc and copy_repo in spirit. It does not explicitly name the sibling it competes with (e.g., yuque_create_doc), so the differentiation is implied rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition workflow: fetch the source via yuque_get_doc, clean the content, then call this tool with title/body/format/paths. That is real when-to-use context. It stops short of naming when NOT to use it or pointing to create_doc/import alternatives.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses one useful trait ('creates TOC dirs and copies') but omits permissions/auth requirements, overwrite or conflict behavior on the target repo, idempotency, and whether the operation is synchronous or long-running.

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

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

Two front-loaded sentences covering action and input shape, with no padding. The trailing pointer to an external markdown file is terse but not self-contained.

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

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

For a 3-parameter mutation tool with no annotations and no output schema, the description leaves key gaps: return value, failure modes, source-vs-target semantics, and the undefined 'cleaned documents' contract that the agent must satisfy. It leans on an out-of-band reference file rather than being self-sufficient.

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

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 adds only marginal value by restating the documents shape as (title/body/format/paths) and flagging that documents must be 'cleaned,' without defining what cleaning entails.

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

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

States a specific verb and resource ('Batch copy documents to another repo') plus the side effect of creating TOC dirs. The 'batch' qualifier implicitly separates it from the singular yuque_copy_doc, though no sibling is named outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance and no named alternatives (e.g., yuque_copy_doc for a single doc, yuque_import_file for file ingestion). The only hint is 'Agent provides cleaned documents array,' which describes input prep rather than tool selection.

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

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

No annotations are provided, so the description carries the full burden for a mutation tool. It notes the HTTP method (POST) but says nothing about authorization requirements, whether the document must exist, what happens to the DSL on error, or what the response contains. The pointer to an external markdown reference ('详见 references/api/board_api.md') does not help an agent that cannot read that file inline.

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

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

The first sentence is tight and front-loaded with verb, resource, and the three supported board types; the endpoint is a compact second clause. The trailing Chinese reference to an external file is low-value for most agents but does not bloat the text significantly.

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

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

For a mutating tool with no annotations and no output schema, the description is too thin: it omits side effects, error conditions, and return information, and relies on an out-of-band doc reference. An agent has enough to attempt the call but not enough to call it confidently.

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

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 all five parameters including the mutually exclusive doc_id/url pair and the insert_after_lake_id behavior. The description's only added value is repeating the board type values, so the baseline 3 applies.

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

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

The description states a specific verb and resource ('Create a board resource (mindmap/flowchart/architecture diagram) in a document') and names the endpoint, so an agent knows it produces a board artifact embedded in a doc. It does not explicitly name a sibling like yuque_update_board or yuque_get_board to differentiate itself, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all – no statement that this is for creating a new board versus modifying one with yuque_update_board, no prerequisites about the target document, and no mention of required permissions. The agent is left to infer everything from the name.

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

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

No annotations exist, so the description carries the full burden for a mutating tool. It discloses the HTTP endpoint and the parent-node placement default, but says nothing about auth requirements, failure modes, or side effects such as creating a TOC node.

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

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

Three short sentences, front-loaded with the action and immediately followed by the conditional parent-node rule. The mixed-language phrasing and file pointer add minor friction but no real bloat.

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

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

An 8-parameter mutation tool with no annotations and no output schema should at least sketch returns, auth and error behavior; the description covers only parent placement and the endpoint, leaving the calling agent under-informed.

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

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

Schema description coverage is 100%, so the baseline is 3. The parent_uuid sentence merely restates the schema's own Chinese description, and the remaining 7 parameters get no extra meaning from the description.

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

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

States a specific verb and resource ('Create a document in a repo'), which cleanly separates it from siblings such as yuque_create_note, yuque_update_doc and yuque_import_file. It does not explicitly name those siblings, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Nothing says when to choose this tool over yuque_create_note, yuque_import_url or yuque_copy_doc, nor what prerequisites (permissions on the repo) are needed. Only a pointer to an external API reference file is offered, which is not actionable selection guidance.

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

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

With no annotations, the description carries the full burden. It does disclose the HTTP method (POST /notes) and the returned fields (id, slug, note_url), which is genuinely useful given there is no output schema. It says nothing about required permissions, rate limits, or side effects, and notably does not explain which namespace/book the note lands in despite the schema having no parent parameter.

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

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

Front-loaded with the action, followed by return values and endpoint in a compact sequence. The trailing Chinese reference pointer ('详见 references/api/note_api.md') is compact but assumes a doc file the agent may not resolve, slightly diluting an otherwise efficient sentence.

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

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

The absence of an output schema is partly compensated by naming the returned fields, and 100% schema coverage handles the inputs. However, for a create/mutation tool with zero annotations, the description omits any permission requirements, target container, or effect on existing data, leaving material gaps.

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

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 both 'body' and 'raw'. The description adds no parameter-level detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb+resource ('Create a note') and clarifies the resource with '(short memo)', which implicitly separates it from the doc-oriented siblings like yuque_create_doc. It does not explicitly name the alternative, so it falls short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no exclusions, and no routing between this and yuque_create_doc / yuque_update_note / yuque_list_notes. The agent must infer from the name alone when a note is preferable to a doc.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the HTTP method and auto-detection behavior, but says nothing about required permissions, side effects, duplicate-name handling, idempotency, or what is returned after creation.

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

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

The description is very short and front-loads the core action before adding endpoint and documentation details. The trailing Chinese phrase '详见 references/api/repo_api.md' is a minor structural inconsistency but does not waste words.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description is thin. It points to an external API reference but does not itself cover authorization requirements, side effects, failure modes, or return behavior, leaving significant gaps for an agent to infer.

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

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

Schema description coverage is 100%, and the input schema thoroughly documents each parameter (login, name, slug, public, description, etc.). The description adds no parameter-level meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

States a specific verb and resource ('Create a repo') and clarifies that it auto-detects between user and group endpoints, which helps distinguish it from read/update/delete repo siblings. It does not explicitly distinguish itself from copy_repo, which also creates a repository, so it falls short of the top score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'Create a repo' implies the basic usage context, and 'auto-detects user vs group endpoint' tells the agent it does not need to choose an endpoint manually. However, there is no explicit when-to-use guidance, no exclusions, and no mention of alternatives such as copy_repo.

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

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

With no annotations, the description carries the full burden. It does add genuinely useful behavior: that deletion is a soft delete to the recycle bin and that a 'DELETE' confirmation token is enforced as a safety guard. It omits permissions/auth requirements, whether the action is reversible from here, and what happens to the document's references.

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

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

Front-loads the core action and effect, then the guard, then the endpoint. The trailing pointer to references/api/doc_api.md is a bit of an afterthought but doesn't obscure the key information. No wasted filler.

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

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

For a destructive, unannotated tool with no output schema, the essentials (soft delete, confirm guard, endpoint) are covered. However, auth/permission requirements and the impact on the doc's placement or history are not addressed, leaving meaningful gaps for an irreversible-looking action.

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

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

Schema coverage is 100%, so all four parameters including the confirm token are already documented in the schema. The description's restatement of confirm='DELETE' duplicates rather than extends the schema, so baseline 3 is appropriate.

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

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

States a specific verb+resource ('Delete a document') and crucially clarifies the effect is a soft delete ('moves to recycle bin'), which distinguishes it semantically from a permanent delete such as a recycle-destroy tool. It does not, however, name the sibling it differs from (e.g. yuque_destroy_recycle or yuque_web_delete_doc), so an agent must infer the distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to choose this tool over the web variant, over yuque_destroy_recycle, or what prerequisites (ownership/permissions) apply. The 'moves to recycle bin' note hints at reversibility but is not framed as usage guidance.

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

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

No annotations are provided, so the description carries the behavioral burden. It does disclose the destructive nature via 'Remove' and the safety guard confirm='DELETE', plus the endpoint. It does not state whether the removal is reversible, what permissions are required, or what the response contains — notable gaps for an unannotated delete tool.

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

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

Three short fragments, front-loaded with the action and the critical confirm guard, followed by the endpoint and a reference pointer. Every element is useful; the mix of English and Chinese in the reference line is slightly uneven but not wasteful.

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

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

With no annotations and no output schema, the description is the sole source of behavioral context. It covers the action, the safety guard, and the endpoint, but leaves permission requirements, reversibility, and return shape unspecified — adequate but incomplete for a destructive operation.

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

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 login, id, confirm, and raw in detail. The description only restates the confirm='DELETE' requirement, adding no syntax or format detail beyond the schema. Baseline 3 applies.

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

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

States a specific verb+resource: 'Remove a member from a group', which clearly distinguishes it from siblings like yuque_get_group_users and yuque_update_group_user. It also names the underlying endpoint DELETE /groups/:login/users/:id, reinforcing the mutation semantics. No explicit sibling routing, but the purpose is unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the clear 'remove a member' framing and the required confirm='DELETE' prerequisite, which is stated. However, there is no guidance on when to choose this over yuque_update_group_user or what prerequisites (admin role, group ownership) apply.

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

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

With no annotations, the description carries the full load and does meaningfully more than the schema: it warns the operation is irreversible and documents the confirm token as an accidental-deletion guard. It still omits permission/authorization requirements, whether cascade effects occur (docs, members), and what the response returns.

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

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

Front-loaded with the destructive nature and the required token, and the whole description is one tight sentence fragment. The trailing reference pointer (在 references/api/repo_api.md) is mildly distracting but genuinely useful for deeper detail.

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

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

For a 3-parameter destructive tool with no annotations and no output schema, the description supplies the crucial safety and irreversibility context plus the endpoint. Missing authorization prerequisites and side effects on contained docs/members keep it short of complete.

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

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

Schema coverage is 100%, so book_id and confirm are already fully documented in the schema. The description repeats the confirm='DELETE' contract without adding format or edge-case detail beyond it, so baseline 3 applies.

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

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

States a specific verb and resource ('Delete a repo') plus the underlying endpoint (DELETE /repos/:id), which immediately separates it from siblings like yuque_update_repo, yuque_create_repo, and yuque_get_repo. The irreversibility note sharpens the scope further.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a strong precondition ('Requires confirm="DELETE"') but never says when to pick this over alternatives such as soft-deletion via yuque_restore_recycle or the recycle-bin tools, nor when deletion is inappropriate. Usage is implied by the verb rather than explained.

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

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

With no annotations, the description carries the full burden and does well: it discloses irreversibility, the cookie+ctoken auth requirement, and the mandatory confirm token. It omits rate limits, response format, or what happens to nested content, which keeps it below a 5.

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

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

Front-loads the destructive nature and the guard requirement, then gives the endpoint and reference doc. Every clause earns its place with no redundancy.

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

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

For a destructive two-parameter mutation with no annotations and no output schema, the description covers the safety profile, auth needs, and confirmation guard. A pointer to the full API doc covers remaining gaps, though return behavior is not addressed.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, and the schema itself explains the 'DELETE' guard. The description only restates the confirm requirement, adding no new parameter semantics beyond the baseline.

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

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

States a specific verb and resource ('Permanently delete a recycle bin item'), and by using 'permanently delete' it is immediately distinguishable from the sibling yuque_restore_recycle. The API endpoint reinforces the action.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The irreversibility warning plus the required confirm='DELETE' guard signal clearly when this is appropriate, and the sibling name restore_recycle implies the alternative. No explicit when-not/alternative routing sentence, however.

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

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

With no annotations, the description carries the full disclosure burden. 'Computes diff locally' is a genuinely useful behavioral trait (no remote call, implies possible truncation via max_lines), and 'compare and show' implies a read-only operation. However, it says nothing about permissions, error behavior when a version ID is invalid, or how truncation interacts with the diff result.

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

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

Two tight sentences that front-load the core action and output format with no filler. The trailing Chinese reference ('详见 references/api/doc_api.md') is a mixed-language pointer of marginal value to an agent and could have been omitted or translated.

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

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

For a diff tool with no output schema and no annotations, the description does cover the essential return semantics (three diff categories) and the local-computation behavior. It stops short of describing the result structure or how truncation is surfaced, but nothing critical to correct invocation is missing.

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

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

Schema description coverage is 100%, so all four parameters (including max_lines and context_lines) are already documented in the schema. The description adds only the notion of added/removed/unchanged categories, which does not deepen understanding of any specific parameter. Baseline 3 applies.

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

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

States a specific verb and resource ('Compare two document versions') plus the output shape ('line-level diff (added/removed/unchanged)'), which clearly separates it from sibling readers like yuque_get_doc_versions and yuque_get_doc_version_detail. It never names those siblings explicitly, so differentiation is inferable rather than stated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites (e.g. that version IDs come from yuque_get_doc_versions), and no exclusions. The purpose implies the use case but the description leaves the agent to infer the routing entirely.

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

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

No annotations are provided, so the description carries the full behavioral disclosure burden. It implies a read-only URL generation but does not state side effects, authentication requirements, rate limits, or return format, leaving key behavioral traits undocumented.

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

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

The description is two short sentences, front-loaded with the core action, and includes a pointer to extended documentation. Every sentence is purposeful and there is no wasted text.

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

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

For a 7-parameter tool with no annotations and no output schema, the description is minimally adequate. It identifies the operation and references extended documentation, but does not address behavioral context, return shape, or usage conditions that would help an agent invoke it confidently.

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

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 all seven parameters. The description adds only a high-level mention of the url vs doc_id+book_id input forms, which is already captured in the schema, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: generate a Yuque embed reader URL. It also specifies the two input forms (document link or doc_id+book_id), and no sibling tool performs this operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains what the tool generates but gives no guidance on when to use it versus alternatives, nor any prerequisites or exclusions. The reference to an external markdown file does not provide usage guidance within the definition.

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

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

With no annotations, the description carries the full burden, and it does disclose the operational shape: it fetches, converts, adds frontmatter, and writes to local disk, plus that resources are not included. It is silent on consequential behavior such as overwriting an existing file, directory creation, authentication/permission requirements, and error conditions.

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

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

Three short, front-loaded clauses with no filler; the pipeline and the boundary with the resources tool come first. The trailing '详见 references/api/extended_api.md' pointer is low-value for an agent that cannot necessarily open that file, but it costs little.

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

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

For a write-to-disk tool with no annotations and no output schema, the description explains the write target and conversion but omits what the call returns (path? metadata?), overwrite semantics, and permission prerequisites. Adequate but with clear gaps for an agent to call this safely.

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

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

Schema description coverage is 100%, so the schema documents all four parameters, including raw_body's role. The description marginally reinforces raw_body by describing the default body_html→Markdown conversion, but adds no syntax, format, or constraint detail beyond the schema. Baseline 3 is appropriate.

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

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

States a specific verb+resource (export a single document) and immediately enumerates the exact transformation pipeline (fetch doc → body_html to Markdown → frontmatter → write to disk), which no sibling does. It also distinguishes itself from yuque_export_resources and implicitly from yuque_export_repo by scoping to 'a single document.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear division of labor by naming the sibling tool for the adjacent task ('Resource download is separate (yuque_export_resources)'), which helps an agent route correctly. It stops short of explicit when-to-use/when-not guidance, e.g. export-to-disk vs. reading via yuque_get_doc.

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

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

With no annotations, the description carries the full burden. It does disclose meaningful side effects: files are written to disk, images are downloaded, and INDEX.md plus GRAPH.md are generated. It still omits auth requirements, whether output is idempotent/overwrites existing files, and the cost of a bulk download.

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

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

A single dense sentence front-loads scope and output artifacts, followed by a brief reference pointer. Everything earns its place, though the pointer to an external doc slightly shifts detail out of the description.

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

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

For a bulk filesystem-writing operation with no output schema and no annotations, the description explains what is produced but not where files land by default (only the schema covers output_dir) or how failures/partial exports are handled. Adequate but with visible gaps.

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

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

Schema description coverage is 100%, so all four parameters (book_id, raw_body, output_dir, download_images) are already documented in the schema. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

The description names a specific verb (Export), resource scope (all docs in a repo), output format (Markdown files), and structure (TOC dir layout) with generated INDEX.md and GRAPH.md. The 'all docs in a repo' scope clearly separates it from the single-doc sibling yuque_export_doc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The scope ('all docs in a repo') implies when to use it versus single-doc export, but there is no explicit statement of alternatives, prerequisites, or when this heavy bulk operation is inappropriate. Usage is inferable rather than stated.

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

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

With no annotations, the description carries the full burden, and it does disclose useful behavior: it extracts URLs from body_html, writes into <output_dir>/images/ and <output_dir>/attachments/, and returns a URL→local_path mapping. However, it says nothing about overwrite behavior for pre-existing files, handling of unreachable resources, permissions/auth needs, or rate limits.

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

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

Three tight sentences with the primary action front-loaded and no filler. The trailing Chinese reference pointer ('详见 references/api/extended_api.md') is mildly extraneous and not self-contained for a non-Chinese-reading agent, slightly reducing the score.

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

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

For a 3-parameter tool with no output schema, the description is reasonably complete: it explains both the on-disk output locations and the returned mapping, so an agent knows what it gets back. Error handling and overwrite semantics remain uncovered, keeping it short of a 5.

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

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

Schema description coverage is 100%, so all three parameters are already documented, and the description largely restates the output_dir layout that the schema already contains. It adds no new syntax or format detail for id or book_id, so the baseline 3 applies.

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

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

States a specific verb and resource ('Download images/attachments from a document to local directory') and then spells out the mechanism: extract from body_html, download, return a URL→local_path mapping. This is clearly distinguishable from siblings like yuque_export_doc, yuque_export_repo, and yuque_upload_attachment without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The context ('from a document') implies when this tool applies, but there is no explicit when-to-use/when-not guidance and no alternatives named. It never contrasts itself with yuque_export_doc or explains whether it should be paired with a doc export, so usage is left to inference.

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

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

No annotations are provided, so the description must fully disclose behavior. It indicates a read operation via 'Get' and mentions returning JSON DSL and summary stats, but omits permissions, side effects, error handling, and other behavioral traits. The endpoint and reference are useful but insufficient.

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

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

Two concise sentences plus a doc reference; the purpose is front-loaded. The reference to a local file may be opaque but doesn't waste much space.

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

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

For a retrieval tool with no output schema and no annotations, the description should explain what the JSON DSL and summary stats contain, the format, and any prerequisites. It only gives a high-level phrase and a file reference, leaving significant gaps.

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

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

Schema description coverage is 100%, so all three parameters are documented in the schema. The description adds no parameter-level detail, which is acceptable given the schema's completeness, but it doesn't enhance semantic understanding.

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

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

States a specific verb (Get) and resource (board resource JSON DSL and summary stats) scoped to a document, and distinguishes from create/update board siblings. The term 'board' is not defined, and the relation to other document retrieval tools is implied rather than explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use guidance, prerequisites, or alternatives are provided. The agent must infer that this retrieves board data from the required resource_id, but no context is given about when to prefer this over other document retrieval tools.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses the authentication requirement and the GET read-only endpoint, but it omits pagination behavior, rate limits, error handling, and whether all stacks are returned by default.

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

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

The description is compact and front-loaded: it states the resource, scope, authentication prerequisite, and endpoint in sequence without filler. Every clause contributes useful information.

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

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

For a simple parameterless read tool, the description covers the core purpose, scope, authentication requirement, and endpoint. It could be slightly more complete by mentioning pagination or return structure, but no output schema exists that would otherwise carry that burden.

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

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

The input schema has zero parameters, so there are no parameter semantics for the description to add. The baseline for a parameterless tool is 4.

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

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

The description states a specific verb (获取) and resource (当前用户的知识库分组/书架列表), and clarifies the scope includes each stack's knowledge bases. It is clearly distinguishable from sibling mutation tools like yuque_update_book_stack and yuque_sort_book_stack as well as generic list_repos.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is a read/list operation and gives the required authentication (cookie+ctoken), but it does not explicitly say when to use this tool versus alternatives such as yuque_get_user_groups or yuque_list_repos. Usage context is therefore only implied.

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

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

With no annotations, the description carries the full behavioral burden. The GET endpoint implies a read-only operation, which is the only real behavioral signal, but there is nothing about the returned statistics shape, pagination behavior, or the external reference file's contents.

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

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

The description is short and front-loads the purpose, which is good. The trailing Chinese pointer to references/api/statistic_api.md does not convey actionable information to the agent and occupies one of only three fragments.

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

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

For a 7-parameter statistics tool with no annotations and no output schema, the description is too thin: it never explains what statistics are returned or how paging interacts with the filter/sort parameters. The endpoint path is the only supplementary context provided.

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

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

Schema description coverage is 100%, so all seven parameters (name, page, limit, login, range, sortField, sortOrder) are already documented in the schema including defaults and allowed values. The description adds nothing beyond that, so the baseline 3 applies.

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

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

States a specific verb ('Get') and resource ('group repo statistics'), and the endpoint path clarifies it targets book-level statistics within a group. However, 'repo statistics' is loosely distinguished from the sibling yuque_get_group_statistics and yuque_get_doc_statistics; an agent cannot confidently tell which one to pick without guessing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no mention of prerequisites, and no direction to or away from the alternatives such as yuque_get_group_statistics. The pointer to a Markdown file is a documentation location, not usage guidance.

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

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

With no annotations, the description carries the full burden, yet it only discloses that three body formats exist and points to an API reference. It says nothing about authentication/permission needs, whether body content is paginated, or rate limits, so behavioral coverage is partial.

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

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

Three terse fragments, front-loaded with the operation and key return variants. The trailing reference file pointer is a minor overhead but useful, so only slightly less than ideal.

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

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

For a 4-parameter read tool with no annotations and no output schema, the definition covers what is returned at a high level but omits usage context and any behavioral caveats. It is minimally adequate rather than complete.

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

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 id, raw, page, and page_size. The description's 'Supports id or slug' merely restates the id field and adds no syntax or format detail beyond the schema, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('Get document detail') and enumerates the three body representations it can return, which distinguishes it from list/batch siblings. It does not, however, explicitly distinguish itself from yuque_web_get_doc or yuque_batch_get_docs, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus siblings (e.g. batch_get_docs, web_get_doc, get_doc_versions). 'Supports id or slug' is a parameter note, not usage guidance, and no prerequisites or exclusions are given.

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

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

No annotations are provided, so the description carries full behavioral burden. It doesn't state read-only nature, permission requirements, whether the result is paginated (though page/limit params imply it), or what the statistics consist of. The endpoint reference and doc link are the only added context.

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

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

Very compact – one purpose sentence, an endpoint hint, and a doc reference. Front-loaded purpose is fine, though the Chinese doc pointer is opaque to non-Chinese readers and adds little routing value.

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

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

For an 8-parameter, no-output-schema, no-annotation statistics tool with several close siblings, the description is thin. It neither clarifies scope vs the other statistics tools nor hints at the return shape, permissions, or pagination behavior.

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

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

Schema description coverage is 100%, so all 8 parameters are documented in the schema with non-trivial detail (enums for range, sortField, sortOrder values). Description adds no parameter meaning beyond the schema, which is the baseline 3 case 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.

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

States a clear verb+resource ('Get group document statistics') and even names the HTTP endpoint. However, it does not differentiate from close siblings like yuque_get_group_statistics, yuque_get_book_statistics, or yuque_get_member_statistics, leaving the agent to infer scope from the name alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no exclusions, and no mention of the competing statistics tools in the sibling list. The endpoint string hints at group scope but nothing routes the agent between this and the other *_statistics tools.

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

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

With no annotations, the description carries the full burden, and it does disclose that this is a read (GET) returning body, body_html, body_asl and a diff. It omits any permission/scope requirements, rate limits, or behavior when the version ID does not exist, so the disclosure is partial rather than complete.

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

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

Three short fragments with the payload contents front-loaded; nothing is padded. The trailing doc reference is minor filler but not harmful.

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

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

No output schema exists, so the description's field list is genuinely useful in lieu of one. Still missing for a version-detail fetch: how the diff is shaped, whether historical bodies can be large, and any auth requirements, leaving the definition only minimally sufficient.

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

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

Schema description coverage is 100%, so both id and raw are already documented, and the description's mention of 'trimmed fields' only loosely gestures at the raw toggle. Baseline 3 is appropriate when the schema does the parameter-level work.

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

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

States a specific verb and resource ('Get version detail') and enumerates the returned fields (body/body_html/body_asl + diff), so the agent knows exactly what it fetches. It does not, however, distinguish itself from sibling tools like yuque_get_doc_versions or yuque_diff_doc_versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage cue is the endpoint path GET /doc_versions/:id, which implies a version ID is required but says nothing about when to choose this over yuque_get_doc_versions (listing) or yuque_diff_doc_versions (comparing). No prerequisites, no exclusions.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses the 100-version cap and the underlying endpoint, but says nothing about permissions/auth requirements or the return shape. Adequate but incomplete for an annotation-free tool.

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

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

Very tight and front-loaded: purpose, scope, then endpoint and a reference pointer. Every sentence earns its place, though the mixed-language reference pointer is only marginally useful in-line.

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

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

For a no-output-schema list tool with full schema coverage, the description covers purpose, cap, and endpoint adequately; the raw param's trimmed-vs-full behavior is deferred to the schema. Only permissions and returned-field detail are missing, which is minor here.

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

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

Schema description coverage is 100%, so both doc_id and the raw toggle are already documented in the schema. The description adds no parameter meaning beyond restating doc_id in the URL template, so baseline 3 is appropriate.

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

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

States a specific verb+resource — 'List document version history' — and adds the scope 'last 100 published versions'. This is clearer than a bare name restatement, though it does not explicitly differentiate itself from sibling tools like yuque_get_doc_version_detail or yuque_diff_doc_versions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent can infer you call this to enumerate versions, but the description names no alternatives and gives no when-not-to-use guidance (e.g. to inspect one version use get_doc_version_detail, to compare use diff_doc_versions). Minimum viable.

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

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

With no annotations, the description carries the full burden: it usefully discloses the required cookie+ctoken authentication and the underlying GET endpoint, and enumerates the returned data. It still omits rate limits, error behavior, and any scoping caveats.

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

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

Two compact sentences: the outcome list is front-loaded and the auth/endpoint detail is appended. The metric enumeration is dense but each item earns its place by telling the agent what comes back.

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

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

For a parameterless read tool with no output schema, the description is largely sufficient: it names the auth requirement, the endpoint, and the shape of the payload. Only the routing distinction from sibling statistics tools is missing.

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

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

The tool takes zero parameters, so the schema requires no semantic elaboration from the description. Baseline 4 applies.

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

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

States a specific verb (获取) and resource (个人编辑中心全景数据) and enumerates the metrics returned, so an agent knows exactly what it yields. It does not, however, distinguish itself from sibling statistics tools such as yuque_get_member_statistics or yuque_get_group_statistics.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no when-to-use guidance and never names an alternative, leaving the agent to infer that this is the personal-scope counterpart to the group/member statistics siblings. The only contextual hint is the auth requirement.

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

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

No annotations are provided, so the description carries the full behavioral burden, yet it only states the operation. It doesn't disclose permissions required for a group, the shape or scope of the 'summary statistics', rate limits, or what the response contains. The external doc pointer (references/api/statistic_api.md) is a lead, not inline disclosure.

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

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

Two terse sentences plus a reference pointer; the purpose is front-loaded and nothing is padded. The reference to an external markdown file is slightly awkward but not wasteful.

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

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

With no output schema and no annotations, the description should convey what the statistics actually contain and the safety profile of the call. It says only 'summary statistics' and defers to an external file, leaving the agent without inline knowledge of return values or access requirements.

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

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

Single parameter with 100% schema description coverage ('Group login or ID (required)'), so the schema already documents it fully. The description adds nothing beyond echoing the ':login' path segment, so the baseline of 3 applies.

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

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

States a specific verb and resource ('Get group summary statistics'), which is clearer than a bare name restatement. It distinguishes itself from siblings like get_member_statistics and get_book_statistics by scoping to the group level, though it never explicitly contrasts with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus the sibling statistics tools (get_member_statistics, get_book_statistics, get_doc_statistics) or when a group-level summary is preferred over get_user_groups. Usage is only implied by the name.

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

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

No annotations are supplied, so the description carries the full burden. It does disclose a useful behavioral trait (fixed page size of 100) and the endpoint, but says nothing about auth requirements, how pagination beyond the first page works, or what trimmed vs raw output contains.

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

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

Compact, front-loaded single block: purpose, page size, role values, endpoint, then a reference pointer. No filler, though the abbreviation-heavy style and the doc pointer are marginally less readable than plain prose.

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

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

For a 4-parameter read tool with no output schema and no annotations, the description covers the resource, the fixed page size, the role filter encoding, and points to a reference doc for deeper API detail. It omits auth and pagination-total behavior, but is close to sufficient.

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

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The description restates the role mapping and page size but adds no new meaning beyond what the schema provides, matching the baseline 3.

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

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

States a specific verb+resource ('List group members') clearly distinct from mutation siblings like yuque_update_group_user and yuque_delete_group_user. It does not explicitly contrast with yuque_get_user_groups (the reverse direction), so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The purpose implies when to use it (fetching membership of a known group), but there is no explicit when-to-use/when-not guidance or named alternative such as yuque_get_group_statistics or yuque_get_user_groups. Usage is only implied.

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

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

No annotations are provided, so the description carries the full behavioral burden. The GET endpoint implies a read-only operation, but the description says nothing about permissions, pagination limits, default sort behavior, or what the response contains.

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

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

Very short and front-loaded: purpose, endpoint, and a reference pointer. Nothing is padded, though the Chinese reference note ('详见 references/api/statistic_api.md') is cryptic to an agent that cannot resolve the path.

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

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

For a stateless read tool with a 100%-covered schema this is minimally viable, but with no output schema the description could profitably say what statistics are returned or how they are grouped. As written, an agent knows how to call it but not what it gets back.

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

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 all seven parameters (name, page, limit, login, range, sortField, sortOrder) including defaults and enum-like value lists. The description adds no parameter detail beyond this, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get group member statistics') and the underlying endpoint sharpens the scope to member-level stats. The 'member' qualifier implicitly separates it from the sibling yuque_get_group_statistics, though the differentiation is never stated outright.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this versus yuque_get_group_statistics, yuque_get_group_users, or the other statistics tools. Usage must be inferred entirely from the tool name.

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

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

No annotations are provided, so the description carries the full behavioral burden, and it delivers only an HTTP verb and path. It says nothing about authentication requirements, error behavior, whether the note must be accessible/owned, or what the trimmed default response contains. The 'raw' flag behavior is only explained in the schema, not here.

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

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

Three short fragments, front-loaded with the action, which is efficient. However the '详见 references/api/note_api.md' pointer is of little use to an agent and consumes space without adding actionable meaning.

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

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

For a simple two-parameter read tool with full schema coverage this is minimally adequate. Since no output schema exists, the description could have described the trimmed-vs-raw return shape, and it omits any auth or error context.

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

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

Schema description coverage is 100%, with both note_id and raw documented in the schema, so the baseline is 3. The description adds no extra semantic detail beyond the path template.

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

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

States a specific verb+resource ('Get note detail') and the underlying endpoint, which is enough to separate it from yuque_list_notes and yuque_create_note. It stops short of explicitly contrasting with siblings like yuque_get_doc, so it isn't a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of when to prefer an alternative such as yuque_search or yuque_list_notes. The endpoint string is a hint at usage but not real guidance.

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

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

With no annotations, the description carries the burden, but as a read-only GET it is implicitly safe. It does disclose a non-obvious behavior: that toc_yml (a YAML TOC tree) is embedded in the response, and that fields are trimmed unless raw is set. It omits auth requirements and any rate-limit/pagination behavior.

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

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

Compact and front-loaded: the resource, key return fields, HTTP route, and a reference pointer come in a few dense fragments with no filler. The trailing Chinese doc reference is useful rather than wasteful.

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

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

There is no output schema and no annotations, so the description must cover return shape — and it does name the key fields (toc_yml, namespace, items_count, full metadata). It also points at an API reference for deeper detail, leaving only minor gaps like auth requirements.

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

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

Schema description coverage is 100%, so both params (raw, book_id) are already documented in the schema, including the namespace-or-ID format for book_id. The description adds nothing parameter-specific beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Get repo detail') and enumerates the notable returned fields (toc_yml, namespace, items_count, full metadata). It is distinguishable from list_repos/batch_get_repos/update_repo, though it does not explicitly differentiate from yuque_get_toc despite both surfacing TOC data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this versus alternatives such as yuque_get_toc (which also returns TOC data), yuque_list_repos, or yuque_batch_get_repos. Usage is only implied by the 'Get' verb; no exclusions or prerequisites are stated.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the return structure (flat array with uuid/parent_uuid/child_uuid navigation), which is valuable given there is no output schema, but it says nothing about auth requirements, scope, or rate limits.

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

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

Front-loaded in a single tight sentence pair plus an endpoint and a doc pointer. Nothing is wasted, though the external markdown reference adds little for a tool this simple.

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

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

For a simple read-only getter with a fully documented 2-param schema, the description covers purpose and return shape adequately. Absent are usage context and behavioral caveats, which keep it short of a 5.

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

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

Schema description coverage is 100% for both parameters, so the schema already documents book_id and raw. The description adds no parameter-level meaning beyond the schema, making 3 the appropriate baseline.

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

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

States a specific verb+resource ('Get repo TOC tree') and clarifies the return shape is a flat array navigable via uuid/parent_uuid/child_uuid, with the underlying endpoint. This is well beyond a restatement of the name, though it does not explicitly contrast itself with the sibling yuque_web_get_toc.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to call this versus alternatives (e.g., yuque_web_get_toc, yuque_update_toc, yuque_batch_update_toc) and no stated prerequisites. The agent must infer usage from the name alone.

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

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

No annotations are provided, so the description carries the full burden. It discloses the HTTP method (GET /user), implying a read-only operation, and lists returned fields, but it does not cover authentication requirements, rate limits, error behavior, or the exact effect of the raw flag beyond what the schema already states.

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

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

Front-loaded with the purpose, then the returned fields, endpoint, and a reference pointer. Two compact sentences with no wasted text.

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

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

With no output schema and no annotations, the description helpfully names the returned profile fields and points to an API reference. It is nearly complete for a simple current-user read, though it could state authentication expectations or clarify the raw flag's output shape in prose.

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

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

Schema description coverage is 100%, so the schema already explains the raw parameter. The description does not add input-parameter semantics beyond the schema, though it does list return fields, which is useful return-value context rather than parameter context.

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

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

States a specific verb and resource: get the current user profile, and lists the returned fields. It is easily distinguishable from sibling tools such as get_user_groups because it targets the authenticated user rather than group membership.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no explicit when-to-use guidance or alternatives. The agent can infer this is for the current user, but there is no statement about when to prefer this over related user/group tools.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only gives the HTTP method and endpoint, implying a read operation, but does not state authentication requirements, whether results are paginated, or any other behavioral traits beyond what the schema already implies.

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

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

The description is three short lines with zero waste. The core purpose is front-loaded, followed by the endpoint and a reference pointer, making it efficient and well-structured.

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

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

For a simple read-only list operation with a fully documented schema and no output schema, the description provides adequate core information and points to a reference document. However, it lacks any usage context or behavioral notes that would help an agent select it over siblings, leaving it only minimally complete.

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

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

Schema description coverage is 100%, so all four parameters are already documented in the input schema. The description adds no parameter-level details beyond the schema, which is the baseline expectation when the schema is complete.

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

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

The description states a specific verb ('List') and resource ('groups the user belongs to'), making the purpose clear. It does not explicitly differentiate from sibling tools like yuque_get_user or yuque_get_group_users, but the tool name and description together are unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives. It does not mention prerequisites, appropriate contexts, or exclusions, leaving the agent to infer usage from the name alone.

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

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

No annotations are provided, so the description carries the burden. It discloses the endpoint and that this is a health/token check, which implies a safe read with no mutation, but it does not state what the response indicates (valid/invalid, error shape) or any rate-limit/auth caveats beyond token validity.

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

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

Front-loaded one-liner that leads with the purpose, plus a short endpoint note. The '详见 references/api/user_api.md' pointer is minor and arguably useful, but slightly dilutes an otherwise tight statement.

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

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

For a zero-parameter, no-output-schema health check, the description covers purpose, semantics, and the underlying endpoint. The only gap is what a caller should expect back from a failing vs. passing check.

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

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

The tool takes zero parameters, so per the baseline this scores 4; there is nothing for the description to clarify beyond the empty input schema.

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

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

States a specific verb+resource: 'Health check — verify Yuque API token validity', with the underlying endpoint GET /hello given as supporting detail. Its purpose is unambiguous and distinct from the data-oriented siblings like yuque_get_user or yuque_search, though it does not explicitly contrast itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'verify Yuque API token validity' implies usage (call to check credentials before/while troubleshooting), but there is no explicit when-to-use, when-not-to-use, or alternative guidance. For a unique-purpose health-check tool, implicit context is roughly adequate.

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

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

No annotations are provided, so the description carries the full behavioral burden. It never states that this is a mutating/write operation, whether an existing doc with the same slug is overwritten or a new one created, permission requirements, or asset-upload side effects. A bare pointer to a reference file does not disclose these traits inline.

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

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

Two short sentences, front-loaded with the core action before the mode enumeration. The Chinese reference pointer ('详见 references/api/extended_api.md') is terse but assumes the reader resolves it, slightly undercutting self-contained concision.

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

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

For a 7-parameter write tool with no annotations and no output schema, this is thin. The distinction between upload_assets and embed_assets (a real behavioral difference affecting where assets live) is left entirely to an external file, so an agent cannot confidently pick a mode or predict side effects from the definition alone.

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

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 all 7 parameters, including mode, format, slug, and paths. The description repeats the mode values but adds no syntax, defaults, or constraints beyond what the schema provides; baseline 3 applies.

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

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

States a specific verb and resource: 'Import a local Markdown/HTML file into Yuque.' This clearly separates it from the sibling yuque_import_url, which handles remote URLs. The three modes are named but not explained, so the purpose is clear while mode selection remains opaque.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus yuque_import_url, yuque_upload_attachment, or yuque_create_doc. Listing '3 modes: direct / upload_assets / embed_assets' names options without saying which conditions select each one, leaving the agent to guess.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the internal pipeline (fetch page, extract readable content, create doc), which is meaningful behavioral context, but omits permissions/auth needs, whether the doc is draft or published, duplicate handling, and error behavior for unfetchable pages.

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

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

Purpose is front-loaded in the first sentence and the pipeline follows compactly. The trailing Chinese reference '详见 references/api/extended_api.md' is cryptic and points to an external file rather than adding inline value, which slightly weakens an otherwise tight definition.

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

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

For a 5-parameter mutation tool with no annotations and no output schema, the description is thin: it defers detail to an external markdown reference instead of stating auth requirements, result shape, or failure modes. Too much must be inferred before a correct call.

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

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

Schema description coverage is 100%, so all five parameters (url, paths, title, format, book_id) are already documented in the schema. The description adds no syntax, format, or constraint detail beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource (import content from a web URL into Yuque) and follows with the processing pipeline (fetches page, extracts readable content, creates doc). This is clearly distinguishable from yuque_import_file (file-based) and yuque_create_doc (blank creation), though it doesn't name those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance, and no routing to alternatives like yuque_embed_url or yuque_import_file. The agent must infer from the name alone that this is the URL-import path versus file import or embedding.

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

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

No annotations are provided, so the description carries the burden. It discloses the HTTP verb/path, the sort order, and a cap of 100 items, which is genuine behavioral context, but it says nothing about whether the repository must be accessible, whether the call is read-only and non-destructive (implied by 'List' but not stated), or how trimmed vs raw output behaves.

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

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

Compact and front-loaded: operation, sort, constraint, endpoint, then a pointer to further docs. Nothing is redundant, though the terse '/repos/:id/docs' and Chinese-language reference are slightly opaque to an English-reading agent.

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

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

For a read-only list tool with no annotations and no output schema, the description covers the essentials (scope, sort, cap) but omits return-shape hints, pagination interplay between offset and limit, and differentiation from sibling list tools. Adequate but with clear gaps.

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

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

Schema description coverage is 100%, so the baseline is 3; every parameter (raw, limit, offset, book_id, optional_properties) is already documented in the schema. The description's only parameter note, 'limit ≤ 100', merely repeats the schema's 'max 100'.

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

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

States a specific verb (List) and resource (documents in a repo) plus the sort order (updated_at desc), so the operation is unambiguous. It does not differentiate from near-duplicate siblings such as yuque_web_list_docs or yuque_batch_get_docs, which prevents a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no mention of alternatives, despite several sibling list tools (yuque_web_list_docs, yuque_batch_get_docs, yuque_list_notes) that an agent could confuse it with. The endpoint path and reference file are provided but not a selection criterion.

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

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

With no annotations, the description carries the full behavioral burden. 'GET /notes' implies a read-only operation and scoping to the current user, which is useful. However, it does not disclose permissions, pagination behavior, or what happens with the status filter beyond what the schema states.

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

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

The description is very short and front-loads the core action before the endpoint. The final reference to an external Chinese documentation path is somewhat opaque, but the overall structure remains efficient and free of filler.

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

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

For a simple list tool with 100% schema coverage and no output schema, the description is minimally sufficient to invoke it. It still lacks usage context, authentication requirements, and any behavioral notes beyond the HTTP method, leaving gaps that an agent might need to infer.

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

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

Schema description coverage is 100%, so all three parameters (page, limit, status) are already documented in the schema. The description adds no parameter meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description states a specific verb and resource: 'List current user's notes.' This is clearly different from sibling tools that list docs or search content. However, it does not explicitly contrast with alternatives like yuque_list_docs or yuque_search, so it falls short of full sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives. It does not mention scenarios, prerequisites, or exclusions. The implied usage is merely 'if you want to list notes,' which is too thin for a 5-point usage dimension.

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

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

No annotations are provided, so the description carries the full burden. It discloses the auth requirement and HTTP route, which is genuine behavioral context, but says nothing about pagination behavior, rate limits, or what fields come back in a recycle item.

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

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

Three short clauses, front-loaded with the purpose, then auth, then endpoint. The Chinese reference pointer is compact and potentially useful, though it assumes the reader can locate that file.

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

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

For a 3-parameter listing tool with no output schema and no annotations, the description covers purpose, auth, and route but omits return-shape expectations and pagination semantics. Adequate but with clear gaps an agent would want filled.

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

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

Schema description coverage is 100%, so limit, offset, and target_type are already documented in the schema. The description adds no syntax or constraint detail beyond that, making the baseline 3 appropriate.

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

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

States a specific verb and resource ('List recycle bin items') with an unambiguous name matching the operation. It does not explicitly differentiate from sibling restore_recycle/destroy_recycle, but the read-only listing intent is clear from the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives an authentication prerequisite ('requires cookie+ctoken') and the underlying endpoint, which implies when it can be called. It does not say when to prefer this over other listing tools or how it relates to restore/destroy operations on the same recycle items.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. Listing the HTTP endpoint implies a safe read, but it says nothing about pagination semantics, default page size, auth requirements, or what trimmed vs raw output means.

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

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

Two short clauses and a reference pointer — front-loaded and free of filler. The Chinese-language reference to an external markdown file is somewhat cryptic but doesn't bloat the text.

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

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

For a six-parameter list tool with no annotations and no output schema, the description is thin. It omits pagination behavior, the meaning of the raw flag, and routing against siblings, leaving real gaps for the agent.

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

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 all six parameters, including limit, offset, type filter, and raw. The description adds nothing beyond what the schema provides, which is the baseline 3 case.

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

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

States a specific verb+resource ('List repos for a user or group'), which is clear and tells the agent what it retrieves. However, it doesn't differentiate itself from close siblings like yuque_web_list_repos or yuque_batch_get_repos, so the agent can't tell which to pick from the description alone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives. With siblings yuque_web_list_repos and yuque_batch_get_repos present, the absence of any routing guidance is a real gap.

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

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

With no annotations, the description carries the full burden. It does disclose real behavioral traits: concurrent multi-path execution, deduplication by doc_id, and fetching full content of top-N docs, which is useful beyond a bare search label. However it says nothing about permissions, rate limits, or what happens on empty results.

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

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

Single dense sentence that front-loads the pipeline stages, with no filler. The trailing external-file reference is mildly unhelpful since the agent cannot read it inline, but the sentence itself is tight.

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

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

No output schema and no annotations, so the description is the only behavioral source, yet it omits the return shape (does it return full doc bodies or just snippets when fetch_docs is low?) and any usage routing against sibling search tools. Adequate for the mechanics, incomplete for decision-making.

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

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

Schema description coverage is 100%, so all five parameters are documented in the schema itself, giving a baseline of 3. The description adds only the LLM-generated keywords idea, which the schema already conveys; scope, creator, fetch_docs, and max_results get no extra meaning.

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

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

States a specific verb+resource ('RAG-enhanced search') and enumerates the pipeline: concurrent multi-path searches, dedup by doc_id, fetch top-N full doc content. It is clear what the tool does, but it never contrasts itself with the sibling yuque_search or yuque_web_search, leaving an agent to guess which search to pick.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use guidance at all — no condition distinguishing it from yuque_search, yuque_web_search, or yuque_list_docs. The only pointer is an external file reference ('详见 references/api/search_api.md'), which is not guidance an agent can act on inline.

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

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

With no annotations, the description must carry the full behavioral burden. It usefully discloses the auth requirement (cookie+ctoken) and the underlying endpoint, but says nothing about success/failure semantics, whether a restore is reversible, or behavior when the item no longer exists.

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

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

Very short and front-loaded: action first, then auth prerequisite, then endpoint and a doc pointer. Every element is brief, though the endpoint path and reference pointer are marginally redundant.

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

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

For a single-parameter mutation with no output schema, the description covers the essentials (action, auth, endpoint) but omits error conditions and response expectations, leaving a modest gap.

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

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

Schema description coverage is 100% and only one parameter (recycle_id) exists, so the schema already fully documents it. The description adds no syntax or format detail beyond the schema, making the baseline 3 correct.

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

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

States a specific verb (restore) and resource (item from recycle bin), which cleanly separates it from the sibling yuque_destroy_recycle. It does not explicitly name the alternative tool, but the action is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the tool itself (restore a deleted item), and the cookie+ctoken prerequisite gives some context. However, there is no explicit when-to-use guidance or explicit routing against yuque_list_recycles / yuque_destroy_recycle.

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

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

No annotations are provided, so the description carries the full load. It mentions the HTTP GET method, implying a safe read, but omits any details about authentication, rate limits, pagination behavior, or result format. For a search tool with no annotations, this is insufficient.

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

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

The description is very concise and front-loads the purpose. The endpoint template and the reference to an external file add minor value but are compact and do not bloat the text. A slight deduction for the potentially unhelpful external reference.

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

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

With no annotations and no output schema, the description should compensate by explaining when to use this tool and what to expect from the search. It lacks usage differentiation from sibling search tools and omits any return behavior or pagination context, leaving significant gaps for an agent.

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

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 all five parameters thoroughly. The description repeats only q and type in an endpoint template and adds no meaning beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a specific verb (search) and resource (Yuque docs and repos), which is clear. However, it does not differentiate itself from sibling search tools like yuque_rag_search or yuque_web_search, so an agent cannot tell them apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to use this tool versus alternatives such as yuque_rag_search, yuque_web_search, or yuque_list_docs. There are no exclusions or context cues beyond the word 'General'.

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

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

With no annotations, the description carries the full behavioral burden and does well: it discloses required authentication (cookie+ctoken), the HTTP endpoint (PUT /api/mine/book_stack/move), and that the array order itself determines the final ordering. It stops short of covering failure modes, atomicity, or rate limits, so it is not exhaustive.

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

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

The description is three compact sentences, front-loads the purpose and authentication requirement, and includes endpoint and parameter semantics without any filler. Every sentence earns its place.

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

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

For a two-parameter mutation tool with no output schema and no annotations, the description provides enough to call it correctly: purpose, auth, endpoint, and the key array-order rule. It leaves out error behavior and return expectations, which keeps it from being fully comprehensive.

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

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 both parameters. The description adds slightly more by stating '数组顺序即最终排序', but the schema's own description ('按期望顺序排列') already conveys the same idea. Baseline 3 is correct 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.

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

The description states a specific verb (排序/sort) and resource (分组/书架内知识库顺序), making the operation unmistakable. It does not explicitly differentiate from the sibling yuque_update_book_stack, so it falls just short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase '常用于把分组内知识库按期望顺序重排' implies a typical use case, but there is no explicit when-to-use guidance, no prerequisites beyond authentication, and no named alternatives. Usage is inferable but not fully specified.

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

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

With no annotations provided, the description must carry the full behavioral burden. It discloses the HTTP method (PUT) and the text/dsl mutual exclusivity, but omits authentication requirements, rate limits, side effects, reversibility, and whether the update is partial or full replacement. The external reference file is not a substitute for inline behavioral context.

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

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

The description is short and front-loaded with the core action. It includes an endpoint and a reference note, which are useful but the Chinese reference may be less accessible to some agents. Overall it is efficient and not padded.

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

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

Given this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks usage context, authentication requirements, expected return behavior, and error conditions. The presence of a reference file does not compensate for missing inline guidance that an agent needs to invoke the tool correctly.

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

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 all five parameters in detail. The description reinforces the text/dsl mutual exclusivity but adds no new syntax, format, or constraint information beyond what the schema provides. A 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.

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

The description states a specific verb and resource: 'Update a board resource'. It also gives the HTTP method and endpoint (PUT /yfm/boards), making the operation clear. However, it does not explicitly distinguish itself from sibling tools like yuque_create_board or yuque_get_board beyond the word 'update'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The only usage guidance is 'text or dsl, choose one', which is a parameter constraint rather than when-to-use guidance. There is no mention of alternatives, prerequisites, or conditions under which this tool should be chosen over yuque_create_board or yuque_update_doc.

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

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

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses required authentication (cookie+ctoken) and the HTTP endpoint (PUT /api/mine/book_stack/move), but omits mutation side effects, reversibility, error behavior, and what happens to existing associations.

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

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

A compact single paragraph that front-loads the action, then adds authentication, endpoint, and a common usage scenario. Each sentence contributes useful information with no redundancy, though it could be slightly tighter.

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

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

For a mutation tool with no annotations and no output schema, the description covers purpose, auth, and endpoint but leaves gaps around side effects, success/failure responses, and whether the move is reversible. It is adequate but not fully complete for safe invocation.

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

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

Schema description coverage is 100% and both required parameters (book_id, stack_id) are documented in the schema. The description mentions the concepts of knowledge base and target group but adds no formatting, constraints, or meaning beyond what the schema already provides, so baseline 3 applies.

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

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

States a specific verb (移动) and resource (知识库到指定分组/书架), and the action is clearly distinct from sibling reads (get_book_stacks) and sorts (sort_book_stack). However, it does not explicitly name or compare against those siblings, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives a clear typical use case: moving a knowledge base from one group (e.g., pre-discard) to another (e.g., discard). This provides context for when to use it, but there are no explicit exclusions or direct comparisons to alternative tools, so it lacks the alternative guidance needed for a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It discloses the underlying endpoint (PUT /repos/:id/docs/:id) and points at references/api/doc_api.md, but says nothing about whether omitted fields are preserved or cleared, whether the update is reversible, or what authorization is required.

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

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

Three short fragments: action+fields first, endpoint second, reference pointer third. Front-loaded and waste-free, though the truncated fragment style makes it slightly cryptic rather than polished.

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

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

For an 8-parameter mutation tool with no annotations and no output schema, the description is thin: it omits partial-update semantics, the effect of the 'raw' flag, and error/permission behavior. The external doc reference is a weak substitute for in-definition guidance.

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

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

Schema description coverage is 100%, so both required IDs and all optional fields are already documented in the schema. The description restates the updatable field list without adding format, enum, or default semantics beyond what the schema provides (e.g. the public 0/1/2 mapping already lives in the schema).

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

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

States a specific verb (Update) plus the resource (a document) and enumerates the mutable fields (title/body/slug/format/public), which clearly separates it from create_doc, get_doc and delete_doc. It stops short of naming siblings explicitly, but the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description never says when to use this tool versus alternatives such as yuque_create_doc, yuque_copy_doc, or yuque_web_delete_doc, nor does it mention prerequisites (permissions on the repo, whether the doc must exist). Usage is only implied by the verb 'Update'.

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

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

No annotations are provided, so the description carries the full burden. It reveals only that this is a PUT (a mutation) and lists role values; it does not disclose permission requirements, whether the change is reversible, or any rate/side-effect behavior.

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

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

Very compact and front-loaded with the action and role values. The trailing reference-file pointer ('详见 references/api/group_api.md') is a slightly opaque addition but is functional rather than wasteful.

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

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

For a mutation tool with no annotations and no output schema, the description is minimally adequate: it covers the action, endpoint, and role semantics. It omits any auth/permission context or behavioral side effects that would make it fully self-contained.

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

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

Schema coverage is 100%, so the schema already documents all four parameters. The description restates the role enum (0=admin,1=member,2=readonly), which duplicates the schema's role description rather than adding new meaning. Baseline 3 applies.

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

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

States a specific verb and resource ('Change a group member role') and identifies the underlying endpoint, which lets an agent distinguish it from siblings like yuque_delete_group_user or yuque_get_group_users. It is clear, though it doesn't explicitly differentiate itself from those siblings in prose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as yuque_delete_group_user or yuque_get_group_users, and no stated preconditions (e.g., admin privileges). The reader must infer usage from the name alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It correctly discloses the destructive deletion safety guard (confirm='DELETE') and the HTTP endpoint, which is valuable. It omits whether deletion is reversible/restorable, permission requirements, and the update-vs-delete side effects, leaving meaningful gaps for a mutation tool.

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

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

Front-loads the warning about deletion and the confirm requirement, then the endpoint. It is compact and every sentence earns its place, with only the Chinese reference pointer adding minor noise.

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

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

For a mutation-with-delete tool that has no annotations and no output schema, the description covers the safety guard and endpoint but leaves the update semantics (which fields, restore possibility) and reversibility unstated. Adequate but not complete.

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

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

Schema coverage is 100%, so all five parameters (including body, status, confirm, raw, note_id) are already documented in the schema, establishing the baseline of 3. The description's status=9=delete note merely restates what the schema already says.

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

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

States specific verbs (update/delete) and the resource (note), and the endpoint PUT /notes/:id pins down the operation. It distinguishes itself reasonably from yuque_get_note and yuque_create_note, though the dual update/delete purpose in one tool is slightly conflated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides one key usage condition (deleting via status=9 requires confirm='DELETE'), which is genuinely useful to select the delete path. However, it offers no guidance on when to use this tool versus yuque_create_note or yuque_get_note, and no exclusions or prerequisites beyond the confirm token.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It says this is a PUT update and names four fields, but it does not explain side effects, whether omitted fields are preserved, authentication requirements, or what happens to related data like TOC when toc is passed. The external reference is a pointer, not usable behavioral context.

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

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

The description is very short and front-loads the core action: update repo metadata. The endpoint and documentation pointer are included without wasted words. It is slightly cryptic due to the mixed Chinese reference and terse fragments, but structurally efficient.

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

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

For a mutation tool with 7 parameters, no annotations, and no output schema, the description is too sparse. It does not mention the required book_id, does not explain toc/raw behavior, and does not clarify partial versus full update semantics. It leaves important invocation context to the schema and an external doc.

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

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 all 7 parameters, including book_id and raw. The description lists only name/description/slug/public and adds no syntax or format details beyond that partial enumeration. Baseline 3 is appropriate because the schema does the heavy lifting.

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

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

The description states a specific verb+resource: 'Update repo name/description/slug/public.' It distinguishes this tool from repo creation, deletion, and retrieval siblings. However, it omits updateable fields such as toc/raw and the required book_id, so it is clear but not fully precise.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use or when-not-to-use guidance. It does not name alternatives like yuque_update_toc or yuque_update_doc, nor does it state prerequisites such as required permissions or the required book_id. The intended usage is only implied by the tool name and listed fields.

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

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

With no annotations, the description carries the full burden. It usefully discloses the critical destructive-op guard ('Deleting requires confirm=DELETE'), which is the most important behavioral trait for a mutation tool. However, it omits auth/permission requirements, whether the update replaces the whole TOC or is incremental, and any response behavior.

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

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

Three compact clauses, front-loaded with purpose, then the safety-critical warning, then the endpoint and reference pointer. Every element earns its place with no filler.

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

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

For a 12-parameter mutation tool with no annotations and no output schema, the description is thin. It covers the delete guard and the action set, but leaves the semantics of moves (node_uuid vs target_uuid), permission needs, and return behavior to the schema alone.

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

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 all 12 parameters. The description only restates the confirm='DELETE' rule that the schema itself explains, adding no new syntax or format detail beyond the structured fields. Baseline 3 applies.

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

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

States a specific verb+resource ('Update repo TOC') and enumerates the sub-operations it performs (create/move/edit/delete nodes). This is clear enough to distinguish it from read-only siblings like yuque_get_toc, though it does not explicitly call out yuque_batch_update_toc, the closest sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit when-to-use guidance or reference to alternatives. The parenthetical action list hints at scope, but nothing tells the agent when to prefer this over yuque_batch_update_toc or the web catalog-move tools.

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

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

No annotations are provided, so the description carries the burden. It discloses size limits (image≤50MB, attachment/video≤2GB) and auth prerequisites (cookie+ctoken), which are useful behavioral details. However, it doesn't mention what happens on failure, rate limits, or return values.

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

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

Very concise: a single sentence with key facts (limits, auth, endpoint, reference). Front-loaded with the core action. The reference pointer is useful but could be more integrated.

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

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

Given no annotations and no output schema, the description covers essential constraints and auth, but lacks details on return values, error handling, or how the uploaded file is used downstream. Adequate but with room for more behavioral context.

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

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 all three parameters fully. The description adds only a size constraint for the 'type' parameter, which is marginally useful but not necessary since the schema lists enums. Baseline 3 is appropriate.

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

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

States a specific verb+resource: 'Upload a file to Yuque CDN'. It also names the endpoint 'POST /upload/attach' and points to a reference doc. The purpose distinguishes it from siblings like yuque_import_file or yuque_embed_url.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes constraints (size limits, auth requirements) which imply when it can be used, but does not explicitly say when to use this tool versus alternatives like yuque_import_file or yuque_embed_url. The usage context is implied rather than spelled out.

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