query_reachability

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

With no annotations provided, the description carries the full burden. It discloses the algorithmic approach (Kameda O(1) index with BFS fallback) and the return structure, including that the path is returned only when BFS is used. This adds useful behavioral context, though it does not mention prerequisites like needing an index or potential side effects, which is reasonable for a read-only query.

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 sentences, with the first front-loading the core purpose and the second providing algorithmic and output details. Every sentence earns its place with no redundancy or fluff.

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 the tool has no output schema and no annotations, the description does a good job covering the essential behavior and return values. It does not mention prerequisites (e.g., whether a pre-built index or call graph is required), which could be important context for an agent, but the core operation is well-explained.

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%, so the description must compensate. It implicitly identifies source_function and target_function as the two endpoints ('between two functions') but adds no detail about their expected format. The workingDirectory parameter is entirely unaddressed in the description. This is minimal compensation for the lack of schema descriptions.

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 states the tool's function with a specific verb ('Query') and resource ('reachability between two functions in a project's call graph'). It distinguishes itself from sibling tools like extract_call_graph or compute_partitioning by focusing on reachability queries, and it outlines the output (whether reachable, method used, path if via BFS).

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 implies usage when one needs to determine if one function can reach another in a call graph, but it provides no explicit exclusions, alternatives, or comparison to sibling tools like graph_query_tool. The context is clear but lacks any 'when-not' or 'use instead' guidance.

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