find_symbol

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

No annotations are provided, so the description carries the full burden and mostly fails to: it does not say that this is a read-only query, whether matching is case-sensitive or substring-based, what the default search scope is when workspacePath is null, or how results are ordered. The enumeration of symbol types is the only behavioral detail it contributes.

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?

A single front-loaded sentence with no filler or hedging. The parenthetical slightly duplicates the symbolType schema description, but the sentence otherwise earns its place.

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 four parameters, no annotations, and no output schema, an agent needs to know match semantics, default scope, result shape, and ordering rules. None of these are covered, so the definition is too thin for a search tool whose behavior is not self-evident from its name.

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%, so the parameters are already fully documented, and the baseline of 3 applies. The parenthetical '(Class, Interface, Function, Variable)' restates the symbolType enum rather than adding new meaning, and it says nothing about how partial names are matched.

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 states a specific verb (Search) and resource (code symbols in the graph) and enumerates the symbol kinds covered. It stops short of distinguishing this from siblings such as search_identifiers or get_file_outline, which appear to overlap on surface form.

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?

There is no guidance on when to use this versus alternatives, nor any stated preconditions (e.g., whether a workspace must be indexed first). The only clue is the word 'Search', leaving the agent to infer scope from the name alone.

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