read_symbol

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It discloses ambiguity handling ('Returns all matches when the name is ambiguous'), the line-number gutter caveat with specific stripping instruction for edit_file reuse, and the tree-sitter fallback when the language server is cold or absent. This goes well beyond basic read semantics, though error cases like symbol-not-found are not explicitly mentioned.

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 four sentences long and front-loaded with the core action. Each sentence adds distinct value: the action, accepted input forms, ambiguity behavior, output format caveat, and fallback mechanism. There is no fluff or redundancy.

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?

For a read tool with no annotations or output schema, the description sufficiently covers return behavior (all matches), ambiguity handling, output line-number gutter instructions, and language-server fallback. The only minor gap is the absence of a symbol-not-found behavior note, but overall it is adequately complete.

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?

The input schema already provides 100% coverage for all three parameters, so the baseline is 3. The description echoes the dotted-name form present in the schema but adds no new parameter-level nuance; it focuses on output formatting and fallback behavior rather than parameter meanings.

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 opens with a specific action: 'Read the source body of a named symbol (function, method, type) in one call,' clearly identifying the resource and scope. It distinguishes itself from siblings like get_definition and read_file by focusing on the symbol body retrieval rather than definition location or whole-file content.

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 through phrases like 'in one call' and accepts plain or dotted forms, but it does not explicitly state when to prefer this tool over alternatives such as get_definition or search_in_files. No exclusions or direct comparison to siblings are provided, leaving the agent to infer the appropriate context.

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