QuakeIndex

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

Annotations already declare read-only, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real value beyond that: results include every observed revision, carry their data source and last-confirmed timestamp, link to both QuakeIndex and USGS event pages, and flag automatic solutions as first estimates. It stops short of stating behavior for an unknown/retired event id.

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

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

Front-loaded with the core capability and the identifier form in the first clause, then the revision behavior. The final sentence about predictions/warnings is slightly tangential to retrieval but earns its place by preventing misuse of the tool as an alerting endpoint.

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

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

With no output schema, the description carries the burden of describing returns and does so well (source, last-confirmed time, page links, revision history). The only gap is error behavior for an invalid or unknown event id, which an agent would want before invoking.

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

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

Schema description coverage is 100%, and the schema already documents that id accepts a USGS event id (e.g. 'ci41234567') or an event page URL. The description repeats the same fact without adding format constraints, normalization rules, or fallback behavior, so the baseline 3 applies.

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

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

States a specific resource (one earthquake, keyed by USGS event id or event URL) and a concrete scope: all held data including every observed revision. Sibling differentiation is implicit rather than stated — nothing names earthquakes_near, latest_earthquakes, or place_activity — but an agent can infer this is the single-event-by-id lookup versus the list/search siblings.

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

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

Usage is implied by the required id ('by USGS event id or URL'), so an agent knows it needs an identifier in hand. The closing sentence usefully sets expectations about what this tool will NOT return (no predictions, no warnings; ShakeAlert/MyShake are the warning sources), but there is no explicit when-to-use/when-not or named alternative for the no-id case.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety bar is low; the description still adds real value by naming the data provenance (USGS via QuakeIndex), the presence of per-result source and last-confirmed timestamps, event links, and the newest-first ordering. The one gap is that it does not disclose default behavior when no location input is supplied, despite zero required parameters.

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

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

Three front-loaded sentences with the spatial and temporal scope stated first and no filler. The closing ShakeAlert/MyShake sentence is the weakest — it reads as a disclaimer rather than invocation guidance — but it does carry the meaningful 'no warnings' constraint.

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

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

For a 9-parameter tool with no required inputs and no output schema, the description covers location selection and return contents adequately. It leaves open what happens with an empty call, how limit interacts with the 'largest in window' item, and how min_magnitude affects results — gaps an agent would have to guess at.

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

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

With only 44% schema description coverage, the description must compensate, and it does explain the critical location-mode semantics (coordinates vs. ZIP vs. city). But it adds nothing about limit (default 20, max 50), min_magnitude, state, or the days default, all of which the schema documents thinly or not at all.

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

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

The first sentence states a specific resource (earthquakes), a spatial filter (radius around coordinates, ZIP, or town), a temporal window (1-365 days), and the sort order plus returned content (distance, largest in window). This clearly separates it from latest_earthquakes and largest_on_record, though it never names a sibling explicitly.

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

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

The 'no predictions and no warnings' line functions as an implicit exclusion, steering the agent away from expecting alerting behavior. However, there is no explicit when-to-use vs. place_activity or latest_earthquakes guidance, and no statement about which of the three location input modes to prefer.

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

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

Annotations already establish read-only, idempotent, non-open-world behavior, so the description focuses on added context: the data provenance (USGS as held by QuakeIndex), the catalogue-span concept, and per-result fields (source, last-confirmed date, links). It also explicitly disclaims predictions/warnings and redirects EEW to ShakeAlert/MyShake, which is useful scoping beyond the annotations.

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

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

The lead sentence is well front-loaded with the key scope, but the trailing sentences mix valuable return-field detail with a somewhat tangential disclaimer about ShakeAlert/MyShake as early-warning sources, which costs space without helping tool selection.

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

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

With no output schema, the description does the work of describing returned fields (source, last-confirmed, links), and it defines the catalogue-span notion that distinguishes this from recency-based siblings. The main gap is radius_km behavior for town/ZIP queries, left entirely to the schema.

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

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

Schema coverage is 75%, so the schema carries most of the load. The description adds value by enumerating place formats with concrete examples ('Kern County, CA', 'Ridgecrest, CA', ZIP), but says nothing about limit, state disambiguation, or the radius_km constraint for towns/ZIPs.

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

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

The description states a specific resource and scope: the largest earthquakes in QuakeIndex's USGS catalogue, resolved by state/county/town/ZIP, over the full catalogue span. 'On record' plus the catalogue-span framing implicitly separates it from latest_earquakes and earthquakes_near, though no sibling is named explicitly.

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

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

