Usgs Earthquakes

Search Earthquakes

search_earthquakes

Read-onlyIdempotent

Search the USGS earthquake catalog (FDSNWS event API) for real-time and historical seismic events. Filter by time window, magnitude, depth, and a circular geographic area. For "last N days/hours" questions pass days/hours rather than computing start_time yourself. Returns a compact list of quakes with magnitude, location, time, coordinates, depth, and significance, plus the exact start_time/end_time and magnitude filter actually queried. Keyless.

Input Schema

Name	Required	Description
`days`	No	Trailing window length in days, measured back from the exact current time (e.g. days: 7 for "the last 7 days"). Use this instead of computing a start_time for relative-window questions — it is the only way to get an EXACT trailing window rather than a date-boundary approximation. Ignored if start_time or end_time is given. If `hours` is also given, `hours` wins.
`hours`	No	Trailing window length in hours, measured back from the exact current time (e.g. hours: 168 for "the past 168 hours"). Same precedence as `days` (ignored if start_time/end_time given); takes priority over `days` if both are given.
`limit`	No	Max events to return (default 20, max 100).
`end_time`	No	ISO date/time upper bound, e.g. "2026-06-09". A bare date is treated as 00:00:00 UTC that day. Defaults to now.
`latitude`	No	Center latitude for a circular search (use with longitude + max_radius_km).
`order_by`	No	Sort order: "time" (newest first, default), "magnitude" (largest first), "time-asc", or "magnitude-asc".
`longitude`	No	Center longitude for a circular search (use with latitude + max_radius_km).
`start_time`	No	ISO date/time lower bound, e.g. "2026-06-01" or "2026-06-01T00:00:00". A bare date (no time) is treated as 00:00:00 UTC that day. If given, this (with end_time) takes precedence over `days`/`hours`, which are then ignored. For "in the last N days" questions, prefer `days` instead of computing this yourself — a model-guessed start_time is a common source of silently-wrong counts. Defaults to 30 days before now if start_time, days, and hours are all omitted.
`max_depth_km`	No	Maximum hypocenter depth in km.
`min_depth_km`	No	Minimum hypocenter depth in km.
`max_magnitude`	No	Maximum magnitude.
`max_radius_km`	No	Search radius in km around latitude/longitude.
`min_magnitude`	No	Minimum magnitude (e.g. 5 for M5+).

Output Schema

Name	Required	Description	Default
`count`	No	Total number of earthquakes matching criteria
`earthquakes`	No	List of earthquakes matching search criteria

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedOct 24, 2026

changedInput schema / examples

Previous value: -[
-  {},
-  {
-    "latitude": 35.68,
-    "longitude": 139.69
-  }
-]New value: +[
+  {},
+  {
+    "days": 30,
+    "limit": 5,
+    "min_magnitude": 6
+  },
+  {
+    "latitude": 35.68,
+    "longitude": 139.69
+  }
+]

addedInput schema / properties / days

Added value: +{
+  "description": "Trailing window length in days, measured back from the exact current time (e.g. days: 7 for \"the last 7 days\"). Use this instead of computing a start_time for relative-window questions — it is the only way to get an EXACT trailing window rather than a date-boundary approximation. Ignored if start_time or end_time is given. If `hours` is also given, `hours` wins.",
+  "type": "number"
+}

changedInput schema / properties / end_time / description

Previous value: -"ISO date/time upper bound, e.g. \"2026-06-09\". Defaults to now."New value: +"ISO date/time upper bound, e.g. \"2026-06-09\". A bare date is treated as 00:00:00 UTC that day. Defaults to now."

addedInput schema / properties / hours

Added value: +{
+  "description": "Trailing window length in hours, measured back from the exact current time (e.g. hours: 168 for \"the past 168 hours\"). Same precedence as `days` (ignored if start_time/end_time given); takes priority over `days` if both are given.",
+  "type": "number"
+}

changedInput schema / properties / start_time / description

Previous value: -"ISO date/time lower bound, e.g. \"2026-06-01\" or \"2026-06-01T00:00:00\". Defaults to 30 days ago."New value: +"ISO date/time lower bound, e.g. \"2026-06-01\" or \"2026-06-01T00:00:00\". A bare date (no time) is treated as 00:00:00 UTC that day. If given, this (with end_time) takes precedence over `days`/`hours`, which are then ignored. For \"in the last N days\" questions, prefer `days` instead of computing this yourself — a model-guessed start_time is a common source of silently-wrong counts. Defaults to 30 days before now if start_time, days, and hours are all omitted."

Changed8 schema fields changedJul 29, 2026

removedOutput schema / properties / earthquakes / items / properties / alert

Removed value: -{
-  "description": "Alert level if applicable",
-  "type": [
-    "string",
-    "null"
-  ]
-}

