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

With no annotations, the description carries the burden. It clearly indicates the tool modifies an existing note (implying it does not create new ones) and the .md-only constraint. However, it does not detail edge cases such as behavior when the note does not exist, whether the separator is added automatically, or the return value. This is a minor gap but acceptable for a simple append 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 description is extremely concise, consisting of two short sentences. It delivers the essential information without any fluff or redundancy. The constraint about .md is stated efficiently.

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

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

Given the simplicity of the tool, the description is mostly complete. It explains the core action and the file type restriction. However, since no output schema is provided and no return value or error behavior is mentioned, an agent might not know whether the tool returns the updated note or a success status. This is a minor omission that could affect slightly more complex use cases, but for a basic append operation, the description suffices.

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

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

The schema covers all three parameters with clear descriptions, achieving 100% coverage. The tool description adds an extra constraint ('Only .md is supported') beyond the schema, which provides additional context for the path parameter. No parameter is left unexplained, and the meaning is clear.

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

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

The description clearly states the tool's function: 'Append content to an existing Markdown note.' It specifies the resource (Markdown note) and the action (append), and the constraint 'Only .md is supported' further clarifies scope. This distinguishes it from siblings like write_note or create_note.

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

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

The description implies usage for adding to an existing note but does not explicitly state when to prefer this over alternatives like write_note or create_note. The constraint about .md files is mentioned, but no direct comparison or when-to-use guidance is provided. The agent must infer from the name and sibling list.

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

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

The description discloses that results are scoped to the current process, data set, configuration, and runtime, which is a useful behavioral caveat. However, it does not explicitly mention side effects or that it is non-destructive, especially given no annotations are present.

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

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

The description is two sentences with no redundancy. It front-loads the primary purpose and then clarifies the result 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?

The tool has a simple input schema and the description sufficiently conveys its purpose and result nature. It lacks explicit output details, but given the tool's simplicity and no output schema, it is adequately 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?

Both parameters have descriptions, but they are terse and add minimal meaning beyond the parameter names. The schema coverage is 100%, so the baseline is 3; the descriptions provide only slight clarification.

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

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

The description clearly states a specific action ('Measure local search latency') that distinguishes it from sibling search tools that actually perform searches. It is concise and unambiguous.

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

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

The description does not provide guidance on when to use this tool versus the many sibling search and indexing tools. It implies a benchmarking use-case but never explicitly states conditions or alternatives.

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

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

With no annotations, the description carries the burden of behavior; it discloses that the tool merges small fragments, removes obsolete versions, and returns compaction statistics, though it does not mention potential side effects like locking or temporary query impact.

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

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

The description is brief, front-loaded with the core action, and each subsequent sentence adds meaningful detail about behavior and return value without fluff.

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

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

Given the tool's simplicity (no parameters, no annotations, output schema present), the description adequately covers purpose, mechanism, and return value; it only omits edge cases like index-not-found or when compaction is unnecessary.

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 default baseline is 4; no parameter explanation is needed and the empty schema is consistent.

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

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

Description clearly states a specific action ('Compact') and resource ('LanceDB index'), and distinguishes it from sibling tools like reindex_vault by emphasizing fragment merging and obsolete version removal.

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 mentions 'after incremental mutations' as a usage context, but never explicitly contrasts compact_index with alternatives such as reindex_vault or vector_index_status, leaving some guidance implicit.

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 burden of explaining behavior. It transparently states the failure condition (existing note causes failure) and the file format restriction (.md only). However, it does not mention the return value or any side effects like indexing, which could be considered minor omissions.

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

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

The description is extremely concise—two short sentences—and covers all essential details: the action, the condition, and the format constraint. There is no redundant or filler content, making it easy for an agent to parse and understand quickly.

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

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

Given the tool's simplicity and the presence of an output schema (though not shown), the description is adequate. It does not explicitly mention the return value, but the action is straightforward and the schema likely covers that. The description is sufficient for an agent to invoke the tool correctly without needing additional context about side effects or related operations.

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

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

The input schema provides clear, complete descriptions for all three parameters: path (vault-relative path with example), content (body without frontmatter), and optional frontmatter (YAML metadata). The 100% schema coverage means each parameter is well-defined, leaving no ambiguity about its meaning or format.

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

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

The description clearly states the action (create a Markdown note), the resource (a note), and a key condition (fail if it already exists). It also specifies the supported format (.md), making the tool's purpose unambiguous and distinct from sibling write 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 usage for creating new notes without overwriting, but does not explicitly say when to use this tool instead of alternatives like write_note or append_note. The 'fail if already exists' condition hints at the use case, but there is no direct comparison or guidance for selection among sibling tools.

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

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

With no annotations provided, the description carries the full burden. It mentions the YYYY-MM-DD.md convention, which is useful, but it does not disclose whether the operation is read-only, what happens if the note does not exist, or what 'information' includes beyond the output schema. This is a notable gap for a tool with no 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?

Two sentences with no redundancy: the first states the core purpose, the second provides the naming context. The description is front-loaded and every word earns its place, making it highly efficient.

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

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

For a simple two-parameter read tool, the description is somewhat adequate but lacks behavioral guarantees like read-only status and error behavior. Since there is an output schema, return structure is covered, but the absence of annotations means the description should be more explicit about side effects and edge cases.

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

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

The input schema covers both parameters (date and folder) with defaults and descriptions, so the baseline is 3. The description adds the file naming convention, which is a minor clarification on the date format but does not significantly enhance understanding beyond the schema.

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

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

The description clearly states the tool returns information about the daily note for a specific date, with a concrete naming convention. It is not a tautology and is specific enough, but it does not explicitly differentiate from sibling tools like read_note or get_note_metadata, so it falls short of a 5.

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

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

There is no guidance on when to use this tool versus alternatives. The description only states what it does, not the context in which it is the preferred choice over, say, read_note or get_note_metadata, nor any exclusions.

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

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

