mineral_sites

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

With no annotations, the description carries the full burden and does real work: it discloses the empty-result failure mode, the ~300k site catalogue scale that motivates the bbox requirement, and the code-vs-name matching behavior of `commodity`. It omits auth/rate-limit and pagination behavior, so it falls short of a 5.

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 core constraint is front-loaded in the first sentence and the two follow-up notes are terse and non-redundant. Slightly fragmented line breaks add no information, but there is no wasted prose.

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 values need not be explained; the description covers the essential call-correctly facts (bbox required and format, commodity coding). The only material hole is the undocumented `detail` parameter, which could change result size or shape.

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 coverage is 0%, so the description must compensate: it does so well for `bbox` (explicit lon_min,lat_min,lon_max,lat_max ordering and requiredness) and `commodity` (MRDS code like "CU"/"AU", not a name). The third parameter, `detail` (default "short"), is never mentioned in the schema or the description, leaving its allowed values and effect unknown.

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 first line names a specific resource (USGS MRDS mineral deposit sites) and its spatial scope (inside a bbox), so the agent knows exactly what is retrieved. It does not need to be differentiated from a sibling because no other mineral/deposit tool exists in the list, but it also never states the verb explicitly (list/query).

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?

It gives a clear precondition: bbox is REQUIRED for data, and without a viewport the tool answers an empty collection — an agent that reads this will always supply a bbox. It does not point to alternatives for catalog-wide browsing, but none of the listed siblings appear to cover that case.

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