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

With no annotations, the description carries the full burden and does well: it discloses that timestamps and reason stamps are auto-inserted and that a pre-revision mirror is recorded (audit side effect), and that existing text is preserved. It omits permission requirements and whether appends are idempotent, but the key side effects are surfaced.

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 behavioral contract is front-loaded in the first sentence, with parameters documented compactly below. The Args block is slightly verbose but every line carries information; nothing is redundant with the schema titles.

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

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

For a 3-parameter mutation tool with no annotations, the description covers the side effects (timestamp/reason stamp, revision mirror) that an agent needs before writing. An output schema exists, so return values needn't be explained; only permission/auth context is arguably missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does: each of the three parameters is given meaning beyond its schema title — node_token as the target page, markdown as the content to append, and reason as the rationale written into both the page and the audit ledger. It doesn't note that reason is optional (default empty), which keeps it from a 5.

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

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

States a specific verb and resource ('在页面末尾追加内容') plus a scope constraint ('不改写原文') that implicitly separates it from kb_replace_text. It doesn't name the sibling tool explicitly, so a 4 rather than a 5.

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

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

Usage is implied by 'append without rewriting the original', which tells the agent this is for additive edits rather than replacements. However, no alternatives are named (e.g., kb_replace_text for rewriting) and no when-not conditions or prerequisites are given.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses what is inspected and that it produces structural suggestions based on thresholds, which is behavior beyond the name. However, it does not state that the operation is read-only (no mutation of the KB), whether thresholds are fixed defaults, whether the run is expensive/slow on large KBs, or whether it has any side effects such as caching.

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, front-loaded with the overall '体检' framing followed by the concrete check list and then the suggestion output. No filler. It is slightly dense with enumerated items but every clause names a distinct check.

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 return values need not be explained, and there are no parameters. What remains missing is the behavioral envelope: whether the audit is read-only, whether thresholds are fixed, and how it relates to kb_status for an agent deciding between the two. 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?

The tool takes zero parameters, so the baseline of 4 applies. The description also implicitly explains why there are none by framing the check categories as fixed, though it does not state that thresholds are non-configurable defaults.

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 clear metaphor ('体检' / health check) and enumerates the concrete checks performed: duplicate pages, empty pages, missing body text, overly deep/wide directory structure. This is specific enough for an agent to know it is a diagnostic/audit operation, distinct from read siblings like kb_read or kb_outline. It stops short of stating the operation in a precise noun+verb form (e.g., 'audit the knowledge base and report structural issues').

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 say when to run an audit versus alternatives such as kb_status (which sounds like a lighter health/state check) or kb_outline. There are no stated preconditions, no exclusions, and no routing to siblings. Use is only implied by the audit vocabulary.

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

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

No annotations are provided, so the description carries the full burden, and it discloses multiple behaviors beyond the schema: idempotent dedupe on title/content, automatic locator header prepending, and the three-section structure injected when directory=true. That is solid, though it omits permission or failure-mode disclosure and says nothing about what the returned page looks like, which the output schema may cover.

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 front-loaded: the core action and idempotency contract come first, then a compact Args block where each line carries a concrete rule. It is appropriately sized for a 10-parameter creation tool, with only minor redundancy in the type enumeration.

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 return values need not be explained. However, four metadata parameters (domain, source, status, maturity) with non-obvious defaults are documented nowhere, leaving an agent unable to reason about them. That is a real completeness gap for a tool with 10 parameters and no annotations.

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

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

Schema description coverage is 0% across 10 parameters, so the description must compensate. It meaningfully documents 6 of them—title authoring rules, markdown header behavior, parent_node_token fallback, type values, directory side effects, and the force escape hatch—but leaves domain, source, status, and maturity totally unexplained, which is a substantial gap.

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 ('新建一页并写入正文'), which clearly identifies the operation as page creation plus body write, and it distinguishes the tool from kb_append and kb_replace_text by implying it acts on new pages. It does not name those siblings explicitly, so it does not reach the level of a 5.

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

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

