USGS — Elevated Alert Volcanoes

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

Annotations already declare readOnly, openWorld, idempotent, and non-destructive hints. The description adds substantial behavioral context beyond those annotations: the empty-array result when all volcanoes are NORMAL/GREEN, the exact returned fields, the no-auth public-domain status, and the near-real-time update cadence. No contradiction exists.

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 five sentences long, with every sentence earning its place: scope, returned fields, empty behavior, target use cases, and data provenance/freshness. It is front-loaded with the core purpose and contains no filler.

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?

Given that the tool has a rich output schema and the annotations cover the safety profile, the description still covers everything an agent needs: exactly what is returned, when an empty array occurs, who this data serves, and operational facts like auth and update latency. The presence of an output schema makes deeper return-value documentation unnecessary.

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% for the single optional color_code parameter, including its enum values and meanings. The description reinforces the filtering concept but does not add parameter-level detail beyond what the schema already provides, matching the baseline for 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 verb and resource ('Get all US volcanoes currently in an elevated state') and precisely enumerates the color codes and alert levels. It is clear and unambiguous, but it does not explicitly differentiate itself from sibling volcano tools such as volcano.status.monitored, falling just short of full sibling distinction.

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?

Concrete use cases are provided ('Ideal for real-time hazard monitoring dashboards and aviation safety agents') and the scope is clarified (only elevated, active-unrest volcanoes). However, it does not explicitly state when to prefer an alternative tool or when not to use it, so it stops short of full guidance.

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