Skip to main content
Glama

earthquake-mcp-server

by io.github.cyanheads

Count Earthquakes

earthquake_count
Read-onlyIdempotent

Count earthquakes matching filters without fetching full records. Use for statistical queries ("how many M5+ earthquakes in 2025?") or to gauge result size before calling earthquake_search. Omitting start_time counts only the last 30 days, so pass an explicit range for any period-specific question; queryEcho reports the window and filters the count actually covers. When exceeds_limit is true, the count exceeds 20,000 and a full search would be truncated — narrow filters before fetching. USGS returns the max_allowed cap (20,000); EMSC count endpoint does not return this field (max_allowed will be null). Counts can be scoped to a rectangular study area with min_latitude, max_latitude, min_longitude, and max_longitude — each independently optional. Combining the box with the lat/lon/radius circle intersects the two, counting only events inside both. Both catalogs include non-tectonic records, so a radius over a mining region counts quarry blasts alongside earthquakes — pass event_type="earthquake" on USGS to exclude them. USGS-specific filters (alert_level, event_type, min_felt, min_significance) are not sent when source=emsc — the response names them in ignoredFilters.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
sourceNoData source. Both catalogs are global. "usgs" covers global events with PAGER, DYFI, and ShakeMap metadata. "emsc" is an independent global catalog operated by the European-Mediterranean Seismological Centre — use it to cross-check a count from a separate network. It has no PAGER, DYFI, or ShakeMap metadata; its station coverage is densest around Europe and the Mediterranean, so counts of small events differ most by region.usgs
end_timeNoEnd of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted.
latitudeNoLatitude for radius search. Requires longitude and radius_km.
min_feltNoMinimum number of DYFI (Did You Feel It?) reports. Use to count events with confirmed public impact. Only available from USGS.
longitudeNoLongitude for radius search. Requires latitude and radius_km.
radius_kmNoSearch radius in kilometers from the lat/lon point. Max 20001.6, the ceiling USGS enforces — half the Earth's great-circle circumference. Converted to degrees for EMSC (1° ≈ 111.2 km).
event_typeNoFilter by upstream event classification, e.g. "earthquake" to exclude quarry blasts and explosions from the count, or "quarry blast" to count only those. Matched verbatim against the USGS catalog, which accepts any string and returns a count of zero for an unrecognized one. Only available from USGS.
start_timeNoStart of time range as ISO 8601 (e.g. "2026-01-01" or "2026-05-23T00:00:00"). A bare year expands to January 1st and an unpadded month or day is zero-padded, so both sources honor the same window. Defaults to 30 days before end_time (or before the current time) if omitted — applied server-side so USGS and EMSC honor the same window.
alert_levelNoMinimum PAGER alert level. PAGER estimates economic loss and casualties. "green" = minimal impact; "red" = extreme. Only available from USGS.
max_depth_kmNoMaximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope.
max_latitudeNoNorthern edge of a bounding-box search, in degrees.
min_depth_kmNoMinimum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km).
min_latitudeNoSouthern edge of a bounding-box search, in degrees. Independent of the other three box parameters — supply any of them. Must not exceed max_latitude when both are given.
max_longitudeNoEastern edge of a bounding-box search, in degrees.
max_magnitudeNoMaximum magnitude.
min_longitudeNoWestern edge of a bounding-box search, in degrees. Range extends beyond ±180 so a box can cross the antimeridian (e.g. min_longitude=170, max_longitude=190) — always keep min_longitude at or below max_longitude rather than inverting the pair.
min_magnitudeNoMinimum magnitude (Richter or equivalent). M2.5+ is felt by some people; M5+ can cause damage; M7+ is major.
min_significanceNoMinimum USGS significance score (0–2000+). Combines magnitude, felt reports, and PAGER estimates. Significant events typically score 600+. Only available from USGS.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNoNumber of events matching the query.
errorNoPresent when the call failed. Absent on success.
sourceNoData source used.
queryEchoNoEcho of the effective parameters the count covers, including server-resolved defaults. Read start_time and end_time to know which window the count spans — a filter absent here was not sent upstream.
max_allowedNoMaximum events the API would return for a full fetch. 20000 for USGS. Null for EMSC — the EMSC count endpoint does not return this field.
exceeds_limitNoTrue when count exceeds 20000 — a full earthquake_search would be truncated. For EMSC, evaluated against the known 20000 limit since max_allowed is not returned. Narrow filters to retrieve all matching events.
ignoredFiltersNoUSGS-only filters supplied in the input but not sent upstream because source=emsc does not support them. The count is NOT constrained by these — re-run with source=usgs to apply them. Absent when every supplied filter was applied.

TDQS

A5/5.0
Behavior5/5

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

Annotations declare readOnly, openWorld, and idempotent hints, but the description adds substantial behavioral context: the default 30-day window, the 20,000 cap and exceeds_limit flag, EMSC's lack of max_allowed, non-tectonic records inclusion, and ignoredFilters for EMSC. This goes far beyond the annotations, enriching the agent's understanding of what happens 'under the hood.'

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence earns its place. It front-loads the core purpose, then layers specific behavioral caveats in a logical order. There is no fluff; the density is justified by the tool's complexity (18 params, dual sources).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description covers all critical pitfalls: time-range defaults, result caps, source-specific behavior, filter interactions, and the queryEcho mechanism. Since an output schema exists, the description need not explain return values, but it still provides enough context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Though schema coverage is 100%, the description adds cross-parameter semantics not in the schema: the intersection of bounding box and radius circle, the independent optionality of box parameters, and the effect of omitting start_time. It also explains how event_type 'earthquake' excludes quarry blasts but isn't sent to EMSC, which is critical for accurate counts.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with the specific verb 'Count' and resource 'earthquakes matching filters,' immediately distinguishing it from earthquake_search. It explicitly states the tool counts without fetching full records and gives concrete examples of statistical queries, making the purpose unambiguous and distinguishable from sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use for statistical queries... or to gauge result size before calling earthquake_search.' It also covers edge cases like the 30-day default, the exceeds_limit behavior with a directive to narrow filters, and cross-source differences (USGS vs. EMSC). This is comprehensive routing advice.

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

All earthquake-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.7/5.0
Disambiguation5/5

Each tool serves a clear, distinct purpose: count for statistical queries, search for filtered record retrieval, feed for pre-computed real-time data, and get_event for per-event detail. Overlap between count and search is explicitly addressed with guidance on when to use each. No two tools appear interchangeable.

Naming Consistency5/5

All tools follow the consistent pattern of earthquake_ + verb (count, get_event, get_feed, search), making the action and resource unambiguous. The naming is uniform across all four tools, with no mixed conventions or vague verbs.

Tool Count5/5

With 4 tools, the surface is tightly scoped and each tool covers a necessary operation for the domain. This is well within the ideal 3-15 range and neither feels thin nor overloaded for an earthquake data server.

Completeness5/5

The tool set covers the core workflows: searching with rich filters, counting for statistics, retrieving detailed event info, and accessing real-time feeds. No significant gaps are apparent—the server supports both USGS and EMSC sources, and the read-only nature is appropriate for the domain.

Resources