repo_path_between

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

The description asserts 'Read-only, deterministic traversal, no side effects,' but the annotations declare readOnlyHint=false, which tells an agent the opposite. These two signals directly conflict and an agent cannot tell whether invoking this tool may mutate state. The conflict is flaggable under the contradiction rule even though other behavioral details (bounded traversal, min-confidence reporting) are otherwise informative.

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 operation, then clearly delimited 'When to use', 'When NOT to use', and 'Output' segments. Dense but every sentence carries information an agent needs; no filler.

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 correctly supplies the return shape (JSON array of ordered {node_id, path, start_line, end_line, via_edge, confidence} objects), plus traversal bounds and default edge types. An agent has everything needed to call and interpret results — the only defect is the safety-signal conflict noted above.

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% — every parameter, default, and the CO_CHANGE caveat is documented in the schema itself. The description only restates the CO_CHANGE rule already present in the edge_types field, adding no new syntax or format guidance. Baseline 3 applies when the schema does the heavy lifting.

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+scope: find a bounded bidirectional path between two node_ids over named edge types, reporting minimum confidence per path. It distinguishes itself from siblings by explicitly naming repo_neighbours and repo_search as the wrong tools for adjacent tasks.

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?

Explicit 'When to use' with a concrete example (HTTP handler to database write) and an explicit 'When NOT to use' that routes to the correct alternatives (repo_neighbours for one hop, repo_search for open-ended search). Nothing is left to inference.

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