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

Annotations already mark this as read-only, and the description adds meaningful behavior: it enumerates the link types covered and notes that each result includes the lines where links appear. This goes beyond the structured annotations without contradicting them.

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

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

Two sentences with no filler: the first defines what is returned, the second gives the intended use case. The key information is front-loaded and every clause earns its place.

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

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

For a single-parameter, read-only tool with no output schema, the description sufficiently explains what the agent will receive (linking notes plus the lines of the links) and why it would use the tool. Nothing essential is missing.

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

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

There is only one parameter and the schema already describes it fully as 'Path of the note relative to the notes root' with 100% coverage. The description adds no additional parameter-level detail, so the schema carries the burden.

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

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

The description clearly identifies the resource (backlinks to a note) and specifies the exact link forms included: [[wikilink]], alias, and relative Markdown links. This distinguishes it from siblings like ragdown_read_doc or ragdown_list without needing to open the schema.

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

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

It gives explicit usage context: 'Use it to find what depends on or refers to a note, e.g. before changing or superseding it.' It does not name alternatives or exclusions, but the use case is clear enough for an agent to select this tool appropriately.

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 provide readOnlyHint=true, openWorldHint=false, and the description aligns. It adds behavioral context beyond annotations: fails gracefully to empty text, filters by min_score, skips short prompts and slash commands, and prevents duplicate sections per session. Could mention empty return format but 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?