Usage context is implied rather than stated: it is clearly a place-scoped historical-ranking tool, and the accepted place formats are given. There is no explicit when-to-use-this-vs-X guidance against earthquake_details, place_activity, or latest_earquakes, and no exclusion conditions beyond 'no predictions/warnings'.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world; the description adds meaningful extra context beyond that — the data is USGS as indexed by QuakeIndex (consistent with openWorldHint=false), each result carries a freshness timestamp and source links, and it explicitly disclaims predictions/warnings while naming ShakeAlert and MyShake as warning sources. Minor gap: no mention of the 50-result cap or empty-result behavior.

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

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

Front-loaded with the core operation and filters in the first clause, followed by the use-case trigger and return-value summary. The final sentence on early-warning sources is useful but slightly tangential to invoking the tool.

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

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

With no output schema, the description does the right work by summarizing what each result contains (source, last-confirmed time, links). For a simple 4-param read tool with no required parameters, this is nearly complete; only the limit cap and behavior on zero matches are unaddressed.

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

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

Schema coverage is only 25% (only 'hours' documented), so the description must partially compensate. It does clarify the hours window ('up to 7 days') and the min-magnitude and US-only filters, but says nothing about 'limit' (that results are capped at 50) or how defaults behave, leaving a real coverage gap.

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

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

States a specific verb and resource ('most recent earthquakes recorded by USGS'), plus scope: worldwide vs US, newest-first ordering, and magnitude/time filters. This implicitly distinguishes it from largest_on_record (historically largest) and earthquakes_near (proximity-based), though no sibling is named explicitly.

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

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

Gives a concrete trigger phrase ('any earthquakes today?') that maps cleanly to the tool's purpose, and the 'newest first / hours back' framing clarifies when recency rather than proximity or magnitude records is wanted. It stops short of explicitly naming when to prefer a sibling instead.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds genuine behavioral value: 'a missing score is never zero', the observed-not-forecast framing, and that each result carries its source and last-confirmed timestamp — all information the annotations cannot convey.

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

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

The core definition and ranking mechanic are front-loaded in the first sentence, and each subsequent sentence covers a distinct concern (disclaimer, missing-data rule, provenance, no-warning routing). It is slightly dense, but no sentence is redundant.

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

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

With no output schema, the description usefully lists what a result contains (score, label, band, source, last-confirmed time, links) and disclaims forecasting. The main omission is guidance on choosing between the place, state, and county parameters.

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

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

Schema coverage is 100%, so each of place/state/county is already documented with examples. The description adds nothing about how the three alternate addressing modes interact (precedence of free-text place vs. state+county), leaving a real semantic gap, but the baseline for full coverage is 3.

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

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

The description names a specific verb-and-resource: fetches the QuakeIndex 0-100 activity score for a US state or county, including its label and normal band. That is clearly distinct from sibling tools like earthquake_details or latest_earthquakes, though it never names those siblings to make the contrast explicit.

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

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

Usage is implied by the framing question 'is this normal for here?' and the explicit disclaimer that it is not a forecast or risk rating, which helps the agent avoid misusing it. However, there is no explicit statement of when to pick this over earthquakes_near or was_that_an_earthquake, and no exclusions or alternatives are named.

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

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

Beyond the annotations, the description explains the intensity threshold, the Atkinson & Wald basis, the meaning of 'not_yet_reported', the handling of smaller nearby quakes, source provenance, last-confirmed timing, and links to USGS Did You Feel It? and event pages. It also explicitly disclaims predictions and warnings and names ShakeAlert and MyShake as warning sources.

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

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

The description is front-loaded with the core purpose and answer states, then adds useful caveats and provenance. It is somewhat long and includes some repeated provenance/link information, but most sentences earn their place.

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

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

With no output schema, the description carries the burden of explaining return states and does so thoroughly: yes, not_yet_reported, no, too-small nearby events, source metadata, and safety disclaimers. For a seven-parameter read-only query tool, this is sufficiently complete.

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

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

Schema description coverage is 71%, so most parameters are already documented in the input schema. The description adds context about 'a few minutes ago' and location-based intensity, but it does not add parameter-specific syntax or usage details beyond what the schema provides.

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

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

The description states a specific function: checking whether USGS has recorded an earthquake that could have caused recently felt shaking at a location. It clearly distinguishes this from sibling tools by framing the tool as a personal 'did I feel it?' check rather than a general earthquake search or detail lookup.

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

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

The description gives a clear usage context: someone who felt shaking a few minutes ago and wants to know if an earthquake explains it. It does not explicitly name alternative sibling tools or say when not to use this one, but the intended scenario is unambiguous.

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