describe_symbol

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so safety is clear. The description adds an extra limitation about the graph layer for call data, which goes beyond the annotations and improves transparency.

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 concise sentences that deliver the key value proposition, alternatives, and a caveat without fluff. The structure front-loads the purpose and immediately contrasts with siblings.

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?

Provides enough context to understand the tool's scope (definition, callers, callees, tests) and its partial dependency on the graph layer. While it lacks a detailed return format, the description is sufficient for a read-only context-gathering tool.

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 covers all 5 parameters with descriptions, including defaults and examples for symbol format. However, the description itself adds no extra meaning beyond the schema; the limits are self-explanatory and the source parameter is adequately described as optional.

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?

Clearly states it provides one-shot context for a symbol including definition, callers, callees, and tests, and explicitly contrasts with three sibling tools (find_definition, find_usages, find_tests_for) by being cheaper and faster. The verb 'describe' and resource 'symbol' are specific.

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?

Explicitly recommends using this tool before changing a function or class and notes it's cheaper than calling the three alternatives separately. Also mentions a caveat that call data needs the graph layer while definition and tests always work, giving clear guidance on when it's reliable.

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