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

With no annotations, the description carries the full behavioral burden. It does disclose one real trait beyond the schema: parent directories are created automatically (mkdir -p semantics). It says nothing about behavior when the directory already exists (error vs. idempotent), permissions required, or failure modes — significant gaps for a write tool with zero annotation coverage.

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 front-loaded sentence with zero filler; the scope and the parents behavior are both packed into it.

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, for an unannotated mutation tool the description omits existence/overwrite behavior and error conditions, leaving an agent to guess how to handle a pre-existing path.

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?

There is one parameter at 0% schema description coverage, so the description must compensate. It partially does by implying relpath is interpreted relative to the volume root, but it does not state the path format, allowed characters, or whether a leading slash is valid.

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

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

States a specific verb and resource ("Create a directory") plus a scope constraint ("under the volume root"), which is enough to separate it from siblings like kb_move_file or kb_rename_file. It stops short of naming a sibling or explicitly contrasting, but the action is unambiguous.

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

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

No guidance on when to use this versus alternatives such as kb_move_file or kb_list_tree, and no preconditions stated (permissions, whether the volume root must exist). Usage is only inferable from the name and the parenthetical "(and parents)".

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

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

No annotations are provided, so the description carries the full behavioral burden. It makes clear the tool reports rather than mutates, and it lists exactly which conditions are surfaced, which is useful. However, it does not state cost/scope of the scan (whole KB vs. partial), whether it modifies anything (e.g. rebuilding the index), or any performance caveats for large knowledge bases.

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 parts: a one-line purpose followed by a dense enumeration of the checks, with the purpose front-loaded. Every clause maps to a distinct output category. Minor waste only in the reST-style double-backtick markup around `_Inbox` and `INDEX.md`.

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 zero parameters and an output schema present, the description only needs to explain what the audit looks for, and it does so exhaustively across four categories. The remaining gap is operational context — expected cost on a large KB and whether any remediation happens — but nothing required to invoke it is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. No parameter-level gaps exist to compensate 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?

The description gives a specific verb+resource ('audit the knowledge base') and then enumerates the four problem classes it reports: inbox backlog, orphans, dead links, and unindexed files. This is far more than a restatement of the name. It does not explicitly contrast itself with overlapping siblings such as kb_status, kb_scan_inbox, or kb_reindex, so an agent must infer the boundary.

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 stated — 'audit for common problems' suggests a periodic or pre-cleanup diagnostic, and the enumerated checks hint at what you'd act on afterwards. There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. kb_scan_inbox for inbox-only checks).

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

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

No annotations are provided, so the description carries the full behavioral burden; 'List' implies read-only, but it says nothing about traversal behavior, output size limits, symlink handling, or error conditions for a missing subdir. The only behavioral disclosure is the parenthetical 'depth-limited', which is vague since the actual default (2) lives in the schema.

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 front-loaded sentence with no filler, appropriately sized for a simple two-parameter read. The doubled backticks around ``subdir`` are a minor formatting artifact but don't hurt comprehension.

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 needn't be described, but for a traversal tool with zero annotation coverage and zero schema description coverage the description leaves too much unstated: depth semantics, defaults, and whether the listing is recursive or a single level. It is not complete enough for reliable 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 0%, so the description must compensate and only partly does: it names `subdir` and gestures at `depth` via 'depth-limited', but never explains what depth counts (directory levels vs. file counts), that it defaults to 2, or that subdir defaults to '.'. An agent still has to guess the meaning of both parameters.

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

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

States a specific verb (List) and resource (directory tree) with a scoping qualifier (under subdir, depth-limited), which cleanly separates it from retrieval siblings like kb_search or kb_read_document. It doesn't explicitly name any sibling, so it stops short of 5.

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

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

No guidance on when to prefer this over kb_search, kb_scan_inbox, or kb_status. The agent must infer that this is for structural browsing rather than content lookup.

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

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

With no annotations, the description must carry the behavioral burden. It does disclose the key traits — the operation is additive ('append'), non-destructive of prior content, and targets a fixed path — but says nothing about whether the meta directory is created if absent, whether lines are timestamped, or whether failures raise errors.

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?

One sentence, front-loaded with the verb and resource, with the path in parentheses as useful supporting detail. No filler; the only shortfall is that the budget was spent entirely on 'what' with nothing on 'when'.

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

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

For a one-parameter append-only logging tool with an output schema, the description covers the essential what and where, so an agent can call it. Gaps remain on line format, directory creation side effects, and when logging is expected, which matter because there are no annotations to fall back on.

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% and the single 'message' parameter is never described. The description doesn't say whether message should be plain prose, whether newlines are allowed, or whether it is prefixed/formatted. The self-evident parameter name limits the damage, but no compensation is provided.

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?

