usgs-water-mcp-server

Water List Parameters

water_list_parameters

Read-onlyIdempotent

Look up USGS parameter codes — the 5-digit codes every other tool's parameterCd takes. With no query, lists a curated set of well-known codes with names, units, and thematic group, from a built-in table (no network call): 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), and others; filter it with group. For anything else — turbidity, nitrate, chlorophyll, suspended sediment, salinity — pass query to search the full USGS parameter-code catalog (~19,600 codes) by name and description, or pass a 5-digit code to look it up. A query returns at most 25 entries, matching curated codes first, with total counting every match.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`group`	No	Filter the curated list by thematic domain: "streamflow", "groundwater", "temperature", "meteorological", "water-quality", or "all" (default). Applies to the curated list only — leave it "all" when passing query.	all
`query`	No	Search the full USGS parameter-code catalog. Case-insensitive; every word must start a word in the parameter name or description (e.g. "turbidity", "nitrate filtered", "dissolved oxygen"). A bare 5-digit code (e.g. "63680") returns that code. Omit to list the curated codes.

Output Schema

TableJSON Schema

Name	Required	Description
`note`	No	Guidance when a query matched nothing or was truncated. Absent otherwise.
`error`	No	Present when the call failed. Absent on success.
`query`	No	The catalog query searched, trimmed. Absent when listing the curated codes.
`total`	No	Number of entries that matched, before the 25-entry cap.
`truncated`	No	True when a query matched more than 25 entries and only the first 25 are listed — add words to narrow it.
`parameters`	No	Matching parameter entries. Without query: the curated codes. With query: matching curated codes first (each once, as its curated entry), then catalog records whose name holds every query word, then those matched through the description, each by code — at most 25.

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedSep 25, 2026

changedInput schema / properties / group / description

Previous value: -"Filter by thematic domain: \"streamflow\", \"groundwater\", \"temperature\", \"meteorological\", \"water-quality\", or \"all\" (default) for the full catalog."New value: +"Filter the curated list by thematic domain: \"streamflow\", \"groundwater\", \"temperature\", \"meteorological\", \"water-quality\", or \"all\" (default). Applies to the curated list only — leave it \"all\" when passing query."

addedInput schema / properties / query

Added value: +{
+  "description": "Search the full USGS parameter-code catalog. Case-insensitive; every word must start a word in the parameter name or description (e.g. \"turbidity\", \"nitrate filtered\", \"dissolved oxygen\"). A bare 5-digit code (e.g. \"63680\") returns that code. Omit to list the curated codes.",
+  "maxLength": 200,
+  "type": "string"
+}

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "parameters",
-      "total"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "parameters",
+      "total",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode."New value: +"Machine-readable failure mode. Declared by this tool: `query_with_group`: query was combined with a group other than \"all\". group filters the curated list only; the USGS catalog carries no matching grouping. `upstream_error`: The USGS parameter-code catalog could not be read — the request failed, timed out, or returned something other than a catalog page. Other values are possible when a failure originates below the handler."

addedOutput schema / properties / error / properties / data / properties / reason / examples
```
Added value: +[
+  "query_with_group",
+  "upstream_error"
+]
```

addedOutput schema / properties / note

Added value: +{
+  "description": "Guidance when a query matched nothing or was truncated. Absent otherwise.",
+  "type": "string"
+}

changedOutput schema / properties / parameters / description

Previous value: -"Matching parameter records with code, name, unit, and group."New value: +"Matching parameter entries. Without query: the curated codes. With query: matching curated codes first (each once, as its curated entry), then catalog records whose name holds every query word, then those matched through the description, each by code — at most 25."

changedOutput schema / properties / parameters / items / description

Previous value: -"A USGS parameter code entry with name, unit, and domain group."New value: +"A USGS parameter code entry."

addedOutput schema / properties / parameters / items / properties / description

Added value: +{
+  "description": "USGS catalog description, naming the medium, fraction, and method (e.g. \"Turbidity, water, unfiltered, … formazin nephelometric units (FNU)\"). Present on usgs-catalog entries only.",
+  "type": "string"
+}

