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

With no annotations, the description carries the full burden and does so well: it discloses the write location and naming convention, the YAML header, immediate searchability, INDEX.md refresh, and the dedup short-circuit returning `duplicate: true`. The notable gap is filename collision with different content — the description never says whether an existing same-named file is overwritten, which is the key risk for a write tool.

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

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

Front-loaded with the effect and the output path, then parameters in a scannable block. The `:param:` lines restate some of the opening sentence, but each adds an example or default, so little is truly wasted.

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 seven-parameter mutation tool with no annotations, the description covers side effects, dedup semantics and parameter formats, and the output schema handles return values. The one thing an agent still cannot answer is what happens when the target filename already exists with different content.

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: all seven parameters are addressed, including `allow_duplicate` in the prose. It adds format guidance absent from the schema — date as YYYY-MM-DD with today as default, category examples with a created-if-missing note, and tag/source examples in realistic (including non-English) forms.

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 ('Save text') and immediately enumerates the concrete inputs it handles (notes, pasted data, web clips, chat excerpts). It also spells out the resulting artifact path pattern ``<category>/<YYYY-MM-DD>_<title>.md``, which separates it from file-oriented siblings like kb_import_file or kb_move_file.

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 enumerated scenarios make the intended use case clear, and the duplicate branch tells the agent what to expect on a repeat call. It stops short of explicit exclusions such as 'use kb_import_file for files already on disk', so the boundary with siblings is inferred rather than stated.

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

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

With no annotations, the description carries the full 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?

With no annotations, the description must carry the full behavioral load. It usefully discloses the ordering ('largest first'), the dedup hash, and that deletion is deferred to kb_trash, implying this call is non-destructive. It is silent on cost/scope of the hashing pass and on how the limit bounds the result set.

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 filler: the first defines the output and ordering, the second defines the intended action. Front-loaded and easy to parse.

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 explanation is not required, and the mutation path is correctly outsourced to kb_trash. However, for a tool that hashes an entire library, the missing scope and limit semantics leave an agent guessing at the practical meaning of a call.

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

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

There is one parameter (limit) with 0% schema description coverage, and the description never mentions it. The agent cannot tell whether limit caps the number of groups or the number of files, nor what units apply — the only hint is 'largest first', which addresses ordering, not the limit.

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

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

States a specific verb and resource (list groups of files) plus the exact matching criterion (identical content via SHA-256) and the ordering (largest first). This is clearly distinguishable from siblings like kb_search or kb_list_tree, which do not do content-level dedup.

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 frames the follow-up workflow: keep one per group and remove the rest with kb_trash, naming the sibling that performs the destructive step. It gives clear positive guidance but no exclusions (e.g. when not to dedup, or whether this covers the whole library).

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 safety burden itself, and it does disclose the consequential behavior: fix=True indexes missing files and rewrites INDEX.md. It also bounds the mutation by saying the inbox backlog is not touched. It omits idempotency and whether rewrite is destructive to custom INDEX.md content.

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 plain-English summary is front-loaded, and the second paragraph's parenthetical labels (backlog, orphans, dead links) compress four report categories into one sentence without wasted words. The closing note about the inbox earns its place by clarifying scope.

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 formatting needn't be explained, and the description covers the audit categories plus the fix-mode lifecycle (report, repair, report again). The main remaining gap is max_items and whether repeated fix runs are safe.

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 define both parameters. It explains fix=True well (indexes missing files, rewrites INDEX.md, re-reports), but max_items is never mentioned, leaving the agent to guess whether it caps report entries per category or overall.

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 ("Audit the knowledge base") and enumerates exactly what the audit reports: inbox backlog, orphans, dead links, and unindexed text files. That level of detail makes it distinguishable from kb_status and kb_reindex, though it never names those siblings explicitly.

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

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

It clearly states the conditional mode ("with fix=True also repair what it can") and what fix does versus what it deliberately leaves alone ("The inbox backlog is left for you to organise"). It does not, however, name an alternative tool for the unfixed inbox work (e.g. kb_organize or kb_scan_inbox).

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

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

With no annotations, the description carries the full burden and does substantial work: it discloses that text-bearing files become searchable immediately while images/video are only stored and indexed in INDEX.md, that identical content is skipped (naming the ``skipped_duplicates`` result key), and that `move` deletes the source. It omits failure modes, permission/auth requirements, and size or batching limits.

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

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