Specific verb ('Append') plus a specific resource ('a line to the organize log') and even the concrete target path (.mcp_meta/organize.log). This clearly separates it from read/search/mutation siblings like kb_read_document or kb_move_file, though it never explicitly names a sibling it contrasts with.

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

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

There is no statement of when an agent should call this versus doing nothing or using another tool, nor any precondition (e.g. 'call after a successful organize operation'). Usage is only inferable from the word 'log'.

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

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

With no annotations provided, the description carries the full behavioral burden. It usefully discloses that "the search index is updated in place — no reindex needed afterwards," but it omits important mutation behavior such as overwrite/collision handling, source deletion semantics, required permissions, and failure modes.

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 purpose is front-loaded in the first sentence, followed by a relevant index-update note and compact parameter explanations. Every line adds useful information with no filler.

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

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

An output schema exists, so return-value explanation is unnecessary. However, for a mutation tool with no annotations and a sibling kb_rename_file, the description lacks selection guidance and collision/overwrite behavior, leaving meaningful gaps for safe invocation.

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

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

Schema description coverage is 0%, so the description must compensate, and it does explain all three parameters. It gives path examples for src_rel and dest_dir_rel and clarifies that new_name is optional and preserves the original filename when empty.

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-plus-resource: "Move (and optionally rename) a file into a category directory." That is clear enough to identify the operation, but it does not explicitly distinguish the tool from the sibling kb_rename_file despite overlapping rename functionality.

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 that this tool is for moving files into category directories, but it gives no explicit when-to-use guidance, prerequisites, or exclusions. It never says when to use kb_move_file versus kb_rename_file, kb_create_directory, or other siblings.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses that the return is extracted text (not raw bytes), but says nothing about behavior on missing files, truncation signaling, or permission/error conditions. The output schema covers the return shape, which offsets this somewhat.

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?

One front-loaded sentence stating the purpose, followed by a compact param block. No wasted prose, though the Sphinx-style ':param' formatting is slightly redundant with the schema.

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 needn't be described, and both parameters are documented. The remaining gap is error/missing-file behavior and how truncation is indicated to the caller.

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 does: relpath is defined relative to the volume root with a concrete example, and max_chars is bounded (1-50000). The default value of 6000 is only in the schema, and truncation semantics aren't spelled out, keeping it short of 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: return the extracted plain text of one document. The 'one document' scope implicitly separates it from kb_search and kb_list_tree, though no sibling is named.

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 parenthetical '(for quoting/summarising)' implies a use case, but there is no explicit when-to-use/when-not guidance and no routing to kb_search for finding a path first.

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

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

No annotations are supplied, so the description carries the burden. It usefully discloses the incremental-vs-full behavior and the cost implication that full re-extracts every file, but says nothing about permissions, duration, concurrency, or whether the operation is safe to interrupt or repeat.

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

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

Two short sentences, with the primary action front-loaded. The ':param' reStructuredText artifact is slightly out of place in a tool description but costs little.

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

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