changedOutput schema / properties / parameters / items / properties / group / description

Previous value: -"Thematic domain grouping for filtering."New value: +"Thematic domain of a curated entry. Absent on usgs-catalog entries."

addedOutput schema / properties / parameters / items / properties / source

Added value: +{
+  "description": "\"curated\": one of the well-known codes this server lists by default. \"usgs-catalog\": a record from the full USGS parameter-code catalog.",
+  "enum": [
+    "curated",
+    "usgs-catalog"
+  ],
+  "type": "string"
+}

changedOutput schema / properties / parameters / items / properties / unit / description

Previous value: -"Unit of measure (e.g. \"ft³/s\", \"ft\", \"°C\")."New value: +"Unit of measure (e.g. \"ft³/s\", \"ft\", \"°C\", \"FNU\")."

changedOutput schema / properties / parameters / items / required

Previous value: -[
-  "code",
-  "name",
-  "unit",
-  "group"
-]New value: +[
+  "code",
+  "name",
+  "unit",
+  "source"
+]

addedOutput schema / properties / query

Added value: +{
+  "description": "The catalog query searched, trimmed. Absent when listing the curated codes.",
+  "type": "string"
+}

changedOutput schema / properties / total / description

Previous value: -"Number of parameters returned."New value: +"Number of entries that matched, before the 25-entry cap."

addedOutput schema / properties / total / maximum
```
Added value: +9007199254740991
```
addedOutput schema / properties / total / minimum
```
Added value: +-9007199254740991
```

changedOutput schema / properties / total / type

Previous value: -"number"New value: +"integer"

addedOutput schema / properties / truncated

Added value: +{
+  "description": "True when a query matched more than 25 entries and only the first 25 are listed — add words to narrow it.",
+  "type": "boolean"
+}

Changed6 schema fields changedAug 22, 2026

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": [
+      "parameters",
+      "total"
+    ]
+  },
+  {
+    "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.",
+          "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: -[
-  "parameters",
-  "total"
-]

First observedJun 7, 2026

TDQS

A4.6/5.0

Behavior4/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral detail beyond those: the curated list is served from a built-in table with no network call, the query searches a ~19,600-code catalog, and results are capped at 25 with curated matches ranked first and a total count of all matches. This gives the agent concrete expectations about performance and result shape. It doesn't cover error handling or authentication, but for a read-only lookup that is acceptable.

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?

The description is longer than average but information-dense and logically structured: purpose statement, no-query mode, query mode, code-lookup mode, and result-limit note. Every sentence earns its place; examples are illustrative rather than filler. It is not excessively verbose, though it could be tightened slightly without losing 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?

With an output schema present (per context signals), the description does not need to enumerate return fields. It fully covers all input scenarios (no query, query, bare code), explains the effect of group, and states the result cap and counting behavior. For a two-parameter, zero-required lookup tool, nothing an agent needs to call it correctly is missing.

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 description coverage is 100% and the schema itself is unusually thorough for both parameters. The description still adds value by giving concrete examples of curated codes (00060, 00065, 00010, 72019) and by clarifying that query can take a bare 5-digit code or a phrase, plus the 25-entry limit and ordering. These enrich the agent's understanding beyond the schema's already-detailed field descriptions, justifying a score above the baseline of 3.

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-resource pair ('Look up USGS parameter codes') and immediately frames its role as the source for the 5-digit parameterCd used by every other tool, distinguishing it from siblings that consume those codes. It goes on to enumerate three distinct modes (list curated, search catalog, direct code lookup), leaving no doubt 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?

Explicit usage conditions are given for each mode: 'With no query, lists a curated set... filter it with group'; 'For anything else... pass query to search'; 'or pass a 5-digit code to look it up.' It also tells the agent when to leave group at 'all' (in the schema) and sets expectations on result limits. This is unambiguous when-to-use guidance with no need to infer.

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

All usgs-water-mcp-server 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.