The description gives clear context: default idempotency so duplicate title or content returns the existing page, and 'force' only when you knowingly want a parallel second page. It does not explicitly route to alternatives, for example to kb_append for adding content to an existing page, so a 4 rather than a 5 is appropriate.

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

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

With no annotations, the description carries the full burden, and it does add real value by stating that node_token is preserved and old links remain valid — a stability guarantee not derivable from the schema. However, for a mutation it omits permission requirements, what happens to children of the moved node, and whether moving under a descendant is rejected.

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

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

Two short, front-loaded sentences with zero waste — the action comes first, the invariance guarantee second. Nothing could be removed without losing meaning.

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

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

An output schema exists, so return values need not be explained. But for an unannotated mutation with three parameters at 0% schema coverage, the description leaves gaps around permissions, failure modes, and the 'reason' field.

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 0%, so the description must compensate; it only clarifies that node_token is unchanged by the operation, leaving target_parent_node_token and especially the optional 'reason' parameter unexplained. Two of three required parameters have no semantic elaboration.

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

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

States a specific verb and resource ('把页面移动到另一个父节点下' = move a page under another parent node), which is unambiguous. It does not, however, distinguish itself from siblings like kb_rename or kb_outline, so the agent gets no routing help.

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

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

No guidance on when to use this versus alternatives (e.g., kb_rename for name changes, kb_create for new pages), and no prerequisites or exclusions. The agent must infer the context of use entirely.

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

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

With no annotations, the description carries the full burden, and it does disclose the two most important behavioral traits: the default entry point and a depth cap (default 3, range 1–5). It does not state that the operation is read-only in so many words, nor whether large trees are truncated or paginated beyond the depth limit, which matters for a browsing tool on an unknown-sized corpus.

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

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

Purpose and scope are front-loaded in the first sentence, followed by a compact per-argument list; there is no filler. The Args block is slightly redundant in formatting but each line adds 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?

An output schema exists, so return shape need not be explained, and both parameters are covered semantically. What is left unaddressed is minor but real: read-only nature and any size/truncation limits on the returned tree.

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 0% and neither param has a description in the schema, so the description must compensate, and it does: parent_node_token is defined as the starting node with empty meaning the configured entry page (a semantic the bare default "" does not convey), and depth is given the range 1–5 that the schema omits. Only the token format itself remains unspecified.

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

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

"查看知识库目录树" states a specific verb and resource, and adds scope (default starts at the entry page, max 3 levels) plus a concrete use case ("answering what have I written down"). It is implicitly distinguishable from kb_search/kb_read as a structural browse rather than a query or single-page read, but no sibling is named explicitly.

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

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

The phrase "用于回答'我都记了什么'" gives an implied usage context, which is more than nothing. However, it never says when to prefer kb_outline over kb_search or kb_read, nor any exclusions or prerequisites, so routing still requires the agent to infer from tool names.

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

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

With no annotations, the description carries the full burden and discloses important behavior: AI cannot directly delete, a one-time proposal number is returned, and human confirmation at the command line is required. It still omits details such as proposal expiry, permissions, or what happens after confirmation.

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

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

The description is two short sentences with no wasted words. The purpose and the critical human-confirmation constraint are front-loaded.

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 return values do not need to be explained. However, with no annotations and 0% parameter schema coverage, the description should do more to explain the required node_token and reason parameters, even though the core proposal workflow is covered.

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 0% for both required parameters, and the description does not explain node_token or reason at all. The overall context hints that these relate to a deletion target and justification, but no parameter-level meaning is added beyond the schema titles.

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: initiating a deletion proposal. It also clarifies that AI cannot delete directly, which makes the tool's role distinct from direct mutation, but it does not explicitly compare against sibling 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 implies this tool is used when a deletion is needed but cannot be performed directly, and that human confirmation is required. It does not state when not to use it or name alternative tools, so the guidance remains implied rather than 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?

