Read a document

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

Annotations cover only read-safety (readOnlyHint=true, openWorldHint=false), and the description adds genuinely new behavior: reads unclipped directly from disk and returns a header line 'path:start-end of total_lines (hash …)' where the hash is the whole file's base_hash, with raw file text from line two. That return contract is exactly what an agent needs and is absent from structured fields.

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

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

Front-loads verb, resource and scope in the first sentence, then use cases, then output format. Three dense sentences, all load-bearing; the header/hash explanation is slightly run-on but is necessary since there is no output schema.

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

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

With no output schema, the description carries the return-format burden and does so explicitly. Combined with path semantics for recall hits and wikilinks, an agent has enough to call it correctly; the only shortfall is line-range boundary semantics. Not requiring auth or error behavior is acceptable for a read-only disk 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 only 33%: path is documented in the schema, but start_line and end_line are bare. The description's 'whole or by line range' explains the intent of the two undocumented integers but not whether the range is inclusive, 1-based, or what happens on out-of-range values, so it only partially compensates.

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

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

States a specific verb and resource ('Read a Markdown file from the documents folder') plus scope ('whole or by line range, straight from disk'). An agent can distinguish this from ragdown_recall (search) and ragdown_context without opening the schema.

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

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

Gives two concrete triggers: inspecting context around a ragdown_recall hit and following a [[wikilink]]. It names the sibling workflow that leads here but never states when not to use it (e.g., vs. ragdown_context or ragdown_list), so guidance is strong but not exhaustive.

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