USGS — US Volcano Catalog

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

Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds valuable behavioral context: the catalog is complete ('all 170'), includes specific regions, and the optional region filter is a substring match. It also discloses the data source (USGS Volcano Hazards Program) and public domain status. The only minor gap is not describing pagination or response size, but the output schema exists and the description is otherwise transparent.

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 compact and front-loaded: it opens with the core action and scope, then details the fields, then the optional filter, then use cases, then auth. Every sentence adds value. The field enumeration is dense but necessary for an agent to know what data is returned. No filler or repetition of the schema.

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 catalog tool with one optional parameter, an output schema, and full annotation coverage, the description is complete. It tells the agent what data is returned (field list), how to filter, when to use it, and that no auth is needed. The output schema covers return structure, so the description doesn't need to explain that. Nothing an agent needs to call this correctly is missing.

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 'region' parameter, and the schema already describes it as a 'Filter by region name substring' with examples. The description reinforces this by saying 'Optionally filter by region substring (e.g. "Alaska", "Hawaii", "Cascades")' and adds the context that the filter is a substring match. Since the schema already covers the parameter well, the description's reinforcement earns a 4 rather than a 3 because it clarifies the substring semantics and provides additional examples.

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 ('Get'), a precise resource ('full catalog of all 170 US volcanoes tracked by the USGS Volcano Hazards Program'), and enumerates the included regions. It also lists the exact fields in each entry, which distinguishes it from sibling tools like volcano.catalog.detail and volcano.alerts.cap. The scope is unambiguous.

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: 'Use to enumerate all US volcanoes, discover IDs, or build regional hazard maps.' It also explains the optional region filter with examples. While it doesn't name a specific alternative tool, the context signals show siblings like volcano.catalog.detail and volcano.alerts.cap, and the description's clear scope makes the usage context obvious. The 'No auth — USGS public domain' note also clarifies access requirements.

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