Since no annotations are provided, the description carries the full burden of context. It is transparent about the *structure* of the returned data, listing specific elements like '修订摘要与链接,' which is valuable behavioral context for a retrieval operation.

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 definition is efficient and concise. The purpose is front-loaded, and the description adds value without being verbose or repetitive of the structured schema definition.

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

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

Given that an output schema is expected, the description is highly complete, as it specifies the exact nature of the content (Markdown, metadata points) retrieved. The agent has all the necessary information to attempt 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?

With a 0% schema description coverage, the description must compensate entirely. It excels here by explicitly defining the 'node_token' as a Knowledge Base node token and providing context on its expected origin, which significantly enhances understanding.

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

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

The description is exceptionally clear, using specific verbs to list all retrieved data points: real-time Markdown body, headers, path, revision summary, and links. This distinct list effectively differentiates it from siblings like kb_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?

Usage is implied rather than explicitly stated. While the description explains the required input source (tokens from kb_search/kb_outline), it does not provide explicit guidance on when to use this tool versus when a purely content-based tool should be used.

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

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

With no annotations, the description carries the full burden, and it does disclose two meaningful side effects: the old title is retained as a search alias, and existing links remain intact. That is real value beyond the schema. However, it says nothing about permissions, whether the rename is reversible, or what confirmation looks like for a mutation.

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

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

Two compact sentences, front-loaded with the action and followed by the non-obvious consequences. Zero wasted text.

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

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

Output schema exists, so return values need no explanation, and the two side-effect facts cover the riskiest behavior. But for a 3-parameter mutation with no annotations and zero schema descriptions, leaving node_token and reason undocumented is a real 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 0% across three parameters, so the description must compensate and largely doesn't. It implies a new title is supplied but never explains node_token (the target identifier) or what the optional 'reason' field is for.

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

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

States a specific verb+resource: '修改页面标题' (modify page title), and adds the conceptual framing that the title IS the proposition. It's distinguishable from kb_replace_text or kb_move by focusing on the title alone, but it doesn't explicitly name those siblings.

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

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

No when-to-use or when-not guidance. The agent must infer that this is the tool for renaming rather than editing body content, and nothing directs it away from kb_replace_text or kb_move for adjacent edits.

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

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

No annotations are supplied, so the description carries the full behavioral burden. It usefully discloses that this is a mutating rewrite that preserves formatting and that a read-verify step is mandatory, but says nothing about match scope (first occurrence vs all), behavior when the search string is absent, reversibility, or permission requirements.

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

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

Three short sentences, front-loaded with the action, then use cases, then the safety precondition. No filler; the prerequisite is placed last so it reads as a gate right before invocation.

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 return values need not be described. But for a destructive rewrite with zero annotations and zero schema coverage, the description is thin: it omits match semantics, failure behavior, and the meaning of node_token, all of which an agent needs before mutating a page.

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 0%, so the description must compensate and it only partly does: 'search fragment' implies an exact literal match string and 'replace' the substitute text. node_token (which page/node to target) and the optional reason parameter receive no explanation anywhere, leaving half the parameters undocumented.

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

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

States a specific verb and resource: replace a literal span of text inside a page while preserving style. It also distinguishes itself from siblings by declaring it is the only tool that rewrites existing original text, so an agent can route between it and kb_append/kb_create without inspecting schemas.

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

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

Gives concrete use cases (fixing typos, updating stale values, correcting wording) plus a hard prerequisite: call kb_read first to confirm the search fragment. It does not explicitly say when NOT to use it (e.g. adding new content should go to kb_append), so the exclusion is implied rather than stated.

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

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

With no annotations at all, the description carries the full burden, and it does disclose one genuine behavioral trait — title-weighted ranking across the entire library. It says nothing about permissions/auth, rate limits, result ordering/pagination beyond k, or whether body text is searched alongside titles.

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

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