A mutation-flavored maintenance tool with no annotations and an output schema (so returns needn't be explained). The one parameter is well covered, but guidance on when to run it, prerequisites, and side effects on the existing index is missing.

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

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

Schema coverage is 0% for the single parameter, but the description compensates well by defining 'full' as re-extracting every file rather than only changed ones. That is the key semantic an agent needs to choose the value.

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: scan the volume and update the search index incrementally. That distinguishes it from kb_search and kb_read_document, though it is not explicitly differentiated from kb_health_check or kb_update_index_md, which an agent might confuse with an index-maintenance operation.

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

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

Implies usage ('incrementally' vs a full re-scan) but never states when an agent should call this versus siblings such as kb_scan_inbox or kb_update_index_md, nor whether it is safe or necessary to run routinely.

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 that the index is kept in sync and that the operation stays in the same directory, but it omits important mutation details such as overwrite behavior, permissions, failure cases, and reversibility.

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 filler. The core operation and scope are front-loaded, and the index-sync note is directly relevant.

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?

Although an output schema exists, this is a mutation tool with no annotations and zero parameter description coverage. The description leaves out collision behavior, path semantics, and permission requirements, so it is not complete enough for confident 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 0%, so the description must explain the two required parameters. It does not clarify what 'src_rel' is relative to, whether 'new_name' should include an extension, or how target-name collisions are handled.

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: rename a file. The phrase 'in place (same directory)' also distinguishes it from the sibling move operation without requiring schema inspection.

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 for when this tool applies: renaming within the same directory. However, it does not explicitly name kb_move_file as the alternative for cross-directory moves or state when not to use this tool.

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

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

No annotations are supplied, so the description carries the burden; 'List' implies a safe read, but it says nothing about permissions, ordering, limits, or whether subdirectories of _Inbox are included. The triage-workflow sentence adds genuine context beyond the structured fields, which earns partial credit.

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

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

Two short sentences, front-loaded with the core action and its scope, followed by the follow-up step. No filler or restated name.

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?

Return values are covered by the output schema, so the remaining gaps are behavioral and parametric: recursion, result limits, and preview_chars meaning. Adequate to call the tool, but not complete for a tool whose parameter is entirely undocumented.

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?

preview_chars has 0% schema description coverage and the description never mentions it. 'Short content preview' gestures at controllable preview length but does not state units, defaults, truncation behavior, or acceptable ranges, so the single parameter remains effectively 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 ('List'), resource ('files'), and a narrow scope ('_Inbox'), plus an output shape ('short content preview'). This differentiates it in practice from kb_list_tree's whole-tree listing and kb_search, though 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?

Explicitly describes the downstream workflow: use previews to pick a target category and new name, then call kb_move_file. That is a clear when-to-use signal, but it gives no exclusions or guidance on when kb_list_tree or kb_search would be preferred instead.

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

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

With no annotations, the description carries the full disclosure burden. It does explain what each retrieval mode actually does internally (BM25/substring, embeddings, rank-fused), which is real behavioral value, but it never states that the operation is read-only, says nothing about result ordering/limits beyond top_k, or what happens on an empty or stale index.

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

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

Purpose is front-loaded in the first sentence, then each parameter gets one compact line with no filler. The Sphinx :param markup is slightly noisy but does not waste the reader's attention.

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-value documentation is not required, and all three inputs are covered including their semantics. The only shortfall is procedural context: no note on whether the index must be refreshed first or how this relates to document-reading siblings.

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 supply all parameter meaning — and it does: query is a natural-language question or keywords with Chinese/English support, top_k is bounded 1–30, and mode's three values are enumerated with their underlying mechanics plus a recommendation. Only minor gaps remain (no default values restated, no query-length or performance caveats).

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 — 'Search the knowledge base' — plus the return shape ('most relevant text chunks'). It is clearly distinguishable from siblings like kb_reindex or kb_read_document, though it never names them 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 only guidance is the recommendation that 'hybrid' is the preferred mode. There is no statement of when to search versus reading a document directly via kb_read_document, nor any prerequisite about index freshness that the presence of kb_reindex/kb_scan_inbox implies.

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

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

With no annotations provided, the description must carry the behavioral burden. 'Report' implies a non-mutating read operation and the sentence discloses the two checks performed, but it does not explicitly state safety, permissions, or error behavior when the drive is not mounted.

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 wasted text. It states the core behavior immediately and is appropriately sized for a zero-parameter status tool.

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 zero-parameter status tool with an output schema, the description is largely complete: it says what is reported and does not need to explain return values. The main remaining gap is that it does not clarify its relationship to kb_health_check.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to explain parameter semantics, and the empty input schema is self-contained.

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 clear verb, 'Report', and names the two things reported: drive mount status and basic index statistics. It is specific about what the tool does, but it does not differentiate this status check from the sibling kb_health_check.

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

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

The description gives no explicit guidance on when to use this tool rather than alternatives such as kb_health_check. Usage is only implied by the word 'Report', with no conditions, exclusions, or 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?

With no annotations, the description carries the behavioral burden and does well by disclosing that the write is atomic via temp file plus rename, preventing truncated indexes on interruption. It still omits prerequisites such as whether the root directory must exist and whether manual edits are overwritten.

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

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

Two short sentences with zero waste. The main action is front-loaded, and the atomic-write detail follows immediately as supporting context.

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 tool is simple, has no parameters, and has an output schema, so the description does not need to explain return values. It covers the core operation and the key safety behavior, though it leaves the relationship to kb_reindex unclear.

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 there are no parameter semantics to explain. The description correctly adds no irrelevant parameter detail, matching the baseline for a parameterless 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 names a specific verb and resource: regenerate the root INDEX.md from current directory contents. It does not, however, distinguish this from the sibling kb_reindex, which likely has overlapping semantics.

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 states what the tool does but gives no explicit guidance on when to use it, when not to use it, or how it differs from kb_reindex. An agent must infer usage entirely from the name and the phrase 'from the current directory contents'.

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