find_usages

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

With no annotations, the description carries the full burden, and it does disclose two useful traits: results are capped ('at most top_k hits') and source lines/enclosing definitions are only returned 'when available'. It adds a cross-tool hint (read_lines suggests bounded source ranges) but says nothing about permissions, the filtering behavior of `include`, or how hits are ordered.

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 tight sentences with the core action front-loaded and no filler. The second sentence efficiently bundles the result cap and the availability caveat, though the trailing read_lines reference slightly distracts from the tool's own contract.

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?

An output schema exists, so return values need not be described, and the description does cover scope, cap, and availability. For a zero-annotation, zero-schema-coverage tool it still leaves gaps: the `include` parameter's meaning and the definition of a 'lexical' reference versus other search siblings are unresolved.

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 for all three parameters. It explains top_k indirectly ('returns at most top_k hits') and `symbol` by implication, but `include` is never mentioned and its filtering semantics are left entirely undocumented in both schema and description.

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 gives a specific verb+resource ('find lexical references to a symbol'), which is more precise than a generic 'search' and implicitly separates it from find_symbols (definitions) and find_evidence. It stops short of explicitly naming a sibling or drawing the boundary with them, so it is clear but not fully differentiating.

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?

Usage is implied by the phrase 'find lexical references to a symbol', so an agent can infer the basic trigger. However, there is no explicit when-to-use, no exclusions, and no routing guidance relative to find_symbols, find_evidence, or select_context, leaving the choice between overlapping search tools to inference.

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