addedOutput schema / properties / earthquakes / items / properties / felt_reports
```
Added value: +{
+  "type": [
+    "null",
+    "number"
+  ]
+}
```
addedOutput schema / properties / earthquakes / items / properties / magType
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / earthquakes / items / properties / tsunami

Removed value: -{
-  "description": "Tsunami warning flag",
-  "type": "boolean"
-}

addedOutput schema / properties / earthquakes / items / properties / tsunami_flag
```
Added value: +{
+  "type": "boolean"
+}
```
addedOutput schema / properties / earthquakes / items / properties / url
```
Added value: +{
+  "type": "string"
+}
```

removedOutput schema / properties / earthquakes / items / required

Removed value: -[
-  "id",
-  "magnitude",
-  "place",
-  "time",
-  "latitude",
-  "longitude",
-  "depth_km",
-  "type",
-  "tsunami",
-  "significance"
-]

removedOutput schema / required

Removed value: -[
-  "count",
-  "earthquakes"
-]

Changed1 schema field changedJul 29, 2026

changedInput schema / examples

Previous value: -[
-  {
-    "endtime": "2024-01-31",
-    "minmagnitude": 5,
-    "starttime": "2024-01-01"
-  },
-  {
-    "endtime": "2024-12-31",
-    "latitude": 35.68,
-    "longitude": 139.69,
-    "maxradius": 5,
-    "minmagnitude": 3,
-    "starttime": "2024-01-01"
-  }
-]New value: +[
+  {},
+  {
+    "latitude": 35.68,
+    "longitude": 139.69
+  }
+]

Changed2 schema fields changedJun 20, 2026

addedInput schema / examples

Added value: +[
+  {
+    "endtime": "2024-01-31",
+    "minmagnitude": 5,
+    "starttime": "2024-01-01"
+  },
+  {
+    "endtime": "2024-12-31",
+    "latitude": 35.68,
+    "longitude": 139.69,
+    "maxradius": 5,
+    "minmagnitude": 3,
+    "starttime": "2024-01-01"
+  }
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "count": {
+      "description": "Total number of earthquakes matching criteria",
+      "type": "number"
+    },
+    "earthquakes": {
+      "description": "List of earthquakes matching search criteria",
+      "items": {
+        "properties": {
+          "alert": {
+            "description": "Alert level if applicable",
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "depth_km": {
+            "description": "Depth below surface in kilometers",
+            "type": "number"
+          },
+          "id": {
+            "description": "USGS event ID",
+            "type": "string"
+          },
+          "latitude": {
+            "description": "Epicenter latitude",
+            "type": "number"
+          },
+          "longitude": {
+            "description": "Epicenter longitude",
+            "type": "number"
+          },
+          "magnitude": {
+            "description": "Earthquake magnitude",
+            "type": "number"
+          },
+          "place": {
+            "description": "Location description",
+            "type": "string"
+          },
+          "significance": {
+            "description": "Event significance score",
+            "type": "number"
+          },
+          "time": {
+            "description": "Event time in ISO 8601 format",
+            "type": "string"
+          },
+          "tsunami": {
+            "description": "Tsunami warning flag",
+            "type": "boolean"
+          },
+          "type": {
+            "description": "Event type (e.g., earthquake)",
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "magnitude",
+          "place",
+          "time",
+          "latitude",
+          "longitude",
+          "depth_km",
+          "type",
+          "tsunami",
+          "significance"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "count",
+    "earthquakes"
+  ],
+  "type": "object"
+}

First observedJun 10, 2026

TDQS

A4.3/5.0

Behavior4/5

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

Annotations already declare the full safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description adds genuine context beyond them: keyless access (no auth), a compact return payload, and the fact that the actual start_time/end_time and magnitude filter are echoed back, which helps the agent verify silent filter errors.

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?

Four tight sentences: purpose, filter dimensions, a key usage heuristic, and what comes back. The critical 'use days/hours instead of computing start_time' guidance is front-loaded and nothing is wasted.

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?

With 13 optional params, an output schema, and rich annotations, the description covers purpose, usage, data source, keyless access, and result shape — more than enough for correct invocation. Nothing an agent needs 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 description coverage is 100%, so the schema already carries precedence and default behavior; the description's parameter mentions (time window, magnitude, depth, circular area) mostly restate it. Baseline 3 is appropriate given the schema does the heavy lifting with no added syntax or enum detail beyond it.

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 ('Search the USGS earthquake catalog (FDSNWS event API)') plus the filterable dimensions (time, magnitude, depth, circular area) and whether the data is real-time or historical. An agent can distinguish it from count_earthquakes and get_earthquake without opening either schema.

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

Usage Guidelines4/5

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

Gives actionable when-to-use guidance: prefer `days`/`hours` for relative-window questions rather than computing start_time, and use lat/lon plus max_radius_km for circular searches. It does not explicitly name sibling tools (count_earthquakes, get_earthquake) as alternatives, so it stops just short of the routing clarity a 5 requires.

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

All Usgs Earthquakes tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.