fdsn_query_earthquakes

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds non-redundant behavioral context: return format is 'compact tabular result (columns + rows)', depth is in kilometers, pagination via 'offset + returned_count', and that preferred origin/magnitude are used. 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?

Descriptions is well-structured with a purpose sentence, return format note, common examples, and datacenter list. It is somewhat long but each section earns its place; no fluff. Could be slightly more compact, but the examples provide high value.

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 the tool has 19 parameters, 0% schema coverage, and an output schema, the description covers the essential operational aspects: return shape, unit convention, pagination, datacenter choice, and alternates. It addresses the main gaps an agent would encounter when selecting and invoking this tool.

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 has 0% description coverage, so the description bears the burden. It provides illustrative parameter combinations (minmag/starttime, minlat/maxlat/minlon/maxlon, latitude/longitude/maxradiuskm, orderby/limit, offset), and clarifies units and pagination semantics. However, not every parameter is explained individually (e.g., endtime, updatedafter, minradiuskm), so it is strong but not exhaustive.

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 explicitly states 'Query earthquake events from an FDSN datacenter with flexible parameters' – a specific verb and resource. It distinguishes from sibling by-id tools by mentioning 'For the full detail of a single event (all origins/magnitudes, arrivals, focal mechanism) use the by-id tools.'

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?

Provides multiple concrete usage examples (recent events, significant events, geographic area, radial search, pagination), explicitly says the by-id tools are for single-event details, and lists available datacenters. This gives clear when/what-to-use guidance.

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