The description discloses the key side effect: files are recoverable and permanent deletion is unsupported. However, it does not mention other potential effects such as permissions, related index updates, or what happens if the path doesn't exist. Since no annotations are provided, the description carries the full burden, but it covers the most critical behavioral aspect.

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 concise, using just two sentences to convey the action and the recoverability aspect. No extraneous information is included, making it well-structured 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?

The description explains the core behavior and the recoverable nature, which is sufficient for a simple delete operation. However, it does not mention the return value or error behavior, though the presence of an output schema (indicated in context) may reduce the need for that. Overall, it is reasonably complete but could benefit from a note about the output or failure scenarios.

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

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

The only parameter 'path' is described as 'path relative to the vault', which is clear and sufficient. The schema coverage is 100%, so all parameter semantics are fully explained.

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

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

The description clearly states the tool's function: deleting a note by moving it to trash, and clarifies the scope (md, pdf, canvas) and the non-permanent nature. The verb 'delete' and resource 'note' are explicit, leaving no ambiguity about what the tool does.

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

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

The description explains the behavior (move to trash, recoverable) but does not explicitly mention when to use this tool over alternatives like write_note or create_note. It implies a safe deletion use case but lacks direct guidance on selection criteria.

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

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

Discloses that the operation is enqueued and returns a job id, but does not mention that it will modify note files or what happens on failure. Since no annotations are provided, more detail about side effects would improve transparency.

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

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

Two sentences, no filler, and the key async semantics are front-loaded. The pointer to the status tool is a concise and useful addition.

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?

Provides enough context for a simple async job: it returns a job id and points to the status tool. It lacks details about output schema or required inputs, but for a background enqueue operation the description is largely sufficient.

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

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

Each parameter has a short description ('optional single note', 'folder selection limit'), but the interplay between path, paths, and folder is unclear, and all parameters are optional with no explanation of default behavior when none are 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?

Clearly states the action ('Enqueue'), the resource ('required-frontmatter enrichment'), and the async/background nature. It also distinguishes itself from the sibling status tool by directing users to enrich_frontmatter_status for 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?

Explicitly describes the async workflow: enqueue, get a job id immediately, then check status. It could be stronger by noting when to prefer this over direct frontmatter edits, but the intended usage is clear.

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

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

No annotations are provided, so the description carries full responsibility. It only says 'Return the status' without disclosing error handling, side effects, or edge cases (e.g., job_id not found, invalid limit). The behavior is underspecified.

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

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

The description is a single concise sentence that directly states the function. It is well-structured and to the point, though it could include more detail without becoming verbose.

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 but lacks context about the output format or status values, and the output schema is not provided. An agent would need additional information to interpret the response correctly, so the description is incomplete.

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?

Both parameters are fully described in the schema (limit for number of recent jobs, job_id as optional). The tool description adds no additional meaning, and schema coverage is 100%, so a baseline of 3 is appropriate.

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

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

The description clearly states the tool returns the status of frontmatter enrichment jobs, which is a specific verb and resource. It is distinct from the sibling tool 'enrich_frontmatter' that performs the enrichment action, so the purpose is unambiguous.

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

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

Usage is implied through the parameter descriptions (limit for recent jobs when job_id omitted, job_id for a specific job) but there is no explicit guidance on when to use this tool versus alternatives, such as when to check status vs. trigger enrichment.

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, and the description does not disclose whether the operation is read-only, potentially expensive, or has any side effects. The user is left without information about performance or safety implications.

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 concise, with the main action in the first sentence and a clarifying explanation in the second. There is no unnecessary verbosity or redundant 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?

The description is adequate for a simple graph-analysis tool, but it lacks context about expected output, edge cases, or how it relates to other graph tools. Given the tool's simplicity, the provided information is acceptable but not fully complete.

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

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

The input schema descriptions for 'limit' and 'folder' are present and cover 100% of parameters, so the baseline is met. The tool description itself adds no extra meaning about how these parameters affect the articulation point computation, but the schema is sufficient.

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

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

The description clearly states the tool finds articulation points in the note graph, and the second sentence explains the graph-theoretic meaning. It is specific enough to distinguish it from general search or stats tools, though the name 'bridge' vs 'articulation point' could cause slight 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?

The description does not explicitly say when to use this tool versus alternatives like find_link_clusters, graph_data, or link_stats. It only defines what the tool does, leaving the user to infer appropriate use cases.

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 burden of behavioral transparency. It mentions 'rebuildable link index' but does not disclose side effects, read-only behavior, potential staleness of the index, error conditions, or performance characteristics. The behavioral trait described ('is_resolved=false') is more of a definition than a disclosure of tool behavior.

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

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

The description is two concise sentences with no filler or irrelevant detail. It is well-structured and front-loads the primary purpose before adding a technical clarification about the link index.

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

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

Given the tool's simplicity, the presence of a schema describing both parameters, and the existence of an output schema (which removes the need to describe return values), the description is largely complete. Minor context about the 'rebuildable link index' could be expanded, but it does not prevent correct usage.

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

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

Schema coverage is 100% for both parameters, with clear descriptions in the schema ('limit' as maximum returned notes, 'folder' as optional folder filter). The tool description does not add additional semantic meaning beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states a specific verb ('Find') and resource ('links that point to missing notes'), distinguishing this tool from sibling tools like get_outlinks, find_orphan_notes, and link_stats. It is immediately obvious what the tool does.

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

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

The purpose implicitly suggests when to use the tool (when you need broken links), but it does not explicitly contrast it with alternatives or state conditions for choosing it over similar tools like find_orphan_notes or link_stats. Usage guidance is 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It reveals the connected-components algorithm but does not state whether the operation is read-only, what side effects might occur, or any performance implications. The existence of an output schema reduces the need to describe return format, but the description still lacks explicit safety or side-effect information.

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

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

The description is extremely concise: two sentences with no filler. The primary purpose is front-loaded, and the algorithmic detail is placed second, which is optimal for scanning. Every word adds value.

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

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

Given the presence of an output schema, the return format does not need description. The two optional parameters are well-covered by the schema, and the description explains the tool's core function and method. The only gap is the lack of explicit read-only confirmation, but that is a minor omission for a 'detect' tool. Overall, it is adequate for correct invocation.

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

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

