Skip to main content
Glama

earthquake-mcp-server

by io.github.cyanheads

Get USGS Earthquake Feed

earthquake_get_feed
Read-onlyIdempotent

Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window. These feeds are CDN-cached by USGS and faster and more available than the query API — use them for "what's happening now" queries. "all" includes microseisms (M<1); "significant" is a USGS curation based on magnitude, felt reports, and PAGER impact estimates. "hour" returns 0–10 events typically; "month" can exceed 10,000 for the "all" tier, so results are returned a page at a time: count is the page size, totalCount the whole feed, and nextCursor the input for the following page. The cursor is opaque and must be passed back verbatim — unlike earthquake_search, these feeds have no upstream paging parameter and USGS regenerates them about once a minute, so a numeric offset across two calls would skip or repeat events. For historical or filtered queries, use earthquake_search instead.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum events to return in this call. Default 100, max 1000. Applies to the first page; later pages carry the page size inside the cursor, so set it on the first call rather than changing it mid-sequence.
cursorNoOpaque token for the next page, taken verbatim from a previous call's nextCursor. Omit for the first page. Do not construct, parse, or edit it — it encodes a position in the feed snapshot and is rejected if malformed.
time_windowNoTime window for the feed. "hour" typically returns 0–10 events; "month" can exceed 10,000 for the "all" tier. Prefer "hour" or "day" for real-time status checks.day
magnitude_tierNoMinimum magnitude threshold for the feed. "all" includes microseisms (M<1). "1.0" is M1.0+. "2.5" is M2.5+. "4.5" is M4.5+. "significant" is a USGS curated selection based on magnitude, felt reports, and PAGER impact estimates — not purely magnitude-based.2.5

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
countNoNumber of events returned in this page, not the whole feed.
errorNoPresent when the call failed. Absent on success.
eventsNoEarthquake events for this page, newest first.
noticeNoRecovery guidance when the feed contains no events, or how to continue when a page was capped — narrowing the magnitude tier, widening the time window, paging with the cursor, or using earthquake_search for filtered queries. Absent when a single page covers the whole feed.
feed_urlNoSource feed URL.
truncatedNoTrue when the feed holds more events than this page returned. nextCursor carries the input for the following page.
nextCursorNoOpaque token to pass back as the cursor input for the next page. Present only when more events remain; absent means this was the last page.
totalCountNoNumber of events in the whole feed, across every page.
generated_atNoISO 8601 UTC timestamp when this feed was generated by USGS.

TDQS

A5/5.0
Behavior5/5

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

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses crucial runtime behavior: feeds are CDN-cached, regenerated about once a minute, results are paginated via opaque cursor, and attempting to use a numeric offset would skip/repeat events. This level of detail preempts common misuse and is far more than annotations provide. 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.

Conciseness5/5

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

The description is organized logically: purpose, then usage context, then paging details, then pointer to alternatives. Every sentence contributes new information; there is no filler. Despite its length, it feels tight because each clause carries operational value, and key constraints are front-loaded.

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 (pagination, cursor semantics, multiple enum-based parameters), the description covers all critical aspects an agent needs: how results are returned (count, totalCount, nextCursor), the fragility of cursor handling, and the distinction from search. The presence of an output schema further reduces the need to describe return structure, so nothing essential is missing.

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?

While the schema already describes 100% of parameters, the description adds substantial meaning: it explains typical event counts per time window, clarifies that 'significant' is curated rather than purely magnitude-based, and warns that the cursor must be passed back verbatim. These enrich the schema descriptions, making selection and invocation more reliable.

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 a precise action and resource: 'Fetch a USGS pre-computed real-time earthquake feed by magnitude tier and time window.' It also differentiates from sibling earthquake_search by stating its real-time feed nature and explicitly pointing to search for historical/filtered queries. This leaves no ambiguity about what the tool does.

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 explicitly states when to use: for 'what's happening now' queries, and when not to use: 'For historical or filtered queries, use earthquake_search instead.' It also advises preferring 'hour' or 'day' windows for real-time checks, giving practical selection guidance beyond raw parameter definitions.

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