Two sentences, densely informative. The main purpose is front-loaded, and the differentiation from ragdown_recall comes second. 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 moderate complexity (6 params, no output schema), the description covers the key behavior: output is a block or empty, filtering logic, and deduplication. Could mention the return format in more detail (e.g., whether it's a plain string or includes metadata), but for a read-only retrieval tool, it is nearly complete.

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

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

Schema coverage is 100%, so parameters are already well-documented. The description adds high-level context (filtering, skipping) but doesn't add detail to any specific parameter beyond what schema provides (e.g., default env vars are in schema descriptions). Baseline 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 it returns a ready-to-inject <ragdown-context> block for pre-turn hooks, and explicitly contrasts with ragdown_recall. Distinguishes its filtering behavior (min_score, skips short prompts/slash commands, no duplicates per session).

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

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

Explicitly says 'For hooks that run before a turn', and mentions it is unlike ragdown_recall, suggesting when to use this vs. that sibling. Provides clear guidance on timing and alternative avoidance.

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

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

Beyond the annotations' destructiveHint, the description reveals crucial behavior: whole-file replacement including frontmatter, the hash-based optimistic concurrency lock, append semantics, heading-scoped appending, and the silent no-write outcome when the file changed. This goes well beyond what the annotations alone convey.

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 dense sentences front-load the core action, then add necessary safety and append semantics without redundancy. Every clause earns its place, and the most important constraint (whole-file replacement + base_hash) appears early.

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

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

For a destructive write tool with 5 parameters and no output schema, the description covers the main path, the append variant, the heading variant, the concurrency failure mode, and the recovery instruction. An agent has enough to call the tool correctly and handle the non-success case.

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 80%, so the baseline is 3, but the description adds real meaning to base_hash, append, and heading: it explains why base_hash is required (to avoid overwriting unread versions) and exactly how append/heading modify behavior. This exceeds the schema's bare field definitions.

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

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

The description opens with a specific verb and resource: 'Change an existing note, or create one at a path you choose.' It clearly distinguishes the tool's write/update role from sibling read-oriented tools like ragdown_read_doc and ragdown_list.

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

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

The description gives clear operational context: creating vs editing, when base_hash is required, when append is appropriate, and the failure-fallback instruction to 'read it again and redo the edit.' It does not explicitly contrast against other write-adjacent siblings, but the usage conditions are concrete enough for an agent to decide correctly.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, and the description adds output fields, filter behavior, and recent-sort semantics. However, the claim that it lists 'every note' overstates behavior because the schema defaults limit to 100 and caps at 1000, which is a notable inaccuracy in what the agent should expect.

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 tight sentences that front-load the browse-vs-search decision and then pack return fields, optional filters, and sort behavior with no filler. Every clause earns its place, making it easy for an agent to parse quickly.

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

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

For a read-only list operation with no output schema, the description names the returned fields and the main filtering and sorting knobs, and the schema supplies limit bounds. It would be stronger if it acknowledged the default truncation of the result set, but nothing essential is missing for a basic browse call.

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

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

Schema description coverage is only 50%, and the description partially compensates by mentioning subfolder/tag filtering and explaining the 'recent' sort value. It adds little about the 'path' sort value or the meaning of 'limit,' which must be inferred from schema defaults rather than explicitly described.

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

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

The description opens with an explicit action—browse rather than search—and names the resource, notes, plus the concrete result shape (path, title, tags, last change). It also distinguishes itself from search-like behavior, so an agent can separate it from siblings such as ragdown_recall without inspecting schemas.

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

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

It clearly frames when to use this tool: browsing notes rather than searching for them, with optional folder and tag filtering. It does not explicitly name the search sibling as the alternative, so the when-not guidance is slightly implied, but the context is strong enough for correct routing.

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

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

Annotations already declare readOnlyHint=true, and the description goes beyond that by disclosing that reads come straight from disk, are never clipped, and that the returned hash covers the whole file rather than just the requested range. This adds meaningful behavioral context beyond the structured annotations.

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

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

Three dense sentences, each earning its place: the core behavior, the key non-clipping guarantee, and the relationship to recall and edit. The most important scoping information is front-loaded and nothing is redundant.

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

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

For a read-only tool with no output schema, the description covers the main calling scenarios, line-range capability, disk behavior, and output hash semantics. Minor gaps remain around exact line-range rules and response shape, but an agent has enough to call it correctly in its primary contexts.

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 path parameter is richly described in the schema (relative path, recall return value, wikilink forms, heading narrowing), and the description mentions whole-file or line-range reading. However, start_line and end_line have no schema descriptions and the description does not clarify defaults, inclusivity, or interaction with heading narrowing, leaving some ambiguity for a low-coverage 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?

Description states a specific verb and resource: read a Markdown file from the notes folder, either whole or by line range. It also distinguishes itself from siblings by naming its role relative to ragdown_recall hits and ragdown_edit's base_hash, so an agent can tell it apart from recall, list, and edit.

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 contexts for use: seeing context around a ragdown_recall hit, following a wikilink, and obtaining a hash for ragdown_edit. It does not spell out exclusions versus every sibling, but the relevant alternatives are clearly named and the intended use is unambiguous.

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

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

Annotations already declare readOnlyHint=true, so no contradiction. The description adds value beyond annotations by disclosing the output format (file path, line range, heading breadcrumb, cosine similarity) and a heuristic threshold ('above ~0.8 is usually on topic'). It does not describe pagination or sorting, but for a safe read-only search this is adequate.

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, front-loaded with the core purpose, then the usage rule. No filler or repetition of schema content. The behavioral note about similarity is concise and useful.

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

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

For a search tool with no output schema, the description covers when to use it, what it returns, and what to do next. It does not explain format json vs text or max_chars, but those are adequately described in the schema. The main gap is not mentioning whether results are sorted by score, but the similarity note implies ranking. Overall complete enough 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 67% (4 of 6 params have descriptions). The description itself does not add details for the undocumented top_k and format parameters, though it implies ranking relevance. It clarifies query semantics via 'hybrid (semantic + keyword)', but leaves parameter-specific meaning mostly to the schema. This is adequate, not exceptional.

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

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

The description names a specific verb ('search'), resource ('the user's Markdown notes'), and mechanism ('hybrid semantic + keyword'). It also lists what the tool returns (sections with file path, line range, breadcrumb, similarity) and distinguishes it from the sibling ragdown_read_doc, which is for surrounding text.

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

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

It states exactly when to use the tool ('before answering anything the notes may cover') and provides a follow-up action ('follow up with ragdown_read_doc for the surrounding text'). This gives the agent a clear decision rule without having to infer from sibling schemas.

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

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

Annotations declare a safe mutation (readOnlyHint=false, destructiveHint=false, openWorldHint=false); the description adds valuable context beyond them by explaining that indexing is normally automatic and this is a manual, idempotent corrective action. It doesn't hint at cost or duration of a full re-embed, which is the one meaningful gap for a potentially expensive 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?

Two sentences, zero filler. The primary action and its trigger condition are front-loaded, and the parameter note comes second where it belongs.

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?

No output schema and only one optional parameter, so little needs explaining; the description covers purpose, trigger, and parameter semantics adequately. It stops short of stating what happens on completion or how long a full reindex takes, a minor omission for an operation that may be long-running.

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

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

Schema coverage is 0% and the lone boolean has no description in the schema, but the description supplies its meaning: 'full: true to re-embed everything', implying the default false does an incremental update. That is exactly the compensation a low-coverage schema needs.

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

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

States a specific verb+resource: 'Bring the index up to date with the folder now.' An agent can distinguish this from siblings like ragdown_recall or ragdown_read_doc, which are read/query tools, though the description doesn't explicitly name any sibling to disambiguate against.

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 gives both when-not and when: 'Changes are normally picked up automatically within a second; use this after bulk edits made while no server was running.' It also names the escalation path ('full: true to re-embed everything'), so the agent knows the default vs. thorough mode.

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?

Goes well beyond the sparse annotations by disclosing indexing behavior, the non-overwrite guarantee, and that superseded notes remain readable but are excluded from search/context. Adds nuanced guidance on when to use supersedes versus merely writing about the same topic.

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 sentences, each with a distinct job: core action, safety guarantee, supersede guidance. No filler or repetition of schema details.

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

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

Strong on behavior and parameter intent; slightly lacking an explicit statement of return value or generated file path, though that is derivable from naming defaults. Overall sufficient 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?

The description adds important meaning to supersedes (search/context skipping, paths from ragdown_recall) and complements the schema's 67% coverage. It explains the note-save workflow but does not elaborate on less critical params like tags/title beyond what the schema 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?

States a precise action: saving durable knowledge as a new Markdown note in the notes folder, with key qualifiers 'never overwrites' and 'indexed immediately'. The verb-resource pair clearly distinguishes it from read/search siblings like ragdown_read_doc and ragdown_recall.

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

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

Gives clear conditions for use: saving decisions, fixes, how-tos, and when replacing an earlier note with supersedes. It does not explicitly contrast with read-only siblings, but the write/read split is evident from sibling names and 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 only declare readOnlyHint and a closed-world hint, so the description adds real value: it discloses that the response includes per-process role information (whether this process is the indexing primary) and the last sync, which is meaningful multi-process context. It stops short of describing error behavior or output format, but for a read-only status call that is a minor 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 compact sentences with no filler; the reported-field list comes first and the parameter note last. The field enumeration is dense but each item earns its place by telling the agent what to expect back.

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

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

With no output schema, the description carries the return-value burden and largely does so by naming each reported field. Minor omissions remain — no note on response shape or behavior when no index exists — but the essential content is covered for a simple read-only stats call.

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

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

Schema description coverage is 0% and the single boolean parameter is undocumented in the schema, but the description compensates by explaining that include_files makes the response list every indexed file. It does not restate the default-false behavior or note the cost of enumerating all files, so it is good rather than complete.

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

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

The description enumerates exactly what the tool reports (notes folder, index size in files/chunks, embedder, indexing-primary flag, last sync), so an agent can tell it returns index status rather than notes or documents. It lacks a leading verb phrase and never names the sibling tools it differs from, so the differentiation is inferential rather than explicit.

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

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

There is no statement of when to call this versus ragdown_recall, ragdown_read_doc, or ragdown_reindex, and no prerequisites or diagnostic context. An agent must guess that this is a status/inspection tool rather than a retrieval one.

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