Schema description coverage is 100%, and both parameters (folder, min_cluster_size) already have descriptive text in the schema. The description adds no extra meaning beyond what the schema provides, so the baseline of 3 applies—it neither enhances nor harms parameter 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 states a specific verb and resource: 'Detect clusters of densely connected notes.' It further clarifies the algorithmic approach ('Uses connected components') and the intended outcome ('find isolated knowledge groups'). This distinguishes it from sibling tools like find_similar_notes (similarity-based) and find_orphan_notes (unlinked notes), though it doesn't explicitly name alternatives.

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

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

The description implies usage for detecting isolated clusters but provides no explicit guidance on when to choose this tool over alternatives like link_stats or graph_data. There are no exclusions or scenarios where a different tool would be more appropriate, leaving the agent to infer context.

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 of disclosing behavior. It states the tool 'finds' notes, implying a read-only operation with no side effects. However, it does not disclose potential caveats such as whether results are sorted, whether the index must be fresh, or whether orphan detection is based on full graph analysis vs. direct backlinks only. The behavior is generally clear but not exhaustive.

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

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

The description consists of two short sentences with no redundant information. The first sentence directly states the function, and the second clarifies the graph context. It is exceptionally concise while remaining informative.

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

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

For a simple read-only find tool, the description is adequate. It covers the essential behavior and the output schema exists (as indicated by context signals), so return values are not required. Minor details like sorting order or index freshness are not mentioned, but these are not critical for correct usage. Overall, it is complete for practical purposes.

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

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

The schema provides complete descriptions for both parameters ('maximum returned notes' and 'optional folder filter'), achieving 100% coverage. The description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate. There is no ambiguity in parameter intent.

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

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

The description clearly states the tool's purpose: finding notes with no backlinks. It additionally explains the concept in graph terms ('isolated from incoming graph edges'), which reinforces the meaning. It does not explicitly distinguish from sibling tools like find_bridge_notes or find_link_clusters, but the core function is unambiguous.

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

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

The description does not provide any guidance on when to use this tool versus alternatives. It simply states what the tool does, without mentioning prerequisites, typical scenarios, or when another tool might be more suitable. This leaves the agent without explicit decision support.

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

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

The description explains the mechanism (averaging embeddings and searching semantically), indicating a read-only operation. However, it does not explicitly state side effects, output shape, or any limitations, and there are no annotations to supplement this.

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 concise, using two sentences to convey purpose and method without unnecessary information. It is well-structured 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?

The description is adequate for an agent to call the tool correctly, especially given that an output schema exists. It could mention typical use cases or output format, but it is not necessary for basic 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?

The schema descriptions for 'path' and 'top_k' are present and clear. The tool description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate given full schema coverage.

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

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

The description clearly states the tool finds notes similar to a specific note, using a distinct method (embedding averaging and semantic search). This distinguishes it from sibling search tools like search_advanced or search_duplicates.

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

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

No explicit guidance is provided on when to use this tool versus alternatives. While the purpose implies it is for finding similar notes to a given note, there is no direct comparison or conditions for choosing this over search_advanced or suggest_links.

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 of transparency and does disclose a meaningful implementation detail: it uses SQLite catalog and avoids filesystem scans. 'Return' also implies a read-only operation, although it does not explicitly enumerate side effects.

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 concise and front-loaded, with the primary purpose stated in the first sentence and only one additional clarifying sentence. No unnecessary words or repetition.

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

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

The description is sufficient for a simple read-only folder-tree tool, and it states the output shape as a hierarchy. It does not mention edge cases or response details, but no output schema is provided and the operation is straightforward.

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?

Both parameters are described in the schema, so coverage is complete. The descriptions add only marginal detail beyond the parameter names, with 'max_depth' being somewhat vague ('bounded by configuration').

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

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

The description clearly states a specific verb and resource: returning the vault folder structure as a hierarchy. It is distinct from sibling tools like search or list operations, though it does not explicitly contrast itself with them.

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

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

The statement about using the SQLite catalog without scanning the filesystem gives an implicit performance-related use case. It does not explicitly say when to prefer this tool over alternatives or when not to use it.

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

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

With no annotations provided, the description carries the full transparency burden. It clearly indicates that the tool modifies notes ('Add ids') and explains that dry_run lists notes without modifying them, effectively disclosing its destructive and non-destructive modes. It could be more explicit about the irreversible nature of the write operation, but it is largely transparent.

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 concise and well-structured, consisting of two short sentences. It front-loads the core purpose and includes a supplementary detail about UUIDv7 ordering. No unnecessary words or redundancy.

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

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

Given the output schema exists, the description does not need to explain return values. It provides enough context about the operation, the dry_run behavior, and the technical standard (RFC 9562) for an agent to understand when and how to use the tool. The description is complete for this simple 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?

Both parameters (folder and dry_run) have schema descriptions, and the schema coverage is 100%. The description adds minimal extra meaning beyond the schema, only repeating 'optional folder scope'. According to the baseline rule for high schema coverage, a score of 3 is appropriate.

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

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

The description clearly states the tool's function: adding UUIDv7 ids to Markdown notes that lack a frontmatter id. The verb 'Add' is specific, and the resource and condition are explicitly defined, distinguishing it from sibling tools like update_frontmatter or write_note.

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

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

The description implies usage when notes lack ids and explains the dry_run option, but it does not explicitly contrast with alternatives (e.g., manual updates via update_frontmatter) or state when not to use this tool. This leaves some ambiguity about the recommended context.

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

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

Annotations are absent, so the description carries the full burden. It implies a read-only operation by saying 'find', but it does not explicitly state side effects, error behavior, or limitations beyond the index note.

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 concise sentences with no filler. The main purpose is front-loaded, and the implementation detail is relevant and brief.

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

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

For a simple read-only lookup, the core functionality is covered, and the index behavior is a useful addition. However, it does not describe output shape or limitations, and it does not relate to sibling tools, leaving some context gaps.

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

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

