blast_radius

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

The description discloses the recursive traversal behavior and the depth parameter, which is useful. However, with no annotations provided, the description carries the full burden of behavioral disclosure. It doesn't mention whether this is a read-only operation, whether it executes code, or what the output format looks like. The 'max_queries' parameter hints at a query budget but the description doesn't explain what happens when the budget is exhausted.

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 sentences with zero waste. The core behavior is front-loaded ('What breaks if this symbol changes'), and the usage guidance is a natural second sentence. Every word 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?

For a read-only analysis tool with 100% schema coverage, the description is nearly complete. It explains the transitive behavior, the depth parameter, and when to use it. The only gap is the lack of detail about the output format and what happens when max_queries is hit, but these are minor given the schema covers the parameters.

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 the schema already documents all three parameters. The description adds context for 'depth' by explaining the transitive hops behavior, but doesn't add meaning beyond the schema for 'name' or 'max_queries'. Baseline 3 is appropriate since the schema does the heavy lifting.

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 uses a specific verb ('breaks') and resource ('symbol'), and clearly states the transitive behavior ('everything that references it, then everything that references those, to the given depth'). It distinguishes itself from siblings like find_references by emphasizing the recursive blast-radius analysis rather than just direct references.

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 explicitly states when to use this tool: 'Run before changing a signature or deleting anything.' This provides clear context and implies it is a pre-refactoring safety check, distinguishing it from alternatives like find_references or rename_symbol.

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