repo_read

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

The description asserts 'Read-only, deterministic, zero side effects', but the annotations declare readOnlyHint=false, i.e. the tool may modify its environment. That is a same-axis conflict between the prose and the structured hints, so an agent gets contradictory safety signals. The description does add genuinely useful context (indexed chunks have passed secret-path exclusion and redaction, absolute/'..' paths are refused), but the direct contradiction caps this dimension.

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

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

Front-loaded with the core action and scope, then cleanly segmented into when-to-use, when-not-to-use, and output. Slightly dense in the opening clause about HTTP/no-shared-filesystem, but every sentence 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 supplies the return shape ('[cite: path:start-end]' header plus bounded text), the error conditions (refused paths), and the workflow placement relative to repo_search/repo_neighbours. Nothing essential for correct invocation 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?

Schema description coverage is 100%, so path/context/start_line/end_line are already documented with defaults and the 500-line cap. The description adds only the path-provenance rule (must match a [cite: path:start-end] header) and the refusal behavior, which is baseline-level value over an already complete schema.

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

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

States a specific verb+resource (read a widened window of source text around a citation) and immediately scopes it ('from the indexed chunks rather than the filesystem'). It explicitly distinguishes itself from sibling tools repo_search and repo_neighbours, so an agent can route correctly 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?

Provides explicit 'When to use' (after repo_search or repo_neighbours to expand a [cite: path:start-end]) and 'When NOT to use' (never-indexed path, absolute or '..' path), plus the named fallbacks repo_search and repo_find_symbol. Both the positive and negative conditions are spelled out, not implied.

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