Schema coverage is 100% because both parameters are described. The description adds little beyond the schema: 'path' is already explained as a vault-relative target path, and 'include_context' is already described as including text around the link.

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

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

The description clearly states the verb-resource pair ('Find notes that link to one target note') and scopes the operation to a single target note. It does not explicitly name a sibling alternative like get_outlinks, but the reverse-link focus is evident.

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

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

There is no guidance on when to use this tool versus related tools such as get_outlinks, find_broken_links, or link_stats. The only additional note is an implementation detail about using the rebuildable index, not a usage condition.

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

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

The description uses 'Return' and explicitly says 'without the body', implying a read-only operation with no side effects. This is sufficient in the absence of annotations to convey that the tool does not modify anything.

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 concise and to the point, with no unnecessary words. The two sentences are efficient and cover the tool's purpose and output without redundancy.

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

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

Given there is no output schema, the description provides enough detail (parsed frontmatter, tags, file metadata) to set expectations. It also specifies the file type, making the tool's behavior sufficiently complete for an agent.

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

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

The only parameter 'path' is clearly described in the schema as a vault-relative path with an example. The tool description reinforces that it applies to Markdown notes, fully clarifying the expected input without needing additional explanation.

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

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

The description clearly states the tool returns metadata (frontmatter, tags, file metadata) for a Markdown note, and distinguishes it from read_note and other note operations. It is specific enough for an agent to know exactly what to expect.

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

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

The description explicitly states it returns metadata without the body, making it clear when to use this tool instead of read_note or other note-content tools. The scope is limited to .md files, which is a useful constraint.

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?

There are no annotations to indicate read-only behavior or side effects. The description mentions the 'rebuildable link index' but does not explain whether this tool triggers a rebuild, what happens if the index is stale, or what errors might occur. The read-only nature is implied but not explicitly stated.

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

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

The description is extremely concise, using two short sentences without any redundant information. It front-loads the core action and relevant context about the link index, making it easy to scan and understand.

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 tool with one parameter, the description provides sufficient context about what it does and how it relates to the link index. However, it does not describe the output format or return value, which could be relevant for an agent deciding how to use the result, especially since no output schema is provided.

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

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

The single parameter 'path' is well-described as a vault-relative note path with an example format. This gives the agent a clear understanding of the expected value, though it lacks additional constraints like required extension or path normalization details.

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

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

The description clearly states the tool lists every indexed link from a single note, and the name get_outlinks reinforces the purpose. It is specific about the resource (one note) and the action (list links), though 'indexed link' could be slightly more explicit about whether it includes all outgoing links or only those in the index.

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 provide guidance on when to use this tool versus related tools like get_backlinks, aside from mentioning the same link index. It lacks prerequisites, typical use cases, or conditions under which this tool should be preferred.

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

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

No annotations are present, so the description carries full responsibility for disclosing side effects, permissions, errors, or rate limits. It only mentions that notes are returned and ordered, without explicitly confirming a non-destructive read operation or any other behavioral details.

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

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

The description is extremely concise, using two short sentences with no redundant wording. It front-loads the main action and followed by the key ordering detail.

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

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

For a simple read tool with an output schema, the description covers the essential behavior, but it omits details like how the folder filter works, whether pagination or max limits apply, and what an empty result means. The presence of an output schema mitigates some of this, but a bit more context would improve 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 descriptions cover all three parameters but are terse: 'days' as 'bounded time window in days', 'limit' as 'maximum returned notes', and 'folder' as 'optional folder filter'. Defaults are present in the schema, but the description adds little beyond what the schema already provides.

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

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

Description clearly states the action ('Return') and resource ('recently modified notes'), and specifies ordering by modification time. It does not name sibling tools that might serve a similar purpose, but the core purpose is unambiguous.

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

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

No guidance is given on when to use this tool vs. alternatives like list_notes, search_by_folder, or read_note. The description explains behavior but not the appropriate context or conditions for choosing this tool over others.

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 present, so the description carries the burden. It explains the output kind (node-and-edge graph data) but does not mention side effects, default behavior for orphan inclusion, or whether it is strictly read-only.

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 concise sentences with no redundant detail. It front-loads the action and then gives concrete format 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 description is sufficient for selecting and invoking the tool given the parameter schema and the indication that an output schema exists. It names the output format but leaves exact fields to the output schema.

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

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

Both parameters have clear schema descriptions (folder filter and include orphans), so the schema already provides the needed meaning; the description adds no further parameter context.

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

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

Description clearly states the tool exports link-graph data for visualization, which distinguishes it from link statistics, cluster finding, and backlink tools. The node-and-edge format and target tools make the intended use concrete.

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 frames the tool for visualization use cases and names compatible consumers (D3.js, Obsidian Graph, Gephi), but it does not explicitly contrast it with related graph-analysis tools such as link_stats or find_link_clusters.

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 present, but the description explicitly says it checks and returns, implying a read-only diagnostic operation and listing the areas inspected. It stops short of confirming there are no side effects, but the health-check framing makes the behavior reasonably transparent.

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 with no filler, and the core behavior and return value are front-loaded. The description is directly usable without unnecessary detail.

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

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

For a no-argument health check, the description is complete: it states what is checked and what is returned. The presence of an output schema means detailed return-field documentation is not required in the description.

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

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

The input schema is empty and the description introduces no parameter expectations, which is appropriate since the tool takes no arguments. Baseline 4 applies for zero-parameter tools; no additional parameter semantics are needed.

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?

Clearly identifies the operation as returning a health snapshot for monitoring and specifies the checked subsystems (index, catalog, model state, latency alerts). This distinguishes it from the large set of note, graph, and link-related 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?

States the monitoring purpose, but does not explicitly contrast with alternatives or give conditions for when to call it. For a simple no-argument health check, the intended use is inferable but not explicitly guided.

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

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

