USGS — CAP Volcanic Alerts

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, covering safety. The description adds useful behavioral context: only volcanoes that have been at ORANGE or above appear, it returns previous alert state and other specific fields, and it notes 'No auth — USGS public domain.' No contradiction with annotations.

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 multi-sentence but each sentence contributes: definition, context, returned fields, scope condition, use cases, and auth. It is front-loaded with the primary action and avoids fluff.

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?

An output schema exists, so return format is covered. The description explains the data scope, filtering (implicit via parameter), use cases, and authentication requirements. The only minor gap is the alert level terminology mismatch, but it doesn't prevent correct invocation.

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?

The input schema fully documents the single parameter with an enum and description, achieving 100% schema coverage. The description does not add meaningful semantics beyond the schema, and actually introduces potential confusion by mentioning ORANGE/WATCH while the parameter allows ADVISORY. Per the baseline for high schema coverage, a 3 is appropriate.

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 clearly states the verb (Get), the resource (Common Alerting Protocol information for highly elevated volcanoes), and the scope (ORANGE/WATCH or higher). It also lists the specific fields returned, which distinguishes it from other volcano tools that provide different data such as status or notices.

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 provides explicit use cases: integration with emergency management systems, aviation NOTAM workflows, and real-time public alerting pipelines. This gives clear context for when to use the tool, though it doesn't explicitly mention alternatives or situations where it should not be used.

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