Front-loaded with the operation and its constraints, then a compact param block. The Sphinx-style :param markup duplicates names already in the schema, costing a little density, but no sentence is wasted.

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 re-explained; the description still surfaces the one result key an agent must handle (``skipped_duplicates``). Combined with source-scope rules, dedupe behavior, and move semantics, an agent has everything needed to invoke this 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 0%, so the description must compensate, and it documents all five parameters with meaning beyond their types: source_path as an absolute path with a concrete example, category as the target drive folder with default '_Inbox', new_name preserving the extension, move's deletion semantics, and allow_duplicate overriding the dedupe rule.

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

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

States a specific verb and resource ('Copy a file or a whole folder ... into the knowledge base') and clarifies the source machine ('from this Mac'), which implicitly separates it from drive-internal tools like kb_move_file. It never names a sibling as an alternative, so the differentiation is inferred rather than explicit.

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

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

Gives concrete usage context: allowed source locations (~/Downloads, ~/Desktop, ~/Documents, ~/Claude, iCloud Drive, KB_IMPORT_DIRS) and what happens per file type. It does not say when to prefer kb_add_note, kb_scan_inbox, or kb_move_file instead, so the exclusion guidance is absent.

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

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

No annotations exist, so the description carries the full burden. It does disclose two real behavioral traits beyond the name: output is depth-limited and truncated at a max of 600 lines. It omits ordering, whether hidden entries are included, and what happens for a nonexistent subdir — all relevant to a listing 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?

A single front-loaded sentence with zero filler; the output cap is placed immediately after the action description.

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

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

An output schema exists, so return structure need not be described, and the 600-line cap covers the main behavioral surprise. However, with 0% parameter coverage and no annotations, the description leaves the two parameters' meaning and error behavior under-specified for an agent picking defaults.

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 should compensate for two undocumented params. It references `subdir` and implies a depth limit, but never explains what the `depth` value means (default 2), nor that `subdir` defaults to '.' or how it resolves relative to the knowledge base root.

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

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

States a specific verb+resource (list the directory tree) and scopes it to `subdir`, which separates it from content-oriented siblings like kb_read_document and kb_search. It does not explicitly contrast with kb_create_directory or kb_read_document, so the differentiation is only implicit.

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

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

There is no when-to-use guidance and no mention of alternatives or prerequisites (e.g. whether the subdir must already exist or how this differs from kb_read_document for browsing). The agent must infer usage from the tool name alone.

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

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

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?

No annotations are provided, so the description carries the full burden. It does disclose two valuable side effects — the search index stays in sync and INDEX.md refreshes automatically — but never states what happens on a destination collision (overwrite vs. error) or whether the target directory must already exist, which are important for a mutation tool.

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

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

The purpose and the sibling routing are front-loaded in the first two lines, and the parameter notes are compact. The Sphinx-style ':param' markup is slightly verbose but each line carries real 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?

All three parameters are semantically explained, an output schema exists so return values need no elaboration, and the automatic index/INDEX.md behavior is stated. The main remaining hole is overwrite/concurrency behavior at the destination.

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 largely does: src_rel gets concrete path examples including the folder case, dest_dir_rel gets an example directory, and new_name explains that the extension is retained when omitted. It does not clarify whether paths are vault-relative or absolute, nor whether dest_dir_rel must pre-exist.

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 ('Move (and optionally rename) one file or folder') and adds a secondary capability ('restores items from _Trash'). It explicitly routes bulk work to kb_organize, but does not distinguish the rename capability from the sibling kb_rename_file, leaving a minor 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?

Clear guidance for the single-vs-bulk decision ('For many, use kb_organize') and a useful note that this also covers restoring from trash. It stops short of an explicit rule for when to rename via kb_move_file versus kb_rename_file.

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 load and does disclose non-obvious behavior: items are processed independently, failures are reported per item (i.e. partial success is possible), and there is a hard cap of 200 items per call. It stops short of overwrite/collision semantics and whether destination directories are auto-created, which matters for a mutation tool.

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

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

Batch capability is front-loaded in the first clause, followed by the item shape, then the failure and size semantics. Every sentence carries distinct information and the example does the work of a paragraph of prose.

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

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

An output schema exists, so return values need not be explained, and per-item failure reporting is covered. However, for a destructive-ish batch mutation with zero annotations, an agent still lacks answers on overwrite behavior and on whether target directories must pre-exist (kb_create_directory exists as a sibling, hinting they may not).

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 single 'moves' parameter is a free-form object with additionalProperties: string, so the schema documents nothing. The description compensates well by naming dest_dir, marking new_name optional, and showing a concrete item literal. It never explicitly defines 'src' beyond the example, nor whether paths are relative to the KB root, keeping it just under 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?