No annotations are provided, so the description carries the burden. It says 'Return' which implies a read-only operation, but it does not explicitly state that the tool makes no modifications or has no side effects. The behavioral impact is not fully 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 concise, using two short sentences to convey the purpose and included output categories. There is no redundant or irrelevant 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?

There is no output schema, and the description does not specify the structure of the returned statistics. While it lists the categories, it leaves unclear what 'totals' refers to (e.g., total links, total notes) and how the data is formatted. This lack of detail makes the tool's output ambiguous.

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

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

The only parameter (limit) is fully described in the schema with its default and meaning. The description adds no additional semantic information beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states the tool returns vault link statistics and enumerates the specific categories included (totals, most-referenced notes, and notes with most outlinks). This distinguishes it from sibling tools that focus on individual note backlinks or outlinks.

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

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

The description explains what the tool does but provides no explicit guidance on when to use it compared to alternatives like get_backlinks or get_outlinks. There is no mention of scenarios where this aggregate view would be preferred.

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

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

No annotations are provided, and the description does not explicitly state that the tool is read-only or mention any side effects. Since it is a listing operation, it is likely safe, but the description does not explicitly disclose this, leaving some ambiguity.

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 concise, consisting of two sentences. It conveys the core functionality and important usage caveats without unnecessary fluff, making it highly efficient.

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

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

The description provides enough context for correct usage, including the file type limitations and the pointer to search_vault for PDF/Canvas. It lacks details about return format or default pagination, but those are not critical for basic understanding given the schema.

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

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

The schema covers all four parameters (limit, folder, offset, extension) with clear descriptions. The tool description does not add additional meaning beyond the schema, so the baseline score of 3 applies.

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

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

The description clearly states the tool lists vault notes with filters and pagination. It is specific about the resource and action, and differentiates from search-related tools by implying a listing operation. However, it does not explicitly name a sibling tool in the purpose statement, so a small gap remains.

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

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

The description gives explicit guidance on file type limitations: only .md can be read via read_note, and for PDF/Canvas files one should use search_vault. This effectively tells the user when not to use this tool and points to an alternative, which is strong usage guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the action and two constraints (extension matching and ignored folders), but does not mention overwrite behavior, permissions, or reversibility. For a mutation tool, this is adequate but not exhaustive.

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

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

The description is two short sentences with the action stated first and constraints second. It is front-loaded, has zero waste, and every sentence contributes useful information.

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

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

The description covers the core action and key constraints. With an output schema present, the return value is presumably documented. The only notable omission is behavior when the destination path already exists (overwrite vs error), but this is a minor gap given the concise nature.

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

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

Schema coverage is 100%, so both parameters (from_path, to_path) have descriptions in the schema. The description adds the constraint that source and destination extensions must match, which is not in the schema, and clarifies that ignored folders are blocked. This adds meaningful context beyond the schema.

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

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

The description states a specific action ('Move or rename a note') and clearly identifies the resource. It distinguishes itself from sibling tools like create_note, write_note, and delete_note by specifying the operation and adding constraints (extension matching, ignored folders). The purpose is unambiguous.

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

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

The description does not explicitly compare with alternatives or state when to use it instead of other tools, but the purpose is self-evident from the name and description. It does provide usage constraints (extensions must match, ignored folders blocked) that help an agent decide whether the operation is valid. The lack of explicit 'use this instead of X' guidance is a minor gap.

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

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

The description discloses that random selection is performed via SQLite's random ordering over the filtered catalog, which gives insight into the selection mechanism. However, with no annotations, it does not clarify potential edge cases such as empty results or whether this operation is strictly read-only.

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 exceptionally concise, consisting of two short sentences. The main purpose is front-loaded and the implementation detail is placed second, making it easy to scan.

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 tool with an output schema and fully described parameters, the description provides sufficient context for basic invocation. It lacks usage timing and edge-case behavior, but these are covered under other dimensions and the tool's simplicity reduces the need for more.

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

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

The input schema already provides 100% coverage with descriptions for both parameters ('optional folder filter' and 'optional extension filter, such as .md or .pdf'). The description does not add further semantic detail beyond what the schema supplies.

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

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

The description clearly states the tool's function with a specific verb and resource: 'Return a random vault note.' This distinguishes it from search and retrieval tools by emphasizing randomness.

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 is provided about when to use this tool versus alternatives. It does not mention that this is useful for discovery, sampling, or when a deterministic search is not needed, nor does it exclude any sibling tools.

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

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

The description clearly indicates a read-only operation on a note, with no side effects mentioned. Since annotations are absent, this description carries the full burden and adequately discloses the tool's behavior.

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

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

The description is two sentences, with the primary function stated first and the limitation/alternative second. It is concise, well-structured, and every word adds value.

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

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

Given that the tool has an output schema (as per context signals), the description need not explain return values. It provides sufficient context about the operation, supported file type, and alternative for other types, making it 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?

The only parameter 'path' is described as a vault-relative path with an example, and the description adds that only .md is supported, clarifying the expected input format. The schema coverage is 100%.

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

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

The description explicitly states the tool reads a complete Markdown note with parsed frontmatter, making the purpose unambiguous. It also distinguishes from search_vault for other content types, clarifying its scope.

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 specifies that only .md files are supported and directs users to search_vault for PDF or Canvas content, providing explicit when-to-use and when-not-to-use guidance.

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

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

No annotations are present, and the description does not disclose side effects, idempotency, failure behavior, or whether the operation is safe. It only states what the tool does, not its full behavioral impact.

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

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

The description is a single clear sentence with no redundant words. It is appropriately concise for the tool's simple purpose.

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 single-note reindex operation, the description is adequate, but it does not mention edge cases like missing notes or error handling. Given the tool's low complexity, this is acceptable 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?

The schema fully documents the path parameter with a helpful description and example. The description adds a concrete usage example, slightly improving on the schema's baseline.

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

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

The description clearly states the action (reindex) and the resource (one note), and implicitly distinguishes from reindex_vault by specifying 'one note' rather than the whole vault.

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 versus alternatives such as reindex_vault, though the phrase 'one note incrementally' implies a targeted use 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?

