Server Quality Checklist

Tool Scores

• fdsn_get_allmagnitudes_by_idA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so the description does not need to restate safety. It adds valuable behavioral context: the eventid is opaque and must be copied verbatim from a prior query, and datacenter options are enumerated. This goes beyond the annotations by explaining critical usage constraints.

  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 concise and well-structured: a purpose sentence, a usage condition, a critical warning, and datacenter note. Every sentence earns its place with no redundancy or fluff.

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

  Completeness4/5

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

  The description covers the tool's purpose, when to use it, the critical eventid constraint, and datacenter options. An output schema exists to handle return-value details. Minor gaps remain (e.g., error behavior, effect of datacenter on results), but the essential context is present.

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

  Parameters4/5

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

  The schema provides no descriptions (0% coverage), so the description must compensate. It explains the eventid is an opaque provider-specific string and must not be invented or reformatted, and it clarifies the datacenter parameter by listing default and available values. This adds non-obvious semantics beyond the plain 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?

  The description opens with a specific verb and resource: 'Get all computed magnitude solutions for an earthquake event.' It clearly distinguishes itself from sibling tools by focusing on magnitudes and listing relevant magnitude types (ML, Mw, Mb, Md).

  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?

  The description explicitly states when to use the tool: 'when asked about different magnitude types, magnitude comparisons across agencies, or station counts.' It provides clear context but does not enumerate alternatives or when-not-to-use conditions, which prevents a 5.

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

• fdsn_get_focalmechanism_by_idA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, covering safety and idempotency. The description adds valuable behavioral context by noting that moment tensor data is returned 'when available' and that the eventid is opaque and must not be invented or reformatted—this is crucial for correct use beyond what annotations convey.

  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 composed of four concise sentences, each adding unique value: purpose, return data, usage context, eventid caution, and datacenter options. There is no redundancy or filler, and the key information is front-loaded.

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

  Completeness4/5

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

  Given the tool's simplicity and the presence of annotations and output schema, the description covers the essential aspects: what it does, what it returns, prerequisites for eventid, and available datacenters. It doesn't detail error handling for invalid eventids, but that is a minor gap given the overall completeness.

  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?

  Schema description coverage is 0%, but the description compensates thoroughly. It explains that eventid is an opaque, provider-specific string that must be copied verbatim from a query result, which is essential guidance for the required parameter. It also lists valid datacenter options (INGV, EMSC, GFZ, USGS, etc.), giving meaningful semantics for the optional parameter.

  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 clearly states 'Get focal mechanism and moment tensor data for an earthquake event' and lists the specific outputs (nodal planes, principal axes, moment tensor components). This distinguishes it from sibling tools like fdsn_get_arrivals_by_id and fdsn_get_allmagnitudes_by_id, which cover other data types.

  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?

  The description says 'Use this for understanding the rupture geometry and seismic source characteristics,' providing clear when-to-use context. It also mandates that the eventid must be copied verbatim from a prior fdsn_query_earthquakes result, which establishes a prerequisite and prevents misuse. However, it doesn't explicitly name alternative tools for other use cases.

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

• fdsn_get_arrivals_by_idA
  4.6/5.0
  Behavior4/5

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

  Annotations already establish the tool as read-only, idempotent, and non-destructive. The description adds valuable behavioral context beyond that: the eventid is an opaque, provider-specific string that must not be invented or reformatted, and datacenter options (INGV, EMSC, GFZ, USGS, others). It also notes the output includes linked pick data, which is useful. This goes beyond the baseline, though it does not cover all edge cases like error handling.

  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 appropriately concise, front-loaded with the core purpose, then usage guidance, a key warning about eventid, and datacenter options. Each sentence earns its place without redundancy. The structure guides the agent from what to when to how, with no wasted content.

  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 simplicity (2 parameters, output schema available, annotations covering safety), the description is complete. It covers purpose, usage conditions, parameter semantics, and datacenter choices. The critical eventid provenance requirement is essential for correct invocation and is clearly stated. No significant gaps remain for an agent to select and use the tool correctly.

  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?

  With a schema description coverage of 0%, the description fully compensates by explaining both parameters. For eventid, it clarifies its opaque nature, provenance from fdsn_query_earthquakes, and the strict requirement to copy verbatim. For datacenter, it lists valid options and the default (INGV), providing crucial meaning that the bare schema lacks.

  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 clearly identifies the tool's function: 'Get all seismic phase arrivals for an earthquake event, including linked pick data (station, time, phase).' It specifies the resource (seismic phase arrivals) and the action (get), and explicitly distinguishes this from sibling tools by focusing on arrivals and phase data. The use case is further clarified with examples like 'recorded phases, station readings, or seismic wave arrivals.'

  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?

  The description states when to use the tool ('Use this when asked about recorded phases, station readings, or seismic wave arrivals') and provides a critical prerequisite: the eventid must be copied verbatim from a prior fdsn_query_earthquakes result. However, it does not explicitly mention when not to use it or contrast with sibling tools like fdsn_get_earthquake_by_id, so it misses the top score.

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