A specific verb pair (move/rename), an explicit scope ('many files in ONE call'), and a worked example that names the sibling that produces the inputs (kb_scan_inbox). The word 'many' plus 'in ONE call' implicitly separates it from the single-file siblings kb_move_file/kb_rename_file, so an agent can pick it without opening both schemas.

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

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

The parenthetical 'e.g. everything from kb_scan_inbox' sketches the intended scenario, which is real guidance. But it offers no exclusions or explicit comparison against kb_move_file or kb_rename_file, and no prerequisites (e.g. whether dest_dir must already exist). Usage 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?

No annotations are provided, so the description carries the full burden, and it does disclose the single most important non-obvious trait: long documents are paged, with the instruction to re-call using `start_char` when `next_start_char` appears. It does not cover error behavior (missing/unreadable path) or confirmation that the call is a side-effect-free read, but the presence of an output schema lowers the need to describe return shape.

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 core behavior is front-loaded in the first sentence, with paging directly after it since that is the only behavioral surprise. The remaining lines are a compact param block with no filler; every sentence carries information an agent needs to page correctly.

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 three-parameter read tool with an output schema, the definition covers purpose, paging, and all parameter semantics adequately. The remaining omission is procedural context — how to discover a valid `relpath` and what happens on a bad path — which matters for first-time use but not for correct invocation once the path is known.

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 does so fully: `relpath` is defined as volume-root relative with a concrete example (`02_Books/foo.pdf`), `max_chars` gains a valid range (1-50000) absent from the schema, and `start_char` is explained as the paging offset tied to the returned `next_start_char`. All three parameters gain meaning beyond the bare typed schema.

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

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

States a specific verb and resource: returns the extracted plain text of one document, with the intended use ("for quoting/summarising") made explicit. It is distinguishable from sibling kb_search in practice, but the description never names or contrasts an alternative, so differentiation is inferred 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?

Usage is only implied by the parenthetical "for quoting/summarising" and by the paging instruction. There is no guidance on when to prefer this over kb_search, and crucially no hint that a `relpath` must first be obtained via kb_search or kb_list_tree — a real prerequisite gap for an agent that only knows a document name.

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

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

With no annotations, the description carries the burden and does disclose key traits: it runs in the background, blocks for at most wait_seconds, and may return progress rather than a finished result. It does not state cost/duration expectations for a full rebuild, whether the call is safe to interrupt or run concurrently, or whether the index is left inconsistent if aborted.

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

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

Front-loaded with the action, then when-to-use, then runtime behavior, then params — a sensible order. Minor waste: the wait_seconds explanation in the body is repeated almost verbatim in the :param line.

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

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

An output schema exists, so return-value shape need not be described, and the description still covers the one return nuance that matters — it may return partial progress. When-to-use, async behavior, follow-up tool, and both parameters are all addressed for a 2-param optional-args 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 coverage is 0%, so the description must compensate, and it largely does: `full` is explained as re-extracting every file vs only changed ones, and `wait_seconds` is explained plus given the 0-50 range that the schema lacks. It omits the documented defaults (false / 40) and does not say what happens if wait_seconds is exceeded beyond 'returns progress'.

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 — 'Scan the whole drive and bring the search index up to date' — which is clearly distinct from siblings like kb_scan_inbox (inbox only), kb_status (read progress), and kb_search (query). An agent can route to 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?

Explicitly says it is 'Rarely needed' because imported/moved files index immediately and a catch-up scan runs on plug-in, then names the two conditions that do warrant it (bulk Finder copy, full=True rebuild). It also routes to kb_status as the follow-up tool for the progress case.

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?

With no annotations, the description must carry the behavioral load. It does disclose a real constraint — 'Returns at most ``limit`` items per call' — signaling truncation and the need to page. But it never explicitly declares the read-only nature, what previews look like when truncated, or whether subdirectories appear; for an unannotated tool that leaves meaningful gaps.

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 capability front-loaded and the follow-up action second; nothing is padded. Slightly compressed formatting (docstring line breaks) costs it a point.

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 needn't be described, and the description covers purpose, triage pattern, and the downstream batch call. Missing only edge-case behavior (empty inbox, truncated previews, non-file entries) for full completeness.

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 for two undocumented params. It explains `limit` semantically ('at most limit items per call') and implies `preview_chars` via 'short content preview', but never names or bounds the preview parameter. Partial compensation only.

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) plus resource (files in `_Inbox`) and the differentiating trait (short content preview for triage), which separates it from generic siblings like kb_list_tree and kb_search. It stops short of naming an alternative outright, 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?

The second sentence gives an explicit workflow: decide category and name per item, then batch the moves with ONE kb_organize call. That tells the agent both what this tool is for and which sibling to invoke next. It does not state when *not* to use it (e.g. for files outside _Inbox), so not a 5.

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

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

