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

Annotations already cover the write and destructive nature (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the bar is lower. The description adds genuinely useful behavioral context beyond those flags: atomicity ('全有或全无' all-or-nothing) and the server-enforced base_version semantics with auto-read when omitted. This tells the agent how the operation behaves at execution time. It stops short of describing rollback/error behavior or the consequences of the destructive ops, but it meaningfully supplements the annotations.

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 dense sentences with the most important facts front-loaded: transaction scope and atomicity come first, followed by the op array shape, then the base_version behavior. There is no filler or repetition of schema fields. It is slightly compressed in a way that assumes familiarity (e.g., the '...' in the op shape), but every clause 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?

An output schema exists and annotations cover the safety profile, so return values and destructive/write hints are handled. The notable gap is the operation payload structure: the description's '{op: insert|replace|delete, ...}' plus the schema's additionalProperties-{} items leaves the actual mutation fields (e.g., where to insert, what replacement content is, which path is targeted) undocumented. For a destructive batch tool this is a significant omission. Sibling routing guidance is also absent. 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%, setting the baseline at 3. The description adds real value beyond the schema: it specifies the operation item shape ({op: insert|replace|delete, ...}) which the schema's generic items object with additionalProperties:{} leaves entirely open, and it clarifies base_version as server-required-but-auto-read, going beyond the schema's 'Document version read before the protected write'. The idempotency_key already has a schema description, and the description adds nothing further there, which is acceptable.

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: 批量编辑 (batch edit) targeting a doco document, scoped to 1–100 operations with explicit op types (insert|replace|delete) and all-or-nothing transaction semantics. This is clear and actionable, but it does not explicitly differentiate from sibling tools such as doco_update_document or the block-level edit tools, relying on the 'batch' framing and the tool name itself to signal 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?

Usage context is implied rather than stated: the 'single transaction / all-or-nothing' and '1–100 operations' framing signals this is for atomic multi-operation edits, which is a meaningful cue. However, there is no explicit when-to-use vs when-not-to-use guidance, no named alternatives (e.g., doco_update_document for a single edit, doco_patch_block/doco_insert_blocks/doco_delete_block for finer-grained operations), and no mention of prerequisites such as document existence or permissions.

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?

Annotations already cover readOnly, idempotent, and non-destructive. The description adds meaningful context by explaining the two-phase behavior (manifest+cursor first, then added/removed/modified/moved) and the sync_required flag's implication, which is valuable beyond the annotations. It doesn't describe error or rate-limit behavior, but the core incremental pattern is well disclosed.

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 sentences, both information-dense and front-loaded. The first sentence explains the core concept (watermark establishment and incremental reads) with a clear mode split. The second sentence encodes the critical behavioral rule. No filler or repetition.

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 an output schema exists and annotations cover safety, the description sufficiently explains the tool's stateful behavior and how to use it correctly. The only minor gap is that it doesn't explicitly define what happens if 'after' is missing on a second call, but the phrase '首次不传' implies the convention clearly.

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 parameters. The description adds usage-level meaning (first call omits after, subsequent calls use cursor) that complements the schema's generic 'opaque cursor' description. However, it doesn't add detail beyond what a careful agent could infer from the schema plus 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?

The description clearly states the tool establishes or incrementally reads block-level change watermarks for documents. It distinguishes the two modes (initial manifest/cursor vs. subsequent cursor-based diff) and references sibling tools by indicating a re-read of content is required when sync_required=true, which differentiates it from doco_read or doco_get_blocks.

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 explicitly tells when to omit 'after' (first call) and when to pass 'cursor' (subsequent calls). It also provides a critical conditional: if sync_required=true, the agent must re-read the document body and establish a new baseline, which is a clear instruction on what to do next rather than just what the tool does.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, and the description aligns with those. It adds extra value by warning that candidates are strictly separated from explicit concepts, which prevents an agent from expecting candidates in list/get results. No contradiction with annotations 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?

A single, compact sentence front-loads the tool's purpose and uses a colon-structured list to enumerate supported operations. Every clause earns its place; there is no repetition or 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?

Given 10 parameters, 4 actions, and a large sibling set, the description covers the broad scope and the output schema handles return values, but it omits pagination behavior and relationship-direction parameters, and it does not help an agent decide between this and sibling tools like doco_traverse. It is sufficient for a basic invocation but not a complete selection guide.

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?

With schema coverage at 100%, the baseline is 3. The description goes beyond the schema by semantically grouping the actions: list/get are for explicit concepts, candidates is a separate operation, and traverse follows concept relationships. This clarification directly affects how action, status, and min_confidence should be used, adding meaning that the schema's generic descriptions do not provide.

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 clear purpose: a unified read layer for concepts, listing operations (list, get, traverse, candidates) on a specific resource. It distinguishes concepts from generic search/traversal tools by adding the notion of strict separation, but it does not explicitly contrast itself with sibling doco_traverse, so it stops 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 wording implies this is the unified read access point for the concept layer and that candidates must be listed via the candidates action rather than list/get. However, it gives no explicit 'use this instead of X' guidance, and with siblings like doco_traverse, doco_search, and doco_edit_concepts available, an agent is left to infer when this tool is the right choice.

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?

Annotations already mark the tool as not read-only, not idempotent, and not destructive; the description adds useful behavioral context by specifying the accepted content formats (markdown, tiptap-json, html) and the two supported payload shapes (content or document). It does not contradict annotations.

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 entire guidance is one compact, front-loaded sentence: primary purpose first, then the optional content detail. No filler or repetition of schema fields.

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 an output schema, 100% parameter coverage, and annotations, the description is largely complete. It could be slightly stronger by hinting that folder_id/knowledge_base_id scope the creation and that idempotency_key prevents duplicate retries, but those are already visible in the schema.

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 goes beyond the schema by explaining the nested content object's format enum and alternative inner fields, which the schema leaves as a generic additionalProperties object.

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 gives a specific verb and resource ('新建文档' / create a new document) and adds the valuable capability of injecting initial content with supported formats. It is not a tautology, and the create action clearly separates it from update/get siblings, though it does not explicitly name an alternative.

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 intended use is implied: use this tool when a new document must be created, optionally with initial body content. However, it provides no explicit when/when-not guidance or alternatives such as doco_update_document for existing documents, so an agent must infer routing.

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?

Beyond the annotations (which only mark readOnly/idempotent/destructive as false), the description reveals that relations are auditable, that the server validates both ends' permissions and existence prior to creation, and implicitly signals non-idempotency by referencing an idempotency_key. This adds meaningful behavioral context without contradicting annotations.

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 entire description is a single, front-loaded sentence that states purpose, target URI format, and server-side checks. No filler; every clause contributes.

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 creation tool with six parameters and an output schema, the description covers the purpose, the critical URI format, and validation behavior. Combined with full schema coverage and an output schema, the agent has enough to call it correctly; remaining details like return values are presumably handled by the output schema.

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?

All six parameters have schema descriptions, so the baseline is 3. The description adds crucial semantics for target_uri by specifying the exact doco://doc/{id}#block={block_id} format, which is absent from the schema property description, and it frames source_document_id/source_block_id as a stable source block.

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 pair: creates an explicit, auditable typed relation from a stable source block. The resource is specific enough to distinguish it from the many read/update/document sibling tools, and no sibling appears to create relations.

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 provides some context by specifying the target_uri format and explaining that the server validates permissions and block existence before creation. However, it does not explicitly state when to use this tool over alternatives or exclude any sibling, so usage guidance is mostly implied by the tool's purpose.

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?

Annotations already declare destructiveHint=true and readOnlyHint=false, so the basic safety profile is known. The description adds no behavioral context such as permanence, cascading deletion of child blocks, versioning implications, or whether base_version is required for safe deletion. It is not contradictory, but it provides zero value beyond the annotations.

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 extremely short and front-loaded, with no wasted words. It is structurally efficient, though it is so terse that it leaves important behavioral and usage context for other dimensions to cover.

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 that this is a destructive mutation tool, the description should provide some context about consequences or intended use cases. Annotations and schema cover safety and parameters, but the description itself is incomplete for an agent deciding whether deletion is appropriate or what side effects may occur.

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 optional base_version. The description adds no parameter-level meaning, 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 '删除单个块' clearly states a specific action (delete) on a specific resource (a single block), so the core purpose is understandable. However, it does not explicitly differentiate this tool from sibling block operations like doco_patch_block or doco_insert_blocks beyond the verb itself.

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 about when to use this tool versus alternatives. The sibling list contains related block-level operations, but the description provides no context, conditions, or exclusions to help the agent decide which tool fits.

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?

Annotations already mark the operation as destructive and not read-only. The description adds valuable behavior beyond annotations: automatic ETag reading, If-Match header sending, and idempotency-key generation for each write. These details alert the agent to optimistic concurrency and retry expectations. There is no contradiction with idempotentHint=false because generating a key does not assert tool-level idempotency.

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 one dense, front-loaded sentence listing all operation types, followed by one sentence of critical client behavior. Every clause carries information and there is no padding or repetition.

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 13-parameter, 7-action destructive write tool, the description provides the high-level operation map and concurrency/idempotency behavior, while the output schema, annotations, and per-parameter schema descriptions cover the rest. The main remaining gap is explicit action-to-parameter guidance, but the schema field names and descriptions are sufficiently suggestive for an agent to fill it.

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, but the description goes beyond the enum names by explaining the semantic groups: create, update, source/relation addition, merge, and candidate accept/reject. It still does not map each action to the specific required parameters (e.g., merge needs target_concept_id), but the schema parameter names partially cover that.

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 ('unified write') and a specific resource ('explicit concepts'), then enumerates the exact operation categories: create, update, add sources/relations, merge, and accept/reject candidates. This clearly identifies the tool as the concept-mutation entry point and differentiates it from read/search/translation siblings such as doco_get_tree or doco_search.

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 word 'unified' implies this is the intended single entry point for explicit concept writes, and the action list implies the supported cases. However, the description never says when to prefer this over overlapping siblings like doco_create_relation or doco_batch_edit, nor does it mention any exclusion conditions.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is clear. The description adds useful context about stable block_id and version, which is helpful. It doesn't disclose pagination, ordering, or whether full content is included, but for a read-only tool with annotations, this is acceptable but not rich.

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 a single, dense line that front-loads the core behavior and the key parameter (recursive). No wasted words; the Chinese phrasing is compact and clear.

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 block-reading tool with an output schema and strong annotations, the description covers the core behavior and the toggle. It could mention whether it's suitable for large documents or whether blocks include content text, but the output schema likely covers return values. It's structurally complete and adequate for the agent to select and invoke the tool.

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 (recursive and document_id) are already documented in the schema. The description adds the concept of top-level versus all blocks, which maps to the recursive parameter, but doesn't add syntax or format details 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?

The description uses a specific verb ('按块读取' / read by blocks), names the resource (文档块 / document blocks), and clarifies behavior (返回顶层或全部块 with stable block_id and version). It clearly distinguishes itself from doco_get_document, doco_read, doco_traverse, and doco_get_tree because it emphasizes block-level access and stable IDs.

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 specifies when to use it: to read blocks, with a clear toggle for top-level vs recursive. It doesn't explicitly say when-not-to-use or name alternatives, but the sibling list and the '按块' framing imply it's for block retrieval, not for document metadata or search. The missing exclusions are a minor 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile with no contradiction. The description adds real behavioral context beyond annotations: the returned payload carries a version that must be attached to later writes, and annotate=anchors injects <!--@block=<id>--> anchors per top-level block to preserve block IDs across full-document rewrites. The 'warnings 降级提示' behavior is mentioned but not concretely defined, keeping this from 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?

The description is one dense, front-loaded passage that opens with the main purpose before covering formats, version contract, and anchor workflow. Every clause carries information — format trade-offs, the version-carry requirement, and write-back behavior — so nothing is redundant. It is long but justifiably so, and the logical flow is clear; splitting it into shorter sentences would improve readability slightly.

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 an output schema present, a 4-parameter signature, and annotations covering the read-only/idempotent safety profile, the description completes the key functional gaps: it names the version field, explains format fidelity differences, and describes the anchor-preservation workflow for round-trip edits. The weakest point is locale — both schema and description mention docset_ID and language versions without explaining fallback behavior when a locale is absent — so it is strong but not fully 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 baseline is 3. The description adds meaning for two of four parameters: it explains why to choose each format (markdown for semantic reading vs tiptap-json for lossless editing) and what the annotate anchors accomplish (preserving unchanged block IDs on write-back). document_id and locale receive no additional meaning beyond the schema, so the added value is partial — above baseline but not 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+resource: '读取整篇文档正文' (read the entire document body). The scope qualifier '整篇' (entire) and the format list distinguish it from block-level siblings like doco_get_blocks, doco_outline, and doco_get_tree. However, it never explicitly references overlapping siblings such as doco_read, so the 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?

The description gives explicit format-selection guidance: markdown for semantic reading (with warnings downgrade hints), tiptap-json for lossless precise editing, and html as a third option. It also explains the annotate=anchors write-back workflow — injecting block IDs and preserving unchanged block IDs on PUT — and the version field requirement for subsequent writes. It lacks explicit tool-selection exclusions against siblings like doco_read or doco_get_blocks, leaving that 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?

The description is consistent with the read-only, idempotent, non-destructive annotations and adds that the result is the complete directory tree including folders and documents. It does not hide side effects, and no contradictory behavior is mentioned.

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 a single focused sentence with no redundant words, examples, or 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 one-parameter read-only tree tool, the description provides sufficient context about the return scope (folders and documents) and the target resource; it could mention output structure or sibling distinctions, but the existing output schema and clear purpose cover most needs.

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?

With a single parameter that has a complete schema description ('知识库 ID'), the schema already provides the necessary meaning; the description adds no further detail beyond that.

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 clearly states the action ('获取' / retrieve), the resource (a knowledge base's complete directory tree), and the scope (folders + documents), making it easy to distinguish from document-level or search 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?

The wording implies use when the full folder/document hierarchy of a knowledge base is needed, but it does not explicitly compare against sibling tools such as doco_outline or doco_traverse or state when not to use it.

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?

Annotations declare readOnlyHint=false, destructiveHint=false, so the description is consistent. It adds context about server-side matching for after_heading and six positioning modes, which helps the agent understand behavioral nuances beyond the raw schema. It doesn't mention side effects like version conflicts or whether base_version is required for optimistic locking, but annotations already cover the write risk profile.

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 one sentence that front-loads the core operation and then packs all critical positioning modes into a compact list. Every part earns its place; no fluff or repetition of schema details.

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 description covers the key behavioral choice (position modes) well, but omits caveats such as whether inserting requires an existing document, how base_version is used for protected writes, or error conditions like duplicate headings. With an output schema present and annotations present, it's mostly complete, but a note about version conflict behavior would strengthen it.

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 parameters like nodes, position, document_id, base_version are documented in the schema. The description adds important meaning to 'position' by enumerating the six allowed strategies and giving an example ({ after_heading: "部署流程" }), which the schema's additionalProperties does not convey. This is valuable semantic enrichment.

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?

Description states a specific verb ('insert') and resource ('blocks') at a specified position, clearly distinguishing it from read/list/patch/delete siblings. The position enum is listed in Chinese, which is explicit but the title is tautological; still the description provides concrete positioning options.

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 usage by enumerating position strategies, but does not explicitly state when to use this tool vs alternatives like doco_patch_block or doco_batch_edit. No explicit exclusions or conditions are given, leaving the agent to infer based on the verb 'insert'.

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?

The annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the pagination behavior ('分页') and the filter scope, but does not disclose any additional side effects, authorization needs, or limitations beyond what annotations and schema provide. This is acceptable but not rich.

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 a single, front-loaded sentence that conveys the essential purpose and pagination without superfluous words. Every element carries meaning, so it earns a high score for conciseness.

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 the full schema coverage, output schema, and safety annotations, the description is largely sufficient for an agent to understand the tool's function. It does not mention how filters combine or that all filters are optional, but those details are available in the structured fields and do not critically impede correct invocation. Sibling differentiation is missing but handled under usage guidelines.

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 schema description coverage is 100%, with descriptions for all seven parameters, including q, limit, cursor, locale, folder_id, include_variants, and knowledge_base_id. The description groups these into higher-level concepts (search by knowledge base/folder/keyword) but adds no new meaning 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?

The description states a specific verb ('搜索') and resource ('文档列表'), and identifies the key filtering dimensions (knowledge base, folder, keyword) plus pagination. It is clear about what the tool does, but it does not explicitly distinguish this tool from sibling tools like doco_search and doco_search_v2, so it misses the top tier.

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 usage by describing the function, but it does not state when to use this tool versus alternatives such as doco_search or doco_get_tree. There is no explicit when-to-use or when-not-to-use guidance, so the agent must infer suitability from the tool's name and 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the useful scoping detail that only knowledge bases visible to the current user are returned, but it does not disclose pagination, ordering, or other behavioral details. This is acceptable but not rich.

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 a single concise sentence that front-loads the action and resource. There is no redundant wording or unnecessary detail, making it easy for an agent to parse quickly.

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-only listing tool with an output schema present, the description is complete. It specifies the scope (current user visibility) and the resource (knowledge bases), and the annotations cover the behavioral safety expectations.

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 has zero parameters, so there is no parameter semantics burden on the description. The schema is empty and fully covered, and the description does not need to explain any inputs. This aligns with the baseline for a zero-parameter tool.

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 clearly states the action ('列出' / list) and the resource ('当前用户可见的全部知识库' / all knowledge bases visible to the current user). It is specific enough to distinguish this tool from siblings like doco_list_documents, which targets documents rather than knowledge bases.

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 used when the agent needs to enumerate knowledge bases visible to the current user. However, it provides no explicit guidance on when to prefer this tool over alternatives, nor does it mention any exclusions or related sibling 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?

注解已声明 readOnlyHint=true、idempotentHint=true、destructiveHint=false，覆盖了只读、幂等和非破坏性等安全特性。描述在此基础上补充了该工具只返回标题结构（而非完整文档内容），并强调 block_id 是稳定的，这对调用者理解输出性质和规划后续读取非常有价值。没有与注解矛盾之处。

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?

描述用一句话简洁地涵盖了功能（读取大纲）、输出特征（block_id、heading_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?

该工具只有 1 个必需参数，且 schema 覆盖完整、有输出 schema 和全面的注解。描述已经提供了足够的信息让代理正确调用：它做什么、返回什么性质的数据、什么时候用。具体返回字段由输出 schema 承担，无需在描述中重复。

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 对 document_id 的说明覆盖率为 100%，描述中未额外解释参数含义或格式。根据规则，当 schema 描述覆盖率高时，参数语义得分的基线为 3，描述没有超越 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?

描述使用明确的动词'读取'和资源'文档结构大纲'，并具体说明输出内容为每个标题的 block_id、heading_path 和顶层块区间。这与 sibling 工具如 doco_read（读取正文内容）和 doco_get_tree（获取树结构）能清晰区分，代理无需打开 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?

描述中明确提到'适合先规划再局部读取'，给出了具体使用场景：先获取大纲规划，再按需读取局部内容。虽然没有指名替代工具或给出排除条件，但使用上下文已足够清晰，未达到最高分是因为缺少显式的 when-not-to-use 指引。

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?

The description adds meaningful behavioral context beyond annotations: it discloses optimistic concurrency via base_version, automatic latest-version reading when base_version is omitted, and 409 conflict handling with re-read/merge/retry guidance. This is consistent with annotations (readOnlyHint=false, idempotentHint=true) and adds value that is not present in the annotation block.

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 brief and front-loaded: the first sentence states the purpose and the two usage modes, the second sentence covers concurrency and error retry. Every sentence delivers essential information without 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?

The description covers purpose, usage modes, concurrency handling, and error recovery, with output schema and 100% parameter description coverage filling in the rest. It does not state what happens if no node/attrs/content is provided, but that is arguably a schema or validation concern rather than a description 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%, so parameters are already documented. The description goes further by clarifying base_version's role in optimistic concurrency and the auto-read behavior when absent, plus the distinction between node (full replacement) and attrs/content (partial modification). This is additional semantic value 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?

The description states '更新单个块' (update a single block) with a specific verb and resource, and clearly distinguishes two modes: full node replacement vs partial modification via attrs/content. This makes it easy to differentiate from siblings like doco_insert_blocks and doco_delete_block without ambiguity.

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 explicitly explains when to use full node replacement versus partial attrs/content modification, and describes how base_version should be used with a clear fallback to auto-read latest version. It does not explicitly name alternatives or exclusion conditions, but the usage context is clear enough given the sibling list.

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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond those annotations: the cursor is bound to the document body version, and `read_cursor_stale` signals that re-planning is needed. This is useful failure-mode disclosure and does not contradict the annotations.

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, with the core purpose front-loaded and the navigation and staleness behavior condensed into two sentences. Every clause contributes useful information, with no filler or repetition of schema details.

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 tool with 8 parameters, full schema coverage, and an output schema, the description covers the essential purpose, local-reading scope, navigation mechanisms, and cursor-version staleness. It does not explicitly explain how to choose this over sibling tools, but that gap is more about usage guidance than completeness of the read operation itself.

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 8 parameters already have descriptions. The description adds some value by explaining that `around` can anchor any nested block_id and that cursor continuation is supported, but it also references `next_cursor` while the schema property is named `cursor`, creating slight ambiguity. Overall, it provides modest value 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?

The description states '按 token 预算局部读取文档' (read a document locally under a token budget), giving a specific verb, resource, and scope. It clearly conveys what the tool does, though it does not explicitly differentiate it from siblings like doco_get_document, doco_get_blocks, or doco_outline.

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 usage mechanics: use `around` to anchor a nested block_id, or use a cursor to continue reading, and that a stale cursor requires re-planning. However, it does not explicitly state when to prefer this tool over alternatives or when not to use it, so the usage context is implied rather than 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 only thin hints in annotations (readOnlyHint=false, idempotentHint=true), the description carries the behavioral burden and does so richly: it discloses the sync-versus-async contract per generator, the mandatory follow-up polling via doco_summary, the obsolescence condition when the source changes or the summary is pinned, and the guarantee that stale results will not overwrite. This is consistent with all annotations — idempotentHint=true aligns with the non-overwrite and idempotency_key behavior — and no contradiction 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?

The description is compact — two sentences, front-loaded with the core action '重建摘要' followed by generator-specific contracts. Every clause carries distinct information (execution mode, return behavior, staleness policy, overwrite guarantee) with no filler or restatement of the tool name. The semicolon-chained structure is dense but readable, losing a point only for the slightly run-on feel.

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 the rich input schema (100% coverage, enums, idempotency key), the idempotentHint annotation, and an existing output schema, the description only needs to fill the behavioral contract — which it does thoroughly via sync/async mode, staleness conditions, and non-overwrite guarantees. The residual gaps are selection criteria between deterministic and model generators and the exact meaning of '可追溯 fallback', but neither blocks a correct 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%, so the schema already documents all six parameters and the baseline is 3. The description adds only indirect value: the obsolescence condition implies meaning for base_source_version, and the pinned-summary behavior relates to target scope, but no parameter-level syntax or format is elaborated. This is acceptable because the schema handles the burden.

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 opens with the verb+resource pair '重建摘要' (rebuild summary), clearly identifying a write-rebuild operation on a summary. It further distinguishes itself from the sibling query tool doco_summary by stating that a model generator requires a follow-up query via doco_summary(job_id). However, it never names doco_save_summary, its closest writing sibling, so an agent must infer the distinction between rebuilding and saving without explicit guidance.

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 concrete, actionable workflow guidance: for the model generator it explicitly states that only an async task is created and the agent must subsequently call doco_summary(job_id) to retrieve the result, which routes an agent correctly between two sibling tools. It provides clear context for the deterministic vs model split but lacks an explicit statement of when to prefer this over doco_save_summary or criteria for choosing between the two generators.

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?

Annotations already provide idempotentHint=true and destructiveHint=false; the description adds useful behavioral detail by specifying that writes automatically carry an idempotency key and that only pending-review candidates are generated, not direct changes to the explicit concept layer. This refines and contextualizes the annotation hints without contradicting them.

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 only two short sentences, with the primary action and the key safety guarantee front-loaded. Every phrase carries meaning, and there is no filler or unnecessary elaboration.

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 tool with full schema coverage, idempotency annotation, and an existing output schema, the description provides sufficient information for correct selection and invocation. The absence of an explicit sibling alternative pointer is a usage-guideline nuance, not a completeness 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?

The single parameter document_id is fully documented in the input schema ('要重新抽取候选的文档 ID'), and the description adds no additional parameter-level semantics. With schema description coverage at 100%, 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 names a specific action ('触发概念候选抽取/刷新') and resource ('概念候选'), and distinguishes this from the explicit concept layer by stating it only generates pending-review candidates. This makes it easy for an agent to tell it apart from siblings such as doco_concepts and doco_edit_concepts even without naming 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 description clearly communicates when to use the tool: to trigger candidate extraction/refresh while avoiding direct pollution of the explicit concept layer. It does not explicitly name an alternative or give a when-not-to-use statement, but the safety boundary and 'pending-review' wording provide enough context for correct 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?

Annotations already declare this as non-read-only, non-destructive, and idempotent. The description adds value by disclosing that the tool refuses direct machine-result overwrites and by prescribing re-reading the target version after a 409. This concurrency and review-policy behavior is not visible in the annotations or schema and meaningfully improves the agent's expectations.

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 a single sentence that front-loads the core action, then appends the two most important constraints: no machine-result overwrite and 409 re-read behavior. There is no repetition of schema or annotation content and no wasted 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 review-state tool with an output schema and fully described parameters, the description covers the essential action, the no-machine-overwrite policy, and the key conflict-handling instruction. The only notable gap is that it does not help an agent tell document_id and target_document_id apart, but the rest of the structured context is sufficient for 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%, so all six parameters are at least nominally documented. The description indirectly clarifies review_status by mapping 'current' to confirming the translation and 'ignored' to ignoring the unit, but it does not disambiguate document_id from target_document_id, which remain confusingly similar in the schema. A baseline 3 is appropriate because the schema carries most of the parameter documentation burden.

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 precise verb and resource: 'confirm current translation or ignore unit' on a specific target-language document. It also explicitly excludes direct machine-result overwrites, which distinguishes this review action from editing tools. This goes well beyond the title and makes the tool's role clear.

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 clear context: the tool is used on a target-language document to record a review decision. It also provides an explicit exclusion ('does not accept direct overwrite by machine results') and a conflict protocol ('on 409, must re-read the target version'). It does not name sibling tools such as doco_patch_block or doco_translation_units, so it falls just short of full alternative routing.

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?

Discloses important behavior: pinned only prevents automatic overwrites, source changes cause the summary to show stale, and base versions are used for concurrency protection. This goes beyond annotations (idempotent, non-destructive) and is consistent with them.

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 sentences convey purpose, protocol, and pinned behavior without redundancy; all content is relevant and no filler is present.

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 the output schema and full parameter coverage, the description adds necessary context about versioning, stale display, and the read-before-write requirement that cannot be inferred from 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?

All seven parameters have descriptions, including the protocol-critical base_source_version and base_summary_version, and the scope enum. The overall description clarifies how these parameters function in the protected write.

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 the tool's function clearly: 'Manually edit and pin summary' and explains the read-before-write protocol with dual versions, distinguishing it from automatic summary generation and rebuild 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?

Provides guidance to read current summary/source versions before writing and explains the protective write and pinned semantics. However, it does not explicitly name alternative tools such as doco_rebuild_summary, so the condition for choosing manual over automatic summary updates is not fully explicit.

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?

Annotations already declare the tool read-only, idempotent, and non-destructive. The description goes beyond by disclosing that body hits return a stable block_id and summary, and explicitly frames the tool as a locating step rather than a mutating action. This is valuable behavioral context without contradicting the annotations.

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 a single well-structured sentence that front-loads the core action and then provides the most useful operational detail: stable block_id for follow-up block API calls. Every clause earns its place with no fluff or repetition of annotation 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?

Given the output schema exists, the description does not need to explain return values in depth. It covers the essential search behavior, the useful block_id outcome, and the intended follow-up workflow. It is complete enough for an agent to call the tool correctly, though it could mention when to prefer doco_search_v2.

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 q, limit, locale, and knowledge_base_id. The description adds no parameter-level detail beyond restating that search covers title and body, which is also embedded in the schema. Baseline 3 is appropriate because the description does not need to compensate for schema gaps.

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 clearly states a specific verb and resource: full-text search across documents by title and body. It also adds what result shape matters (stable block_id and summary), which helps distinguish it from generic list/read tools. However, it does not explicitly differentiate itself from the closely named sibling doco_search_v2.

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 a clear usage context: use this to locate documents first, then call block APIs for precise read or modification. This implies the intended search-to-locate workflow. It does not mention when to prefer doco_search_v2 or any exclusion criteria, so it is not a full routing guide.

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?

The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's job is to go beyond safety traits — and it does substantially. It discloses the response composition, the cursor-based exhaustive traversal semantics, and critically the negative-evidence rule: when projection.complete=false, results are incomplete and '不能据此断言知识不存在' (cannot assert knowledge absence). This directly prevents a classic agent failure mode of treating a search miss as proof of non-existence. No contradiction with the annotations; it refines the open-world nuance without conflicting.

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 dense sentences with no filler: the first front-loads the purpose and enumerates the return fields, the second conveys the exhaustive-mode traversal capability and the completeness caveat. Every clause earns its place, and the most decision-relevant warning (incomplete results cannot prove absence) is placed at the end where it reads as a caution.

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 output schema exists, so the description is not obligated to fully document return values, yet it still summarizes the key return categories and adds the completeness semantics that no schema could express. For a 6-parameter tool with pagination, an enum mode, and locale/KB scoping, this covers the essentials. The one genuine gap is sibling routing: with doco_search present in the same tool list, the absence of any statement about which search variant to prefer leaves a meaningful completeness hole.

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 carries the per-parameter documentation burden and the baseline is 3. The description adds genuine value on the mode/cursor interplay — that exhaustive mode combined with cursor allows complete traversal — which the schema's terse 'mode parameter' and 'opaque pagination cursor' text does not convey. It does not, however, add meaning for q, limit, locale, or knowledge_base_id beyond what the schema already provides.

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 opens with a specific verb and resource — '全文搜索' (full-text search) — qualified by a distinctive feature, '带查询级完整性证明' (with query-level completeness proof), and enumerates the return content (catalog path, title path, context, score explanation, watermarks). However, it never differentiates itself from the near-identically named sibling doco_search; the reader must infer why two search tools exist rather than being told.

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 context is implied rather than explicit: 'exhaustive 模式可用 cursor 完整遍历' tells the agent that exhaustive mode plus cursor enables full traversal, and the projection.complete=false caveat indicates when a negative result is not trustworthy. But no alternative tools are named, and the obvious sibling doco_search is not addressed with any 'use this when / use that when' guidance, leaving the selection between the two search tools 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?

The description adds that results include source blocks, source versions, coverage, freshness, and fallback semantics, and that it is always available even when the model is off. This goes beyond the annotations, which only state read-only, idempotent, and non-destructive. It does not detail behavior when querying an incomplete async job, but overall adds useful 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 two sentences, starting with the main purpose, and includes essential details without superfluous 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?

Given the output schema exists and annotations cover safety, the description adequately conveys the tool's main functions and result characteristics. It could elaborate on parameter relationships or expected error scenarios, but it is sufficient for an agent to select and invoke the tool.

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?

Each parameter has a description, covering 100% of the schema. The descriptions explain the role of query, scope, job_id, block_id, and target_id. However, they do not clarify how parameters combine (e.g., whether job_id supersedes target_id) or which are mutually exclusive, so the description adds limited semantic depth 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?

The description clearly states the tool reads summaries of various scopes (document, folder, knowledge base) and also queries asynchronous generation tasks. It distinguishes itself from siblings like doco_save_summary or doco_rebuild_summary by focusing on reading.

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 does not explicitly specify when to use this tool versus alternative tools like doco_get_document or doco_outline. It implies usage for retrieving summaries, but lacks direct guidance or conditions.

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?

Annotations already declare readOnlyHint, destructiveHint, and idempotentHint. The description's mention of '读取' aligns with these, but it adds no additional behavioral context beyond the annotations. With annotations present, the bar is lower, so a score of 3 is appropriate.

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 a single, clear sentence with no unnecessary words or repetition. It is concise 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?

The description provides sufficient context for a simple read operation, identifying the specific data points returned. However, it does not mention output format or any potential errors, but that is not critical for a read-only tool with no output schema.

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 only parameter, document_id, is described in the schema as 'Target document ID.' The tool description does not add further explanation or context for the parameter. Since schema coverage is 100%, a baseline score of 3 is warranted.

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 clearly states the tool reads a specific document's Document Set, source language, available language versions, and freshness. It uses the verb '读取' (read) and specifies the resource, distinguishing it from other document-related 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or situations where this tool is preferred.

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?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description's 读取 is fully consistent. The description adds meaningful context beyond annotations by enumerating the exact data exposed: block-level translation units, stable block mapping, source_version, and missing/current/conflict statuses. It does not discuss edge-case behavior, but the output schema and read-only annotations lower the burden.

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 a single dense sentence that front-loads the action and resource, with no filler, repetition of the title, or irrelevant detail. Every clause contributes useful information about what the tool reads.

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 the output schema, rich read-only annotations, and complete parameter-level schema descriptions, the description covers the core semantics well. The only notable gap is usage guidance versus sibling tools, but the resource scope is clear enough for an agent to select and 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 baseline is 3. The description adds value by naming the status vocabulary (missing/current/conflict) and clarifying that locale relates to target-language content, which is not fully specified in the parameter descriptions. It does not elaborate on document_id versus target_document_id, but the schema already provides those descriptions.

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 uses the verb 读取 (read) and names a specific resource: block-level translation units plus stable block mapping, source_version, and translation statuses. This makes it clear that the tool is a read operation, distinct from review/write siblings, though it does not explicitly name or contrast any 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 guidance about when to use this tool versus doco_translations or doco_review_translation_unit, and no mention of alternative conditions or exclusions. The verb 读取 implies a read context, but that is implicit rather than explicit 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?

Annotations already carry readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful interpretation semantics: status=dangling_* invalidates the target, evidence_freshness=stale requires re-confirming evidence, and projection_freshness=stale means the result is not a complete relationship graph. This kind of staleness/validity context goes well beyond the annotations.

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 one dense sentence that front-loads the primary action before the return summary and three status caveats. Every clause earns its place, though splitting the trailing semicolon-separated caveats into separate sentences or bullets would improve scannability; the Chinese-language description also sits alongside an English schema without issue.

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 traversal tool with a rich output schema and safety annotations, the description covers what is returned and how to interpret dangling/stale flags. Minor gaps remain: pagination or traversal depth/limits are not mentioned, and no guidance connects this to doco_create_relation as the mutation counterpart, but the output schema likely covers return shape.

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 (document_id, direction, predicate) are already documented in the schema. The description ties output concepts (forward/reverse relations, registered predicates) to the direction and predicate parameters but adds no new syntax or format detail, matching the baseline-3 expectation for high schema coverage.

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 — traverse documents along explicit relationships — and enumerates what it returns (forward/reverse relations, registered predicates, source blocks, source versions). This clearly differentiates it from siblings like doco_get_tree, doco_read, doco_search, and especially doco_create_relation, which is the write counterpart.

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 qualifier 'explicit relationships' implies it is for relationship traversal rather than content reading or tree structure, giving some usage context. However, it never names alternatives or states when not to use it; with many nearby read tools (doco_get_tree, doco_outline, doco_search), explicit routing would help.

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?

在destructiveHint=true和idempotentHint=true的基础上，描述进一步补充了具体机制：markdown写入如何保留未改动块ID、tiptap-json整篇替换、版本冲突时的合并重试建议，这些是注解未覆盖的行为细节，对调用者判断副作用和恢复策略非常有价值。

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?

三句话覆盖核心操作、格式行为和版本建议，信息高度浓缩，无冗余词汇，关键约束（整篇、base_version）前置，结构清晰利落。

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?

面对5个参数、3种格式、锚点机制和409冲突场景，描述覆盖了调用所需的核心要点：格式差异、冲突应对和版本建议。但缺少对无锚点情况的说明以及与批量/局部编辑工具的边界提醒，略有遗漏。

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对5个参数100%覆盖，提供了基本描述，因此基线为3。描述额外强调了base_version的关键性和format的行为差异，帮助调用者理解参数选择与组合使用，但未明确content/document与format的对应关系，略逊于完美。

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?

描述以'整篇写回文档正文'明确表达了动词和资源，直接说明这是全文更新操作，与patch_block、insert_blocks、delete_block等局部编辑工具形成明显区分。'整篇'一词强调了作用范围，不存在歧义。

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?

描述了不同format下的使用方式（markdown锚点保留、tiptap-json无损替换），并强烈建议带base_version及409冲突后的重试策略，提供了清晰的使用上下文。但未显式说明何时不应用此工具而改用其他编辑兄弟工具，缺少明确的排除条件。

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?

Annotations already indicate this is a write operation (readOnlyHint=false) and not idempotent. The description adds supported file types and return values, but does not disclose potential side effects, retry behavior, or file size limits. With annotations covering the safety profile, this is adequate but not rich.

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 sentence with the action, supported types, return values, and usage tip. Every clause earns its place; 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?

Given an output schema exists and annotations are present, the description covers the essential workflow: upload, get IDs, reference in blocks. It omits edge-case details like file size limits, but those are not critical for correct 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 coverage is 100%, so baseline 3 applies. The description adds value by enumerating acceptable file types (image/PDF/text/Word) that are not present in the file_path schema description, clarifying the parameter's allowed content.

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 uses a specific verb (上传/upload), names the resource (attachment), lists supported file types, and states the return values (attachment_id, URL) plus the referencing workflow. It is clearly distinct from sibling tools, none of which perform uploads.

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 clear context: use when you need to attach a file to a document, and it explains how the resulting attachment_id is used in image blocks. It doesn't name exclusions or alternatives, but no direct alternative exists among siblings, so the guidance is 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?

Annotations already declare the tool read-only, idempotent, and non-destructive, lowering the bar for behavioral disclosure. The description adds useful context by specifying that it inspects the current token and reports user/permission scope, but it does not elaborate on behavior around missing or invalid tokens.

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 a single, front-loaded sentence with no filler. It communicates the action and the object in minimal space, and every word 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?

Given the tool's low complexity, zero parameters, rich annotations, and existing output schema, the description is complete enough. It clearly tells an agent what the tool does and what information it will surface, with no meaningful 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?

The tool has zero parameters and schema coverage is 100%, so there is no parameter documentation burden for the description. The no-parameter baseline is 4, and the description appropriately says nothing about inputs.

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 an explicit self-check action ('自检身份') and clearly identifies the resource: the user and permission scope associated with the current token. This is distinct from all sibling tools, which focus on documents, search, translations, and concepts rather than identity introspection.

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 intended use case: call this tool when you need to know the current token's user identity or permission scope. It does not explicitly name alternatives or exclusions, but no sibling tool appears to serve this identity-check purpose, so the contextual guidance is sufficient.

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