• fdsn_get_allorigins_by_idA
  4.8/5.0
  Behavior4/5

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

  Annotations already provide readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, read-only, idempotent operation. The description adds context beyond annotations by explaining that multiple origin solutions are returned and listing available datacenters. It also highlights the opaque nature of eventid, adding meaningful behavioral context. Not quite a 5 because it doesn't describe pagination or result format, but annotations cover the safety profile adequately.

  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 compact and front-loaded. It starts with the core purpose, then gives usage context, then the eventid constraint, and ends with datacenter options. Every sentence earns its place; there is no fluff or repetition. Length is appropriate for the complexity.

  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?

  The tool has an output schema (though not shown), so return format is presumably documented there. The description covers purpose, usage, critical input constraints, and available datacenter choices. Given the annotations and schema, it is complete enough for an agent to select and invoke the tool correctly. No major gaps.

  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?

  Schema description coverage is 0%, but the description fully compensates. For eventid, it explains that it is an opaque provider-specific string, must be copied verbatim from a previous query, and should never be invented or guessed. For datacenter, it lists concrete valid values (INGV default, EMSC, GFZ, USGS) and notes ObsPy support. This adds rich meaning beyond the bare schema types.

  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 clearly states the tool gets 'all computed origin solutions (hypocenter locations) for an earthquake event.' This is a specific verb+resource combination that distinguishes it from siblings like fdsn_get_earthquake_by_id, which likely retrieves a single event record. It directly addresses the domain of alternative locations and agency-computed origins.

  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?

  Explicit usage guidance is provided: 'Use this when asked about alternative locations, origin comparisons, or which agencies computed origins.' It also gives a critical operational constraint: eventid must be copied verbatim from a prior fdsn_query_earthquakes result and never guessed or reformatted. This is clear when-to-use and prerequisite handling.

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

• fdsn_query_earthquakesA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds non-redundant behavioral context: return format is 'compact tabular result (columns + rows)', depth is in kilometers, pagination via 'offset + returned_count', and that preferred origin/magnitude are used. 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.

  Conciseness4/5

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

  Descriptions is well-structured with a purpose sentence, return format note, common examples, and datacenter list. It is somewhat long but each section earns its place; no fluff. Could be slightly more compact, but the examples provide high value.

  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 has 19 parameters, 0% schema coverage, and an output schema, the description covers the essential operational aspects: return shape, unit convention, pagination, datacenter choice, and alternates. It addresses the main gaps an agent would encounter when selecting and invoking this tool.

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

  Parameters4/5

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

  Schema has 0% description coverage, so the description bears the burden. It provides illustrative parameter combinations (minmag/starttime, minlat/maxlat/minlon/maxlon, latitude/longitude/maxradiuskm, orderby/limit, offset), and clarifies units and pagination semantics. However, not every parameter is explained individually (e.g., endtime, updatedafter, minradiuskm), so it is strong but not exhaustive.

  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 explicitly states 'Query earthquake events from an FDSN datacenter with flexible parameters' – a specific verb and resource. It distinguishes from sibling by-id tools by mentioning 'For the full detail of a single event (all origins/magnitudes, arrivals, focal mechanism) use the by-id tools.'

  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?

  Provides multiple concrete usage examples (recent events, significant events, geographic area, radial search, pagination), explicitly says the by-id tools are for single-event details, and lists available datacenters. This gives clear when/what-to-use guidance.

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

• fdsn_get_earthquake_by_idA
  5/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds crucial behavioral context: the eventid is an opaque, provider-specific string that must exactly match a query result, and it lists available datacenters with a default and a non-exhaustive set supported by ObsPy. This enriches understanding without contradicting 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.

  Conciseness5/5

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

  The description is compact and front-loaded: first sentence states the primary purpose, next specifies the return payload, then provides usage restrictions, and finally datacenter options. Each of the four sentences adds distinct value with no wasted words.

  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 that an output schema exists and handles return-value details, the description covers all necessary context: purpose, input provenance rules, available datacenters, and alternative-tool routing. For the complexity of a simple lookup-by-ID tool, this description is sufficiently complete to guide correct invocation.

  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?

  With 0% schema description coverage, the description fully compensates. It defines the eventid's opaque, provider-specific nature and mandates copying it verbatim from a prior result, and it explains the datacenter parameter with named options and the default value. Both parameters receive meaningful elaboration beyond the bare 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?

  The description uses a specific verb and resource: 'Get basic information about a specific earthquake event by event ID', and lists the returned items (preferred origin, preferred magnitude, station magnitudes, amplitudes). It clearly distinguishes from sibling tools by directing users to 'specialized tools' for detailed data like all origins or arrivals.

  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 this tool (basic information) and when to avoid it (detailed data), naming the specialized alternatives. It also gives an essential prerequisite: the eventid 'MUST be copied verbatim from a prior fdsn_query_earthquakes result' and warns against inventing values. This is clear 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.