No annotations are present, so the description carries the burden. It implies a mutating operation ('rebuild', 'recreated') but does not explicitly disclose potential side effects like index locking, performance impact, or the fact that it modifies the index. This is a moderate transparency gap.

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 succinct sentences: the first states the tool's purpose, the second gives usage guidance. No redundant or vague wording.

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

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

Given the simple parameter set and presence of an output schema, the description provides enough context for correct invocation. No additional explanation of return values or edge cases is necessary.

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

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

The schema covers 100% of parameters with clear descriptions (dry_run, require_daemon). The description adds no extra meaning beyond the schema, so the baseline of 3 applies.

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

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

The description clearly states the specific action ('Rebuild the complete vault index') and differentiates it from sibling tools like reindex_note by emphasizing 'complete' and 'vault index'. It is unambiguous about the scope and purpose.

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 provides a clear 'when to use' scenario: 'after broad reorganizations or when the rebuildable index must be recreated.' While it doesn't mention alternatives, it gives actionable context, which is sufficient for guiding the agent.

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

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

No annotations are provided, so the description carries the full burden of disclosing behavioral traits. 'Run semantic search' implies a read-only query, but the description does not explicitly state that it performs no side effects, does not mutate data, or is safe to invoke. The behavior is not fully transparent.

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

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

The description is extremely concise, consisting of two short sentences. It communicates the essential operation and filter combination rule without unnecessary words, padding, or repetition.

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

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

Given the tool's complexity (14 parameters) and lack of annotations, the description is somewhat thin. It does not mention expected output behavior, result ordering, or interaction with sibling search tools. The schema parameters are well described, so the missing pieces are mostly contextual guidance rather than parameter-level details.

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

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

The schema description coverage is 100%, with each parameter having a description. The main description adds a useful semantic that all optional filters are combined with AND, which clarifies interaction between parameters. However, it does not go beyond the schema to explain nuanced behaviors like date_range precedence or exclusion semantics in more depth.

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 action: 'Run semantic search with structured filters.' It identifies the resource (semantic search) and mentions structured filtering, making the core purpose understandable. However, it does not explicitly distinguish itself from sibling search tools like search_vault_hybrid or search_vault, so it is not fully differentiated.

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

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

There is no guidance about when to use this tool instead of alternative search tools. The sentence 'Every optional filter is combined with AND' describes filter behavior but does not help the agent decide between this and sibling tools. This leaves usage decisions under-specified.

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

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

The description discloses one key behavioral trait: 'Descendant folders are included by the search backend.' This gives useful information about the tool's scope. However, it does not mention other behaviors such as read-only nature, potential side effects, or permissions, which would be relevant given there are no annotations to fill those 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?

The description is concise—two sentences—and directly addresses the core purpose and a key behavior. There is no redundant or extraneous information, making it easy for an agent to parse quickly.

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

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

Given the simplicity of the tool and the presence of an output schema (not shown but indicated as existing), the description covers the essential purpose and a key scoping behavior. It is slightly incomplete regarding usage context and potential side effects, but these are not critical for a basic search operation. The tool is adequately described for its intended function.

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

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

All three parameters have descriptions, covering 100% of the schema. However, the descriptions are minimal: 'search text', 'number of results', and 'folder filter, such as 'projects' or 'research/python'. They do not elaborate on semantic behavior, default handling (though top_k has a default in the schema), or the expected format of the folder parameter beyond an example.

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

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

The description clearly states the tool's function: 'Search semantically within one vault folder.' It specifies the verb (search) and the resource (vault folder), and emphasizes the folder scoping, which distinguishes it from broader search siblings like search_vault or search_vault_hybrid.

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 provide explicit guidance on when to use this tool over alternatives. It lacks statements like 'use this when you need to search a specific folder' or 'instead of search_vault for whole-vault searches.' The only additional note about descendant folders is a behavior, not a usage recommendation.

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

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

The description clarifies that matching is based on exact tags and not semantic search, giving insight into behavior. Since it is a read-only search, no side effects are expected. Additional details like ordering are not mentioned but are covered by parameter descriptions.

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 concise, consisting of two sentences with no redundant information. It efficiently conveys the core purpose and a valuable usage hint.

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 search tool, the description provides adequate context, including a pointer to tag_stats and a distinction from semantic search. Output structure is not described, but an output schema is present, so that information is accessible.

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

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

All three parameters have clear descriptions in the schema, including an example for tags and explicit explanations for limit and match_all. The tool description itself adds no extra detail, but the schema coverage is complete and informative.

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

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

The description clearly states the tool's purpose: to find notes by exact tags, explicitly distinguishing it from semantic search. The verb 'find' and resource 'notes' are specific and unambiguous.

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

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

The advice to use tag_stats to discover available tags before filtering provides a useful precondition. However, it does not elaborate on when exact tag search is more appropriate than other sibling search tools.

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

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

There are no annotations indicating read-only or side-effect behavior. The description implies a non-destructive searching operation, but it never explicitly states that the tool does not modify, delete, or reindex anything. Since annotations are absent, the description carries the full burden of disclosing behavioral guarantees.

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

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

The description is brief and to the point, with no redundant phrasing. The first sentence states the main purpose, and the second sentence adds useful detail about the mechanism. It is well-structured for quick 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?

