analyze_blast_radius

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds meaningful behavioral context beyond those annotations by disclosing the traversal mechanism, the downstream-impact identification, and the 0-100 scoring range. It does not contradict any annotation, though it omits performance/cost implications of deep traversal on large topologies.

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 totaling about 25 words, with the core purpose front-loaded in the first sentence and the mechanism plus output format in the second. There is zero filler or redundancy, and every clause adds distinguishing information.

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 moderate-complexity read-only tool, the description covers purpose, mechanism, and score range, while annotations handle the safety profile and the schema has 100% parameter coverage. A minor gap remains: with no output schema present, the description does not fully clarify whether the returned result includes the identified downstream device set in addition to the score, though 'identifies downstream impact' partially implies it.

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 both device_id and depth are already documented ('Device ID to analyze' and 'Max traversal depth (1-3)'). The description adds only marginal reinforcement by connecting depth to the traversal behavior and device_id to 'device failure', but no new syntax, format, or edge-case meaning is provided beyond the schema. Baseline 3 is appropriate given full schema coverage.

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 action ('Analyze the blast radius of a device failure'), the resource/domain ('using topology data'), and the mechanism ('Traverses neighbors to identify downstream impact'). It also specifies the output ('scores overall blast radius (0-100)'), which further disambiguates it from siblings like get_device_neighbors or get_device_connections that merely list relationships.

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 clear contextual signals about when this tool is appropriate: when assessing failure impact, since it explicitly mentions 'device failure', 'downstream impact', and traversal. However, it does not explicitly name alternatives to avoid (e.g., get_device_neighbors for immediate neighbors only) or state when-not-to-use conditions, stopping just short of fully explicit routing guidance.

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