Two tight components: a one-sentence capability line with the ranking caveat front-loaded, followed by a compact Args block. No filler, no restatement of the schema's type 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?

An output schema exists, so listing return fields is redundant but harmless. For a zero-annotation, zero-schema-coverage tool, the missing pieces are the follow-up workflow (what to do with node_token, i.e. kb_read) and any authentication or result-limit behavior — the definition is workable but not complete.

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

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

Schema coverage is 0%, and the description fully compensates: it gives query formulation rules ('write it the way you'd write a title, no IDs or abbreviations') and states the k bound of 1–20 which the schema does not express at all (schema only shows type integer and default 8). An agent can call this correctly from the description alone.

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

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

States a specific verb (检索/search) and resource (全库, the whole knowledge base), plus the scope note that title matches are weighted higher and what each hit contains. It doesn't name kb_read or any sibling explicitly, but '全库检索' versus reading a single page is distinguishable from the sibling names alone.

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

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

Usage is only implied: a global search tool that returns node_token naturally precedes kb_read, but the description never says so nor names any alternative or when-not condition. The query-phrasing hint ('用你会写进标题的说法') is the only actionable guidance about how to use it well.

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

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

With no annotations at all, the description carries the full burden and does meaningful work: it discloses that the default path is purely local with no network request, and that probe triggers a live Feishu call to re-validate permissions. It does not describe failure/error behavior or latency cost of the probe, which is the remaining gap for a no-annotation tool.

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

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

Two front-loaded sentences state the payload and the routing rule, then a single arg line. Nothing is redundant and the most decision-relevant clause (when unsure, call this first) is placed early.

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 return values need no explanation, yet the description still previews the four status categories. Combined with the probe semantics and the default no-request behavior, an agent has everything needed to call it 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 coverage is 0%, so the description must compensate, and it does completely: probe is defined as whether to hit Feishu live to verify permission validity, with the default (false) explicitly explained as local-only with no request. That is more than the bare boolean schema conveys.

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

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

States a specific verb and resource (查看连接状态/索引规模/上次同步时间/待确认删除提案) and enumerates exactly what the tool reports. That enumeration cleanly separates it from siblings like kb_search, kb_read, kb_audit, and kb_sync, so an agent can pick it without opening the 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?

Gives an explicit routing rule: 任何不确定时先调用它 (call this first whenever uncertain), which is a strong default-selection heuristic for a 12-tool family. It stops short of naming alternatives or exclusions (e.g. when to prefer kb_audit for history), so it is clear but not exhaustive.

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

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

No annotations are provided, so the description must disclose behavior by itself. It does disclose the critical risk: full sync clears the local index and rebuilds it without affecting Feishu content, which lets an agent judge the destructive scope. It does not mention permissions, whether the operation blocks or runs for a long time, cost, or what incremental sync actually checks.

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?

It is short and front-loaded: the purpose comes first, the mode selection comes second, and the per-argument notes come last. Each line adds information and none is redundant.

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

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

An output schema exists, so the return values need not be explained. The two optional parameters are both documented, and the main hazard of full sync is disclosed. Only the distinction between the incremental and full sync semantics is thin (for example, what incremental sync compares or whether it is safe to re-run).

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 0%, so the description must supply the meaning of the parameters, and it does: full is explained, and max_nodes is described as the maximum number of nodes synced this time. However, the relationship between the two is unclear (for example, whether full sync ignores max_nodes), and the default of 2000 is not called out in the prose.

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: syncing a Feishu knowledge base into a local index. This clearly separates the tool from read-oriented siblings such as kb_search, kb_read, and kb_status. However, it does not explicitly claim that it differs from every 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?

It explicitly separates the two modes: use incremental sync for routine work, and use full sync when the structure has changed substantially or the index is suspected to be corrupted ("日常用增量；结构大改或索引怀疑损坏时用 full"). However, it gives no guidance on when to sync at all versus first calling kb_status.

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