Skip to main content
Glama

earthquake-mcp-server

Get Earthquake Event Detail

earthquake_get_event
Read-onlyIdempotent

Fetch detail for a specific earthquake by USGS event ID. Returns the same normalized event a search result carries, plus a projection of the analysis products only the single-event response holds: PAGER impact alert and report link, ShakeMap peak intensity and ground motion, DYFI felt-report totals, the moment-tensor focal mechanism, landslide and liquefaction alerts, origin quality (azimuthal gap, station count, location uncertainty), and finite-fault rupture dimensions. Products are omitted when USGS produced none — a small automatic event typically has no detail at all, while a large reviewed one has most of it. Event IDs appear in the "id" field of earthquake_get_feed and earthquake_search results. This tool is USGS-only — EMSC events have no per-event detail endpoint.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
event_idYesUSGS event ID, e.g. "hv74966427" or "us6000sznj". Found in the "id" field of earthquake_get_feed and earthquake_search results.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
eventNoFull earthquake event detail.
detailNoAnalysis products USGS attached to this event. Absent when the event carries none — that means no product was produced, not that impact was zero.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed14 schema fields changed
    • removedOutput schema / properties / event / properties / cdi / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / cdi / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / depth_km / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / depth_km / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / felt / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / felt / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / magnitude / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / magnitude / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / mmi / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / mmi / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / significance / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / significance / type
      Added value: +[
      +  "number",
      +  "null"
      +]
    • removedOutput schema / properties / event / properties / tsunami / anyOf
      Removed value: -[
      -  {
      -    "type": "number"
      -  },
      -  {
      -    "type": "null"
      -  }
      -]
    • addedOutput schema / properties / event / properties / tsunami / 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": [
      +      "event"
      +    ]
      +  },
      +  {
      +    "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: `not_found`: No event matches the provided event_id. `source_unavailable`: The USGS event API returns a 5xx, serves HTML, or is unreachable. `source_timeout`: The USGS event API did not answer before the request deadline. Other values are possible when a failure originates below the handler.",
      +          "examples": [
      +            "not_found",
      +            "source_unavailable",
      +            "source_timeout"
      +          ],
      +          "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: -[
      -  "event"
      -]
  3. Changed3 schema fields changed
    • changedOutput schema / properties / detail / properties / shakemap / properties / max_pga / description
      Previous value: -"Maximum modeled peak ground acceleration, in percent of g."New value: +"Maximum modeled peak ground acceleration, in g — a fraction of standard gravity, as USGS ShakeMap publishes it (0.4 is four tenths of g)."
    • addedOutput schema / properties / event / properties / event_certainty
      Added value: +{
      +  "description": "How certain the source is of event_type: \"known\" (asserted), \"suspected\", \"unknown\", or \"unreported\". EMSC publishes this as the first character of its event-type code — a suspected explosion is not a confirmed one, and this is the only field that says so. Absent for USGS, which publishes no certainty axis, and absent for an EMSC code outside the published nomenclature.",
      +  "enum": [
      +    "known",
      +    "suspected",
      +    "unknown",
      +    "unreported"
      +  ],
      +  "type": "string"
      +}
    • changedOutput schema / properties / event / properties / event_type / description
      Previous value: -"Upstream event classification. USGS spells it out — \"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\" — while EMSC publishes a two-letter evtype code, \"ke\" for a known earthquake and \"ue\" for an unknown event. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification."New value: +"What kind of event this is, in one vocabulary whichever source served it — the QuakeML type names USGS publishes (\"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\"). EMSC's two-character code is decoded to the same names, so the same event carries the same value from either source; how sure the source is rides on event_certainty instead. A code outside the published nomenclature is forwarded verbatim rather than guessed at. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification."
  4. Changed2 schema fields changed
    • addedOutput schema / properties / detail
      Added value: +{
      +  "additionalProperties": false,
      +  "description": "Analysis products USGS attached to this event. Absent when the event carries none — that means no product was produced, not that impact was zero.",
      +  "properties": {
      +    "dyfi": {
      +      "additionalProperties": false,
      +      "description": "Felt-report summary. Absent when no DYFI product exists for the event.",
      +      "properties": {
      +        "map_url": {
      +          "description": "URL of the rendered DYFI intensity map image.",
      +          "type": "string"
      +        },
      +        "max_cdi": {
      +          "description": "Maximum Community Decimal Intensity derived from those reports (0–12 scale).",
      +          "type": "number"
      +        },
      +        "responses": {
      +          "description": "Number of \"Did You Feel It?\" reports the public submitted.",
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "finite_fault": {
      +      "additionalProperties": false,
      +      "description": "Finite-fault rupture model. Produced only for large events.",
      +      "properties": {
      +        "model_url": {
      +          "description": "URL of the finite-fault rupture model file.",
      +          "type": "string"
      +        },
      +        "rupture_length_km": {
      +          "description": "Modeled rupture length along strike, in kilometers.",
      +          "type": "number"
      +        },
      +        "rupture_width_km": {
      +          "description": "Modeled rupture width down dip, in kilometers.",
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "ground_failure": {
      +      "additionalProperties": false,
      +      "description": "Secondary-hazard alert levels. Absent when no ground-failure model was run.",
      +      "properties": {
      +        "landslide_alert": {
      +          "description": "Landslide hazard alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
      +          "type": "string"
      +        },
      +        "liquefaction_alert": {
      +          "description": "Liquefaction hazard alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "losspager": {
      +      "additionalProperties": false,
      +      "description": "PAGER impact assessment. Estimated fatality and economic-loss brackets live in a separate content file and are not part of this response — fetch report_url for them.",
      +      "properties": {
      +        "alert_level": {
      +          "description": "PAGER impact alert level — \"green\", \"yellow\", \"orange\", or \"red\".",
      +          "type": "string"
      +        },
      +        "report_url": {
      +          "description": "URL of the PAGER one-page PDF summary of estimated impact.",
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "moment_tensor": {
      +      "additionalProperties": false,
      +      "description": "Focal-mechanism solution. Absent for events with no moment-tensor inversion.",
      +      "properties": {
      +        "derived_depth_km": {
      +          "description": "Centroid depth in kilometers derived from the moment-tensor inversion.",
      +          "type": "number"
      +        },
      +        "nodal_plane_1": {
      +          "additionalProperties": false,
      +          "description": "First nodal plane of the focal mechanism. Either plane can be the true fault.",
      +          "properties": {
      +            "dip": {
      +              "description": "Fault plane dip in degrees from horizontal (0–90).",
      +              "type": "number"
      +            },
      +            "rake": {
      +              "description": "Slip direction in degrees (-180 to 180). Near 90 is reverse faulting, near -90 normal, near 0 or 180 strike-slip.",
      +              "type": "number"
      +            },
      +            "strike": {
      +              "description": "Fault plane strike in degrees clockwise from north (0–360).",
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "strike",
      +            "dip",
      +            "rake"
      +          ],
      +          "type": "object"
      +        },
      +        "nodal_plane_2": {
      +          "additionalProperties": false,
      +          "description": "Second nodal plane — the auxiliary solution, indistinguishable from the first on seismic data alone.",
      +          "properties": {
      +            "dip": {
      +              "description": "Fault plane dip in degrees from horizontal (0–90).",
      +              "type": "number"
      +            },
      +            "rake": {
      +              "description": "Slip direction in degrees (-180 to 180). Near 90 is reverse faulting, near -90 normal, near 0 or 180 strike-slip.",
      +              "type": "number"
      +            },
      +            "strike": {
      +              "description": "Fault plane strike in degrees clockwise from north (0–360).",
      +              "type": "number"
      +            }
      +          },
      +          "required": [
      +            "strike",
      +            "dip",
      +            "rake"
      +          ],
      +          "type": "object"
      +        },
      +        "scalar_moment_nm": {
      +          "description": "Scalar seismic moment in newton-metres — the physical size of the rupture.",
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "origin": {
      +      "additionalProperties": false,
      +      "description": "Location-quality metrics for the preferred origin.",
      +      "properties": {
      +        "azimuthal_gap_deg": {
      +          "description": "Largest azimuthal gap between stations, in degrees. Gaps above ~180 make the location poorly constrained.",
      +          "type": "number"
      +        },
      +        "depth_error_km": {
      +          "description": "Depth uncertainty in kilometers.",
      +          "type": "number"
      +        },
      +        "horizontal_error_km": {
      +          "description": "Horizontal location uncertainty in kilometers.",
      +          "type": "number"
      +        },
      +        "num_stations_used": {
      +          "description": "Number of seismic stations used in the location solution.",
      +          "type": "number"
      +        },
      +        "review_status": {
      +          "description": "Review state of the origin solution as the contributing network published it.",
      +          "type": "string"
      +        }
      +      },
      +      "type": "object"
      +    },
      +    "shakemap": {
      +      "additionalProperties": false,
      +      "description": "ShakeMap modeled ground-motion summary. Absent when no ShakeMap was produced.",
      +      "properties": {
      +        "intensity_map_url": {
      +          "description": "URL of the rendered ShakeMap intensity map image.",
      +          "type": "string"
      +        },
      +        "max_mmi": {
      +          "description": "Maximum modeled shaking intensity across the ShakeMap grid (Modified Mercalli).",
      +          "type": "number"
      +        },
      +        "max_pga": {
      +          "description": "Maximum modeled peak ground acceleration, in percent of g.",
      +          "type": "number"
      +        },
      +        "max_pgv": {
      +          "description": "Maximum modeled peak ground velocity, in cm/s.",
      +          "type": "number"
      +        }
      +      },
      +      "type": "object"
      +    }
      +  },
      +  "type": "object"
      +}
    • addedOutput schema / properties / event / properties / event_type
      Added value: +{
      +  "description": "Upstream event classification. USGS spells it out — \"earthquake\", \"quarry blast\", \"explosion\", \"ice quake\" — while EMSC publishes a two-letter evtype code, \"ke\" for a known earthquake and \"ue\" for an unknown event. Not every record in either catalog is a tectonic earthquake. Absent when the source publishes no classification.",
      +  "type": "string"
      +}
  5. Changed14 schema fields changed
    • changedOutput schema / properties / event / properties / alert / description
      Previous value: -"PAGER estimated impact alert level. Null if not computed. USGS only."New value: +"PAGER estimated impact alert level. Null when USGS ran no PAGER assessment, and always null for EMSC, which publishes no such field."
    • addedOutput schema / properties / event / properties / auth
      Added value: +{
      +  "description": "Code of the agency or network the source names as authoritative for this solution, e.g. \"NEIC\", \"BMKG\", \"NDI\" from EMSC or \"us\", \"ci\", \"ak\" from USGS. Absent when the source reports none.",
      +  "type": "string"
      +}
    • changedOutput schema / properties / event / properties / cdi / description
      Previous value: -"Maximum reported intensity (Community Decimal Intensity, 0–12 scale). USGS only."New value: +"Maximum reported intensity (Community Decimal Intensity, 0–12 scale), derived from DYFI responses. Null when USGS computed no DYFI intensity, and always null for EMSC, which publishes no such field."
    • changedOutput schema / properties / event / properties / felt / description
      Previous value: -"Number of DYFI (Did You Feel It?) responses. Null if no reports. USGS only."New value: +"Number of DYFI (Did You Feel It?) responses. Null when USGS has received no reports for the event, and always null for EMSC, which publishes no DYFI field — a null is not evidence the event went unfelt."
    • changedOutput schema / properties / event / properties / mmi / description
      Previous value: -"Maximum ShakeMap instrumental intensity (Modified Mercalli, 0–12 scale). USGS only."New value: +"Maximum ShakeMap instrumental intensity (Modified Mercalli, 0–12 scale). Null when USGS produced no ShakeMap for the event, and always null for EMSC, which publishes no such field."
    • changedOutput schema / properties / event / properties / significance / description
      Previous value: -"USGS significance score (0–2000+). Combines magnitude, felt reports, PAGER. USGS only."New value: +"USGS significance score (0–2000+). Combines magnitude, felt reports, PAGER. Null when USGS computed no score, and always null for EMSC, which publishes no such field."
    • addedOutput schema / properties / event / properties / source_catalog
      Added value: +{
      +  "description": "Upstream catalog this solution came from, e.g. \"EMSC-RTS\" (EMSC real-time seismicity, revised as analysis continues). Absent for USGS, which publishes no catalog identifier on event records.",
      +  "type": "string"
      +}
    • addedOutput schema / properties / event / properties / status / anyOf
      Added value: +[
      +  {
      +    "enum": [
      +      "automatic",
      +      "reviewed",
      +      "deleted"
      +    ],
      +    "type": "string"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / event / properties / status / description
      Previous value: -"Review status. Automatic detections may be revised."New value: +"Human-review state: \"automatic\" (posted by automatic processing, not yet verified by a person), \"reviewed\" (examined by an analyst), or \"deleted\". Null when the source publishes no review status — EMSC does not, so treat an EMSC solution as unverified and subject to revision rather than final."
    • removedOutput schema / properties / event / properties / status / enum
      Removed value: -[
      -  "automatic",
      -  "reviewed",
      -  "deleted"
      -]
    • removedOutput schema / properties / event / properties / status / type
      Removed value: -"string"
    • addedOutput schema / properties / event / properties / tsunami / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / event / properties / tsunami / description
      Previous value: -"1 if a tsunami warning was issued; 0 otherwise. USGS only; 0 for EMSC events."New value: +"USGS tsunami flag: 1 for large events in oceanic regions, 0 otherwise. It is not a warning — USGS states the flag does not indicate whether a tsunami did or will exist; check NOAA (tsunami.gov) for actual alert status. Null when the source publishes no such flag, as EMSC does not."
    • removedOutput schema / properties / event / properties / tsunami / type
      Removed value: -"number"
  6. Changed3 schema fields changed
    • addedOutput schema / properties / event / properties / magnitude / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / event / properties / magnitude / description
      Previous value: -"Preferred magnitude value."New value: +"Preferred magnitude value. Null when no magnitude was computed for the event (the title renders it as \"M ?\")."
    • removedOutput schema / properties / event / properties / magnitude / type
      Removed value: -"number"
  7. Changed3 schema fields changed
    • addedOutput schema / properties / event / properties / depth_km / anyOf
      Added value: +[
      +  {
      +    "type": "number"
      +  },
      +  {
      +    "type": "null"
      +  }
      +]
    • changedOutput schema / properties / event / properties / depth_km / description
      Previous value: -"Hypocenter depth in kilometers. Shallow (<70 km), intermediate (70–300 km), or deep (>300 km)."New value: +"Hypocenter depth in kilometers. Shallow (<70 km), intermediate (70–300 km), or deep (>300 km). Null for historical events where depth was not measured."
    • removedOutput schema / properties / event / properties / depth_km / type
      Removed value: -"number"
  8. First observed

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already declare read-only, idempotent, open-world, but the description adds substantial context beyond that: products are omitted when USGS produced none, a small automatic event typically has no detail at all while a large reviewed one has most of it, and the response is a superset of the search-result normalized event. That variability is exactly what an agent needs to avoid misreading an empty response.

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-loaded with the core action and purpose in the first clause, and the product enumeration, while long, each item earns its place by telling the agent which fields may be present. Slightly dense 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 output schema exists so return values needn't be fully explained, yet the description usefully characterizes which products appear and when they are absent. Combined with the ID provenance and USGS-only constraint, 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.

Parameters3/5

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

Schema coverage is 100% and the schema already documents the event_id format and its provenance, which the description largely repeats. Baseline 3 is appropriate; the description adds no syntax or validation detail beyond the schema.

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 specific verb and resource ('Fetch detail for a specific earthquake by USGS event ID') and immediately distinguishes it from search results by naming the single-event-only products it returns. The USGS-only scope further separates it from any EMSC-related sibling behavior.

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?

Tells the agent where to get the required ID (the 'id' field of earthquake_get_feed and earthquake_search results) and gives an explicit exclusion: EMSC events have no per-event detail endpoint. That is both when-to-use and when-not-to-use guidance.

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.