Skip to main content
Glama

earthquake-mcp-server

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.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed2 schema fields changed
    • removedOutput schema / properties / max_allowed / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / max_allowed / type
      Added value: +[
      +  "number",
      +  "null"
      +]
  2. Changed6 schema fields changed
    • changedInput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedInput schema / additionalProperties
      Added value: +false
    • changedOutput schema / $schema
      Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"
    • addedOutput schema / anyOf
      Added value: +[
      +  {
      +    "not": {
      +      "required": [
      +        "error"
      +      ]
      +    },
      +    "required": [
      +      "count",
      +      "max_allowed",
      +      "source",
      +      "exceeds_limit"
      +    ]
      +  },
      +  {
      +    "required": [
      +      "error"
      +    ]
      +  }
      +]
    • addedOutput schema / properties / error
      Added value: +{
      +  "additionalProperties": {},
      +  "description": "Present when the call failed. Absent on success.",
      +  "properties": {
      +    "code": {
      +      "description": "JSON-RPC error code for this failure.",
      +      "maximum": 9007199254740991,
      +      "minimum": -9007199254740991,
      +      "type": "integer"
      +    },
      +    "data": {
      +      "additionalProperties": {},
      +      "properties": {
      +        "reason": {
      +          "description": "Machine-readable failure mode. Declared by this tool: `invalid_radius`: latitude or longitude provided without radius_km, or vice versa. `invalid_bounding_box`: min_latitude exceeds max_latitude, or min_longitude exceeds max_longitude. `source_unavailable`: Selected source API returns a 5xx or is unreachable. `source_timeout`: Selected source API did not answer before the request deadline. `upstream_rejected`: The source API rejected the query parameters and explained why in its response body. `upstream_rejected_no_reason`: The source API rejected the query but its response body carried no usable explanation. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "invalid_radius",
      +            "invalid_bounding_box",
      +            "source_unavailable",
      +            "source_timeout",
      +            "upstream_rejected",
      +            "upstream_rejected_no_reason"
      +          ],
      +          "type": "string"
      +        },
      +        "recovery": {
      +          "additionalProperties": {},
      +          "description": "Actionable next step for the caller.",
      +          "properties": {
      +            "hint": {
      +              "type": "string"
      +            }
      +          },
      +          "required": [
      +            "hint"
      +          ],
      +          "type": "object"
      +        },
      +        "retryable": {
      +          "description": "Whether retrying may succeed.",
      +          "type": "boolean"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "message": {
      +      "description": "Human-readable description of what went wrong.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "code",
      +    "message"
      +  ],
      +  "type": "object"
      +}
    • removedOutput schema / required
      Removed value: -[
      -  "count",
      -  "max_allowed",
      -  "source",
      -  "exceeds_limit"
      -]
  3. Changed21 schema fields changed
    • changedInput schema / properties / end_time / description
      Previous value: -"End of time range as ISO 8601. Defaults to current time if omitted."New value: +"End of time range as ISO 8601, in the same forms start_time accepts. Defaults to current time if omitted."
    • addedInput schema / properties / end_time / pattern
      Added value: +"^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    • addedInput schema / properties / event_type / minLength
      Added value: +1
    • changedInput schema / properties / max_depth_km / description
      Previous value: -"Maximum depth in kilometers."New value: +"Maximum depth in kilometers. Bounded to the documented -100 to 1000 km catalog envelope."
    • addedInput schema / properties / max_depth_km / maximum
      Added value: +1000
    • addedInput schema / properties / max_depth_km / minimum
      Added value: +-100
    • addedInput schema / properties / max_latitude
      Added value: +{
      +  "description": "Northern edge of a bounding-box search, in degrees.",
      +  "maximum": 90,
      +  "minimum": -90,
      +  "type": "number"
      +}
    • addedInput schema / properties / max_longitude
      Added value: +{
      +  "description": "Eastern edge of a bounding-box search, in degrees.",
      +  "maximum": 360,
      +  "minimum": -360,
      +  "type": "number"
      +}
    • changedInput schema / properties / min_depth_km / description
      Previous value: -"Minimum depth in kilometers. Shallow quakes (0–70 km) typically cause more surface damage than deep quakes (>300 km)."New value: +"Minimum 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)."
    • addedInput schema / properties / min_depth_km / maximum
      Added value: +1000
    • addedInput schema / properties / min_depth_km / minimum
      Added value: +-100
    • addedInput schema / properties / min_latitude
      Added value: +{
      +  "description": "Southern 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.",
      +  "maximum": 90,
      +  "minimum": -90,
      +  "type": "number"
      +}
    • addedInput schema / properties / min_longitude
      Added value: +{
      +  "description": "Western 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.",
      +  "maximum": 360,
      +  "minimum": -360,
      +  "type": "number"
      +}
    • changedInput schema / properties / radius_km / description
      Previous value: -"Search radius in kilometers from the lat/lon point. Converted to degrees for EMSC (1° ≈ 111.2 km)."New value: +"Search 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)."
    • changedInput schema / properties / radius_km / maximum
      Previous value: -20002New value: +20001.6
    • changedInput schema / properties / start_time / description
      Previous value: -"Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). 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."New value: +"Start 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."
    • addedInput schema / properties / start_time / pattern
      Added value: +"^\\d{4}(-\\d{1,2}(-\\d{1,2})?)?([T ]\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$"
    • addedOutput schema / properties / queryEcho / properties / max_latitude
      Added value: +{
      +  "description": "Northern bounding-box edge sent upstream, in degrees.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / queryEcho / properties / max_longitude
      Added value: +{
      +  "description": "Eastern bounding-box edge sent upstream, in degrees.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / queryEcho / properties / min_latitude
      Added value: +{
      +  "description": "Southern bounding-box edge sent upstream, in degrees.",
      +  "type": "number"
      +}
    • addedOutput schema / properties / queryEcho / properties / min_longitude
      Added value: +{
      +  "description": "Western bounding-box edge sent upstream, in degrees.",
      +  "type": "number"
      +}
  4. Changed2 schema fields changed
    • addedInput schema / properties / event_type
      Added value: +{
      +  "description": "Filter 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.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / queryEcho / properties / event_type
      Added value: +{
      +  "description": "Event-type filter sent upstream. Absent for EMSC — not supported there.",
      +  "type": "string"
      +}
  5. Changed2 schema fields changed
    • changedInput schema / properties / source / description
      Previous value: -"Data source. \"usgs\" covers global events with PAGER, DYFI, and ShakeMap metadata. \"emsc\" covers the European-Mediterranean region."New value: +"Data 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."
    • addedOutput schema / properties / ignoredFilters
      Added value: +{
      +  "description": "USGS-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.",
      +  "items": {
      +    "description": "Name of an input filter that was not applied.",
      +    "type": "string"
      +  },
      +  "type": "array"
      +}
  6. Changed1 schema field changed
    • addedOutput schema / properties / queryEcho
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Echo 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.",
      +  "properties": {
      +    "alert_level": {
      +      "description": "PAGER alert filter sent upstream. Absent for EMSC — not supported there.",
      +      "type": "string"
      +    },
      +    "end_time": {
      +      "description": "Effective query end time. Absent when omitted from input — the upstream defaults to the current time.",
      +      "type": "string"
      +    },
      +    "latitude": {
      +      "description": "Radius-search latitude sent upstream.",
      +      "type": "number"
      +    },
      +    "longitude": {
      +      "description": "Radius-search longitude sent upstream.",
      +      "type": "number"
      +    },
      +    "max_depth_km": {
      +      "description": "Maximum depth filter sent upstream.",
      +      "type": "number"
      +    },
      +    "max_magnitude": {
      +      "description": "Maximum magnitude filter sent upstream.",
      +      "type": "number"
      +    },
      +    "min_depth_km": {
      +      "description": "Minimum depth filter sent upstream.",
      +      "type": "number"
      +    },
      +    "min_felt": {
      +      "description": "DYFI felt-report filter sent upstream. Absent for EMSC — not supported there.",
      +      "type": "number"
      +    },
      +    "min_magnitude": {
      +      "description": "Minimum magnitude filter sent upstream.",
      +      "type": "number"
      +    },
      +    "min_significance": {
      +      "description": "Significance filter sent upstream. Absent for EMSC — not supported there.",
      +      "type": "number"
      +    },
      +    "radius_km": {
      +      "description": "Search radius in km sent upstream (converted to degrees for EMSC).",
      +      "type": "number"
      +    },
      +    "source": {
      +      "description": "Data source queried.",
      +      "enum": [
      +        "usgs",
      +        "emsc"
      +      ],
      +      "type": "string"
      +    },
      +    "start_time": {
      +      "description": "Effective query start time sent upstream — server-resolved to a 30-day window when omitted from input.",
      +      "type": "string"
      +    }
      +  },
      +  "required": [
      +    "source"
      +  ],
      +  "type": "object"
      +}
  7. Changed1 schema field changed
    • changedInput schema / properties / start_time / description
      Previous value: -"Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). Defaults to 30 days before end_time if omitted."New value: +"Start of time range as ISO 8601 (e.g. \"2026-01-01\" or \"2026-05-23T00:00:00\"). 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."
  8. First observed

TDQS

A4.7/5.0
Behavior4/5

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

Adds substantial behavior beyond the readOnly/openWorld/idempotent annotations: the 20,000 cap, exceeds_limit truncation semantics, the USGS vs EMSC max_allowed discrepancy, ignoredFilters for unsupported filters, and the default 30-day window. These are real operational traits not captured by annotations.

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

Conciseness4/5

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

Front-loads what the tool does and the key default trap, then layers caveats. Dense but every sentence carries operational weight (caps, intersections, source divergence). Slightly long, but not padded.

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?

An 18-parameter, filter-heavy count tool with an output schema is fully covered: the description explains the default window, the cap, exceed behavior, source-specific filter dropping, and spatial intersection — everything an agent needs to call it correctly and interpret the result.

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?

Adds meaning beyond the already 100%-covered schema: the bounding-box params are independently optional, the box intersects the circle, event_type='earthquake' excludes quarry blasts, and source=emsc triggers ignoredFilters for USGS-only params. This is genuine cross-parameter semantics the schema cannot express.

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?

States a precise verb+resource with scope: 'Count earthquakes matching filters without fetching full records.' Explicitly contrasts with the sibling earthquake_search by positioning it as a gauge-before-fetch tool. An agent can distinguish count vs. get_event vs. search without opening schemas.

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?

Gives an explicit when-to-use ('statistical queries, or to gauge result size before calling earthquake_search'), names the sibling alternative, and specifies the start_time default trap. The exceeds_limit guidance tells the agent exactly what to do next (narrow filters), which is actionable routing.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.