The description lacks important context for an agent: it does not specify the return format, whether results are sorted by similarity, how the max_notes limit is applied, or whether an existing index is required. Given the large sibling tool list and the presence of overlapping search tools, this incomplete context could lead to incorrect tool selection.

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 parameter names and inline descriptions ('folder scope', 'maximum notes to process', 'minimum similarity') provide basic meaning, but they do not explain defaults, value ranges (other than threshold's 0.5-0.99), or how the folder parameter interacts with the search. The schema supplies types and defaults, but the description adds only marginal semantic detail.

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

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

The description clearly states the tool's purpose: finding groups of duplicate or highly similar notes. It uses specific action words ('Find', 'Compares', 'groups') and identifies the resource (notes) and method (embeddings, similarity threshold), making the core function easy to understand.

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 explain when to use this tool versus alternatives like find_similar_notes or search_advanced. It also does not mention any preconditions, such as whether an existing vector index is required, or how this tool differs from other sibling search tools.

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

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

With no annotations, the description carries the transparency burden. It reveals the processing flow—query embedding, vector retrieval, reranking—but does not explicitly state that the operation is read-only or side-effect free.

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

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

The description is brief and well structured: one sentence for purpose and one for flow. No redundant words are present.

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

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

For a simple search tool, the description covers the main behavior, but it does not mention result format or limitations. Since no annotation or output details are present, an agent has limited context about what the search will return.

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?

Both parameters are described in the schema, so coverage is 100%. The description adds no further semantic detail beyond the schema, which is the baseline for fully covered 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?

The description clearly identifies the action (search), the resource (vault notes), and the approach (semantic with cross-encoder reranking). It does not explicitly point to sibling search variants, but the semantic qualifier distinguishes it from hybrid and advanced 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?

No guidance is given about when to prefer this tool over search_vault_hybrid, search_advanced, find_similar_notes, or other search siblings. The description only states what the tool does, not when it should be selected.

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 present, so the description carries the full burden. It does not disclose any side effects, authentication requirements, or rate limits. While it is likely a read-only search, the description omits any explicit statement about non-destructive behavior, leaving some ambiguity.

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

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

The description is two sentences with no unnecessary words. The core functionality and its primary advantage are stated efficiently, making it 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?

The description sufficiently explains what the tool does and what it recovers. It does not mention output format or usage prerequisites, but for a search tool these are not critical. The description is complete enough for an agent to select and invoke 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 100% with clear descriptions for both parameters ('search text' and 'number of results'). The description does not add additional nuance beyond what the schema provides, so the baseline of 3 is appropriate.

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

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

The description clearly states the tool combines semantic and keyword search, and explains the benefit of recovering exact terms and semantic content. However, it could be more explicit in framing it as a search operation, though the context of sibling tools makes that obvious.

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

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

The description gives a hint on when to use it (when exact technical terms and semantic similarity are both needed), but does not explicitly contrast it with sibling tools like find_similar_notes or search_advanced. No explicit 'when to use' guidance is provided.

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

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

With no annotations, the description carries the full burden. It conveys the tool's core behavior (suggesting links, excluding already-linked notes) but does not disclose side effects (e.g., whether it modifies anything) or output format. The read-only nature is implied but not stated.

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 concise, consisting of two clear sentences with no redundant information. It effectively communicates the tool's function in a minimal, well-structured manner.

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

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

Given the lack of annotations and output schema, the description provides sufficient context for an agent to understand the tool's purpose and select it appropriately. However, it omits details about the returned data structure or any edge-case behavior, which slightly reduces 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?

The schema covers all three parameters (path, limit, min_similarity) with basic descriptions, but the tool description adds no additional meaning. Since schema coverage is 100%, the baseline is 3, and the description does not enhance understanding of the 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?

The description clearly states the tool's purpose: suggesting links for a note based on semantic similarity, and specifies that it finds notes not already linked. This distinguishes it from the sibling find_similar_notes which likely returns similar notes without the link-suggestion focus.

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

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

The description implies usage (when you need link suggestions based on semantic similarity) but does not explicitly mention alternatives or when to prefer this over similar tools like find_similar_notes or search_duplicates. The guidance is implicit rather than direct.

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 full responsibility for behavioral disclosure. It mentions detecting changes and synchronizing, which implies index updates, but it does not detail side effects, failure modes, or whether it is safe to run concurrently. The dry_run option is mentioned only in the schema, not in the description, so the description alone is incomplete for a mutation-like 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 description is three concise sentences, with the main action front-loaded. It avoids redundant phrasing and conveys the core purpose, detection scope, and usage hint without fluff. Every sentence contributes value.

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

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

Given the moderate complexity and presence of an output schema, the description covers the key aspects: what the tool does, what it detects, and when to use it. It does not elaborate on edge cases or internal behavior, but it is sufficient for an agent to understand the tool's role and call it correctly. The lack of annotations is partially mitigated by the clear usage guidance.

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

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

Schema description coverage is 100% for both parameters (dry_run and require_daemon), so the schema fully documents their meaning. The description adds no additional parameter context beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description states a specific verb ('Synchronize') and resource ('vault files with the index'), and explicitly lists the types of changes detected (new, modified, deleted). This clearly distinguishes it from sibling tools like reindex_vault (full reindex) and search tools, avoiding any ambiguity about what the tool does.

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

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

Provides explicit when-to-use guidance: 'Use this after files changed while the server was stopped.' This gives clear context for the intended scenario, though it does not explicitly mention alternatives or when not to use it. Still, the guidance is specific and actionable.

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

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

The main description says 'Return', suggesting read-only behavior, but the reset parameter can mutate operation metrics. The input schema describes this reset behavior, but the tool-level description does not call out the side effect or clarify whether stats are cumulative or resettable.

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

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

The description is short, focused, and front-loads the main purpose before listing included statistics. Every sentence contributes useful information without redundancy.

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

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

For a statistics tool, the description lists categories but omits details about return format, units, whether metrics are cumulative/current, and the exact effect of reset on subsequent calls. The reset parameter is explained, but an agent would need more context to fully interpret the response.

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

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

The single reset parameter is fully described in the schema with a default value, so parameter coverage is complete. The tool description does not add extra meaning about the parameter beyond what the schema already provides, so it meets the baseline but not more.

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

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

The description clearly states the tool returns measured operation and subsystem statistics and enumerates the included categories (latency, cache counters, catalog totals, vector-index stats). It is less specific than some sibling tools like vector_index_status or vault_stats, but the name and scope make the primary purpose clear.

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

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

The description implies this is the tool for system/performance metrics rather than content or graph statistics, but it does not explicitly state when to choose it over sibling tools such as vault_stats or vector_index_status. There is no explicit alternative guidance.

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

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

The description indicates a read-only 'return' operation and the counting rule, but with no annotations it does not disclose side effects, permissions, rate limits, or other behavioral constraints beyond that.

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

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

The description is very concise and front-loaded, using two short sentences to state the purpose and the counting rule with no filler or redundancy.

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

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

Given the simple input schema and no output schema, the description provides enough context to understand the core behavior, but it does not specify the exact output shape (e.g., list of tag/count pairs or sorted order).

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?

Both parameters are described with meaningful semantics: 'limit' is the maximum returned tags and 'folder' is an optional folder filter. These add intent to the schema types and defaults, though edge cases like folder exclusion are not discussed.

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 explicitly states the tool returns vault tag usage statistics and clarifies that each tag is counted once per note, which is a specific and concrete purpose. It is clearly distinct from note search or link statistics 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 guidance is provided about when to prefer this tool over related alternatives such as search_by_tags, link_stats, or vault_stats. The description defines what it does but does not state when it should or should not 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?

Describes core behavior (merge is shallow, arrays/objects replaced) and the restriction to existing .md notes, but omits side effects like return values, error handling, or whether it preserves unrelated fields. With no annotations, more detail would be expected for full transparency.

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

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

The description is extremely concise, with two short sentences covering core functionality and constraints. No filler or redundant information.

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

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

Given the low complexity and presence of an output schema, the description is largely complete for an update operation. It could mention what the operation returns or typical error conditions, but the essential usage and merge semantics are 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 coverage is 100% and each parameter has a description, but the tool description adds no extra meaning beyond the schema itself. The merge false behavior ('replace all frontmatter') is only inferable from the schema's description of the default true, not from the tool narrative.

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

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

States a specific verb ('Update') and resource ('YAML frontmatter on an existing Markdown note'), clearly distinguishing it from note content operations like write_note or append_note. The scope is precise and unambiguous.

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

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

The description implies usage for modifying frontmatter and includes constraints (.md only, merge behavior), but it does not explicitly mention when to choose this tool over siblings such as write_note or create_note. No direct alternative comparison is provided.

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 on its own. It only says 'validate' without stating whether the operation is read-only, what it returns on success/failure, or whether it has any side effects. This lack of transparency is a significant gap.

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

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

Two concise sentences, front-loaded with the primary action. No unnecessary words or repetition.

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

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

For a simple validation tool, the description is adequate in terms of when to use it, but it omits details about the validation result (e.g., error format, pass/fail indication) and what 'the schema' refers to explicitly. The presence of an output schema might mitigate this, but the description itself does not provide that 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?

The schema descriptions cover both parameters (path and frontmatter) at 100%, so the baseline is 3. The tool description adds no additional context about parameter interactions or selection logic, but it does not need to since the schema already explains them.

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

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

The description clearly states the action (validate), the object (note frontmatter or supplied dictionary), and the criterion (against the schema). It is specific and distinguishable from other tools.

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

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

Provides explicit timing guidance: 'Use this before creating or updating notes.' It does not explicitly contrast with alternative tools, but the use case is clear enough.

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 of disclosing behavior. It implies a read-only operation by saying 'Return', but it does not explicitly state whether any side effects occur or whether the statistics are computed on-demand or from a cached 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?

The description is extremely concise, using two sentences to state the purpose and output. There is no redundant wording or unnecessary detail.

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

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

The output schema is described in summary form ('totals for chunks and notes, plus last modification time'), which is sufficient for a zero-parameter tool. It is not overly detailed but covers the key information an agent needs to understand the result.

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 per the rubric. The schema coverage is trivially 100%, and the description adds no parameter information because none is needed.

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

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

The description clearly states the tool's purpose with a specific verb ('Return') and resource ('search-index statistics'). It also specifies the exact output (totals for chunks and notes, last modification time), making it distinct from sibling tools like link_stats or system_stats.

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 is provided about when to use this tool versus alternatives such as link_stats, tag_stats, or system_stats. The description only states what the tool returns, not when it should be selected.

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

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

The description explains the creation condition ('index is created when the configured chunk threshold is reached') and outlines the returned fields. Since there are no annotations, the description carries the burden; it provides meaningful insight into the tool's behavior without being exhaustive.

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

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

The description is two sentences long, directly states the action and the key behavioral detail, and lists the output fields. No unnecessary words or fluff.

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

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

The description enumerates exactly what the tool returns ('Current existence, threshold, chunk count, eligibility, and auto-creation setting'). It also provides the trigger condition. Given the simplicity of a status check, this is complete context for an agent to decide and invoke 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?

The tool has zero parameters, so the schema is fully covered by default. There is nothing to explain about parameters, making the description perfectly adequate in this dimension.

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

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

The description clearly states the tool's purpose: 'Return ANN vector-index status.' The resource is specific (ANN vector-index) and the verb is definitive. It is distinct from all sibling tools, none of which target vector-index status specifically.

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

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

The description does not explicitly state when to use this tool versus alternatives. However, given that no sibling tool provides vector-index status, the use case is implicitly unique. Still, the lack of explicit 'use this when' guidance prevents a higher score.

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

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

The description reveals the destructive nature ('Overwrite') but does not mention other side effects such as creating parent directories, updating metadata, or handling of existing content beyond replacement. With no annotations, more detail would improve transparency.

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

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

The description is extremely concise, with two sentences: one stating the function, one providing usage guidance. No wasted words.

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

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

The tool is simple, and the description covers the primary purpose and usage condition. It does not mention error cases or return values, but those are likely covered by the output schema (not shown) and the simplicity of the operation.

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

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

The parameters are fully described in the schema (path as vault-relative path, content as complete note content), so the description adds little beyond restating that content must be complete. Baseline of 3 is appropriate.

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

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

Clearly states the action ('Overwrite or create'), the target ('Markdown note'), and the input ('complete content'). It distinguishes itself from append_note by specifying the caller already has complete content.

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

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

Provides an explicit condition for use: 'Use this when the caller already has the complete .md content.' This tells the agent exactly when to select this tool over alternatives like append_note or create_note.

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