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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuine behavioral context not in annotations: retrieval is "straight from disk" and "Never clipped", telling the agent results are raw and untruncated. It omits error behavior for missing paths or out-of-range lines, keeping it below a 5.

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 zero filler; the core capability is front-loaded and the routing hint follows immediately. 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?

There is no output schema, so the description carries the burden of describing what comes back, and "Never clipped" plus "straight from disk" does that adequately for a read tool. What is missing is edge-case behavior (nonexistent path, line range beyond file length), a minor gap for a simple read 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?

Schema coverage is only 33%: path is documented in the schema, but start_line and end_line are bare integers with no constraints described. The description compensates partially by framing the tool as fetching "whole or by line range", giving the two range parameters meaning, but it does not clarify inclusivity, whether both are required together, or what happens with only one supplied.

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 (read) and resource (a Markdown file from the notes folder), plus scope (whole file or a line range, straight from disk). It explicitly names the sibling ragdown_recall, so an agent can distinguish this file-fetch tool from the semantic search tool without opening either 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?

"Use it to see the context around a ragdown_recall hit" gives a concrete when-to-use condition tied to the sibling tool, effectively routing the agent between recall and read. It stops short of stating when not to use it (e.g. when no hit is in hand), so it is clear context rather than full when/when-not 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?

Annotations already declare readOnlyHint=true and openWorldHint=false, but the description adds real behavioral content: it discloses the return shape (file path, line range, heading breadcrumb, cosine similarity) and gives an interpretive threshold ('above ~0.7 is usually on topic'). It does not address result limits or clipping behavior beyond what the schema says.

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, and the core capability plus return format are front-loaded before the usage directive. Every clause carries information an agent needs.

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 burden of explaining returns and does so concretely, and annotations cover the safety profile. It leaves top_k/format usage and result-limit behavior implicit, a minor gap for a 5-parameter read tool.

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

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

Schema coverage is 60%, so the schema documents query, max_chars and path_prefix but leaves top_k and format bare. The description adds no parameter-level meaning — no guidance on top_k sizing, format choice, or path_prefix scoping — so it neither compensates for the gap nor adds beyond the schema. 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?

Names a specific verb and resource ('hybrid (semantic + keyword) search over the user's Markdown notes') and distinguishes itself from siblings by routing the agent to ragdown_read_doc for surrounding text. An agent can tell this apart from ragdown_stats, ragdown_remember and ragdown_reindex without opening any schema.

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

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

Explicitly states when to use it ('before answering anything the notes may cover') and names the follow-up alternative ragdown_read_doc with its purpose. It lacks exclusions (e.g., when to prefer ragdown_remember or ragdown_stats), so it falls short of the full when/when-not/alternatives bar.

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?

Annotations already declare a non-destructive write, but the description adds real behavioral context beyond them: writes are indexed immediately (so search finds them) and existing files are never overwritten. That indexing and collision-safety behavior is not derivable from the annotation flags.

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 tightly packed sentences: the write action and immediate indexing come first, the non-overwrite guarantee second. No filler and nothing 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 non-destructive write tool with full annotation coverage and no output schema, the description covers the essential behavior including indexing. It leaves minor gaps, such as what is returned and what happens on a name collision given files are never overwritten, but the core call path is 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 description coverage is only 50% — 'title' and 'tags' have no schema descriptions. The description mentions that Markdown frontmatter carries the title, but adds nothing about 'tags' or the 'name' default/format, so it fails to compensate for the coverage gap.

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

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

States a specific verb (save/write) and resource (Markdown note in the notes folder) and characterizes the kind of content it holds. It does not name a sibling tool, but the 'so later searches find it' clause implicitly ties it to ragdown_recall, making it distinguishable from the read-side 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?

Gives positive guidance about what belongs here (a decision, a fix, a how-to) which is useful for choosing to write. However it names no alternative and no when-not condition — e.g. when to use this versus ragdown_reindex or ragdown_read_doc — leaving routing to inference.

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

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

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.