CodeGraph: codegraph_callers

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

Annotations already cover the safety profile (read-only, idempotent, non-destructive, closed-world), so the description only adds the 'full flow' routing hint. It does not disclose whether callers are direct/one-level vs transitive, what the return list shape is, or any index prerequisites. No contradiction with annotations, but minimal extra behavioral context.

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 short sentences deliver the core purpose and point to the appropriate sibling tool. There is no filler or repetition; the description is front-loaded with the actionable verb-resource statement.

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 100% schema coverage and strong annotations, the definition is largely complete for a simple read-only listing tool. The main gaps are the lack of explicit 'direct callers only' clarification and any return shape detail, but the description plus schema gives an agent enough to invoke it correctly in most situations.

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 100%, so all four parameters are already documented with meaningful details (file disambiguation, limit, symbol, projectPath semantics). The tool description itself adds no parameter-specific guidance, so it earns the baseline 3 rather than higher.

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 ('List') and resource ('functions that call <symbol>'), making the tool's purpose immediately clear. It also distinguishes itself from the sibling by pointing to codegraph_explore for the broader flow, and the name 'codegraph_callers' aligns cleanly with this purpose.

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 gives a clear routing hint: 'For the full flow, use codegraph_explore.' This tells an agent when a broader alternative is appropriate. It does not explicitly mention codegraph_callees for downstream callers or state exclusions, but the caller-vs-full-flow distinction provides useful, non-misleading context.

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