No annotations exist, so the description carries the full burden, and it delivers: it discloses the AND-matching rule, the partial-match fallback with its source tag, and filename matching. It doesn't mention ranking, pagination, or cost/latency differences between 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 behavior is front-loaded in two tight sentences, then parameter docs. The ':param' docstring residue is slightly noisy but each line adds real 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?

With an output schema present, the description needn't explain return values, and it covers matching semantics and all parameters. It stops short of explaining folder recursion and how hybrid mode ranks results.

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 documents all four parameters: a query example including non-English terms, top_k bounded 1-30, the three mode values with the env-var requirement, and a folder example. It fully compensates for the empty schema.

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

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

States a specific verb and resource ('Search the knowledge base and return the most relevant text chunks') and explains the matching model. It does not distinguish itself from kb_read_document, the closest sibling for retrieving KB content, 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?

It gives useful selection guidance for the mode parameter ('semantic' needs KB_ENABLE_SEMANTIC, default hybrid) and the fallback to keyword-partial when nothing matches. It never says when to use this instead of kb_read_document or kb_list_tree, so the routing decision is left to inference.

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

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

With no annotations, the description carries the full behavioral burden and does well: it states the tool never errors, responds within a few seconds, and enumerates the possible state values with hint guidance when status is not ok. It could be stronger by explicitly confirming read-only/no-side-effect behavior, but the key behavior is 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?

The description is front-loaded with the purpose and follows with behavioral and state-value details. The state enumeration is useful rather than filler, though the prose could be slightly tighter.

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

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

The tool has zero parameters and an output schema, so the description need not explain return values in detail. It still documents state values and hint behavior, making the definition largely complete, with only the sibling distinction and explicit usage guidance 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 parameter semantics baseline is 4. There are no arguments for the description to clarify.

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 verb and resource: it reports knowledge-base drive state, index statistics, and job progress. It does not explicitly distinguish itself from the sibling kb_health_check, so while purpose is clear, sibling differentiation is missing.

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

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

Usage is implied by the status/reporting framing, and the description says it always answers quickly. However, it gives no explicit when-to-use guidance, no when-not-to-use conditions, and does not name alternatives such as kb_health_check.

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

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

With no annotations, the description carries the burden well: it discloses the destination (_Trash/<today>/), that the item is not indexed and not in INDEX.md, and that the action is reversible via kb_move_file. It omits any permission/auth or side-effect details on the index, but the core behavioral profile is solid.

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

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

Front-loads the core action and recoverability, then adds destination and restore/cleanup guidance with no filler. The param lines are compact and useful.

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 not be described, and the description covers mechanics, destination, and restoration for a 2-param mutation tool. It is nearly complete, missing only explicit auth/permission context.

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

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

Schema coverage is 0%, so the description must compensate, and it does: it gives a concrete relpath example ('03_Notes/重复的笔记.md') and clarifies that reason is an optional note for the organize log. Both parameters gain meaning beyond the bare schema.

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

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

States a specific verb (remove) and resource (file or folder in the knowledge base) with the key qualifier 'recoverably'. The recoverable framing distinguishes it from a permanent delete, though no sibling is a direct delete equivalent.

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?

Explains the recovery path (use kb_move_file to restore, empty _Trash in Finder when certain) which implies this is a soft-delete, giving clear usage context. It doesn't explicitly contrast with other mutation siblings like kb_rename_file or kb_organize, so when-not guidance is only implied.

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

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

With no annotations, the description carries the burden and does add real value: it discloses the atomic write strategy (temp file + rename) and the failure characteristic (no truncated index on interruption). It stops short of saying whether manually edited content in INDEX.md is overwritten, which matters for a regenerating write.

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, zero filler, and the primary action is front-loaded in the first clause. The atomicity note is the only secondary detail and it is genuinely useful.

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

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

For a zero-parameter tool with an output schema, the description covers the action, its redundancy with automatic refresh, and write safety. The remaining gap is the relationship to kb_reindex and whether existing INDEX.md content is replaced wholesale.

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 to disambiguate and the baseline of 4 applies. The description correctly spends no words on parameter semantics.

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: regenerate the root INDEX.md. An agent knows exactly what file is affected. It does not, however, differentiate itself from the sibling kb_reindex, leaving a small ambiguity about which one rebuilds what.

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 '(it also refreshes automatically)' implies this call is usually unnecessary unless the caller needs the update immediately, which is useful implied guidance. But there is no explicit when-to-use rule and no mention of when kb_reindex would be the right alternative.

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