A
licenseA
qualityB
maintenanceEnables querying USGS water data including real-time and historical streamflow, gage height, and water temperature from USGS gauges across the United States.
3
MIT
usgs-water-mcp-server
Server Details
Query real-time and historical USGS water data from ~8,000 stream gages and groundwater wells.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/usgs-water-mcp-server
- GitHub Stars
- 1
- Server Listing
- @cyanheads/usgs-water-mcp-server
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
MCP client
Glama
MCP server
Full call logging
Every tool call is logged with complete inputs and outputs, so you can debug issues and audit what your agents are doing.
Tool access control
Enable or disable individual tools per connector, so you decide what your agents can and cannot do.
Managed credentials
Glama handles OAuth flows, token storage, and automatic rotation, so credentials never expire on your clients.
Usage analytics
See which tools your agents call, how often, and when, so you can understand usage patterns and catch anomalies.
100% free. Your data is private.
Tool Definition Quality
A4.5/5.0
Tool DescriptionsA
Average 4.7/5 across 7 of 7 tools scored.
Server CoherenceA
Disambiguation5/5
Each tool has a clearly distinct purpose: site discovery, parameter lookup, instantaneous readings, time series, conditions, and dataframe analysis. No overlapping functionality.
Naming Consistency4/5
All tools start with 'water_' and mostly follow a verb_noun pattern (e.g., water_find_sites, water_get_readings). The dataframe tools (water_dataframe_describe, water_dataframe_query) use a noun_verb structure, which is a minor deviation.
Tool Count5/5
7 tools is well-scoped for the domain, covering essential operations without excess or deficiency.
Completeness4/5
The set covers key workflows: site discovery, parameter lookup, data retrieval (instantaneous, series, conditions), and analysis. Missing a dedicated tool for detailed site metadata, but find_sites provides reasonable coverage.
Available Tools
7 toolswater_dataframe_describeWater Dataframe DescribeARead-onlyIdempotentInspect
List tables and columns staged on a DataCanvas by water_get_series or water_find_sites. Call this after water_get_series or water_find_sites returns a canvas_id to discover the exact table name and column types before writing a query. Then pass the table name to water_dataframe_query. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| canvas_id | Yes | Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas to describe. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| tables | Yes | Tables and views on this canvas. |
| canvas_id | Yes | The canvas ID that was described — pass to water_dataframe_query. |
Tool Definition Quality
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds useful context: returns error if DataCanvas is not available. No contradictions.
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?
Three sentences, front-loaded with purpose, no redundant information. Every sentence adds 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 output schema exists, annotations are present, and single parameter is fully described, the description is complete. It covers prerequisites, error condition, and next steps.
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% for the single parameter. Description does not add information beyond the schema description for canvas_id. Baseline of 3 is appropriate.
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?
Description clearly states 'List tables and columns staged on a DataCanvas' with specific verb and resource. Distinguishes from siblings by explaining it discovers table names and column types before querying.
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?
Explicitly specifies when to call (after water_get_series or water_find_sites returns canvas_id), and what to do next (pass table name to water_dataframe_query). Also mentions prerequisite: DataCanvas must be enabled.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_dataframe_queryWater Dataframe QueryARead-onlyIdempotentInspect
Run a read-only SQL SELECT against water data tables staged on a DataCanvas by water_get_series or water_find_sites. Workflow: run water_get_series or water_find_sites (get canvas_id + table_name) → water_dataframe_describe (confirm the table and its columns) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. At most 10,000 rows are returned; a query matching more is capped and the response sets truncated=true — scope with WHERE/LIMIT, and use SELECT COUNT(*) or water_dataframe_describe to learn the true match count. Requires DataCanvas to be enabled on this server instance. Returns an error if DataCanvas is not available.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | Read-only SELECT statement. Reference the table by the table_name from water_get_series or water_find_sites; columns vary by source table, so run water_dataframe_describe first for the exact schema. Example: SELECT date_time, value FROM water_series_01646500_00060 ORDER BY date_time DESC LIMIT 10 | |
| canvas_id | Yes | Canvas ID returned by water_get_series or water_find_sites. Identifies the canvas holding the data. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| rows | Yes | Result rows returned (up to 10,000). Column names match the SELECT clause. |
| row_count | Yes | Number of rows returned in the rows array (up to the 10,000-row cap), not the total matched by the query. When truncated is true the cap was reached, so row_count equals the returned count and undercounts the true total. To get the true match count run SELECT COUNT(*) with the same filter, or call water_dataframe_describe for the full row count of the staged table; page large results with LIMIT/OFFSET. |
| truncated | Yes | True when the query matched more rows than the 10,000-row cap and the result was capped — rows and row_count then cover only the first 10,000 matches, and the rest are not in this response. False means rows and row_count are the complete result for this query. When true, narrow the query with WHERE, page with LIMIT/OFFSET, or run SELECT COUNT(*) with the same filter for the true total. |
Tool Definition Quality
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds significant behavioral context: only SELECT statements, row cap behavior, error on missing DataCanvas, and the need for Describe first. No contradictions 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 appropriately sized, front-loads the core purpose, and every sentence conveys essential information (workflow, constraints, behavior). 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 the complexity (SQL query tool with dependencies and limitations), the description covers workflow, prerequisites, row cap behavior, error condition, and the need for DataCanvas. Output schema exists, so return values need no explanation. The description is fully adequate.
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 coverage is 100%, so baseline is 3. The description adds value by explaining the origin of canvas_id (from water_get_series/water_find_sites) and providing an example SQL statement with guidance on referencing table_name and columns. This exceeds the baseline.
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 it runs read-only SQL SELECT against water data tables. It distinguishes itself from siblings by referencing the workflow involving water_get_series, water_find_sites, and water_dataframe_describe, and by explicitly limiting to SELECT statements.
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 provides explicit guidance on when to use (after obtaining canvas_id and table_name, and after confirming with water_dataframe_describe), what is allowed (only SELECT), and what the limitations are (10,000 row cap with truncated flag). It also gives a workflow sequence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_find_sitesWater Find SitesARead-onlyIdempotentInspect
Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability. Returns site numbers, names, coordinates, types, altitude, and (in expanded mode) drainage area. Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number. Capped at 500 sites inline; when truncated=true, upstreamTotal holds the full count and, if DataCanvas is enabled, the complete match set stages to a canvas (canvas_id/table_name) for retrieval via water_dataframe_query — otherwise narrow the filters to get all matches.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| huc | No | Hydrologic Unit Code (HUC) scoping results to a watershed. Either a 2-digit major HUC (e.g. "02" for the Mid-Atlantic region) or an 8-digit minor HUC (e.g. "02070008" for the Middle Potomac). NWIS accepts no other lengths. | |
| bbox | No | Bounding box as "west,south,east,north" in decimal degrees (e.g. "-77.5,38.5,-76.5,39.5" for the DC metro area). Mutually exclusive with stateCd/countyCd/huc. | |
| stateCd | No | 2-character US state abbreviation (e.g. "VA", "WA"). Returns all sites in the state for the given filters. | |
| countyCd | No | FIPS county code(s) as bare 5-digit numbers — state and county digits concatenated, no separator (e.g. "51013" for Arlington, VA). Comma-separate up to 20 (e.g. "51059,51061"). Use with stateCd for clarity. | |
| siteType | No | Site type filter. Common codes: "ST" (stream), "GW" (groundwater well), "LK" (lake/reservoir), "SP" (spring), "AT" (atmosphere), "OC" (ocean), "ES" (estuary). Comma-separate multiple types (e.g. "ST,GW"). | |
| canvas_id | No | Canvas ID from a prior call to stage the full match set into an existing canvas rather than creating a new one. Applies only when the result is truncated and DataCanvas is enabled. Omit to start a fresh canvas. | |
| siteOutput | No | "basic" returns core identification fields. "expanded" adds drainage area, altitude, contributing area, and other metadata. | basic |
| parameterCd | No | 5-digit parameter code to require at each returned site (e.g. "00060" for discharge). Use water_list_parameters to discover codes. Comma-separate multiple codes with no spaces (e.g. "00060,00065"). | |
| hasDataTypeCd | No | Require sites with data of this type. Common values: "iv" (real-time/instantaneous), "dv" (daily values), "gw" (groundwater). Comma-separate multiple types. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| sites | Yes | Matching USGS monitoring sites (capped at 500 inline; when truncated, upstreamTotal holds the full count and canvas_id/table_name point to the staged full set when DataCanvas is enabled). |
| total | Yes | Number of sites returned inline in this response (at most 500). |
| notice | No | Advisory when results were capped — points to the staged canvas when DataCanvas is enabled, otherwise to narrowing filters, for retrieving all matches. |
| filters | Yes | Filters applied to this query. |
| canvas_id | No | Canvas ID for the DataCanvas holding the full, uncapped match set. Present only when truncated=true and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query to retrieve sites beyond the inline cap. |
| truncated | Yes | True when the upstream result set exceeded the 500-site cap. Query the full match set via water_dataframe_query when canvas_id is present, or narrow filters (add bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd) to retrieve all matches. |
| table_name | No | DuckDB table name in the canvas holding all matching sites. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL. |
| upstreamTotal | Yes | Total number of sites matching the query upstream, before the 500-site cap was applied. Equals total when truncated=false. |
Tool Definition Quality
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. The description adds behavioral details beyond annotations: cap at 500 sites, truncated behavior with upstreamTotal, DataCanvas staging, and expanded mode fields. 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?
The description is a single dense paragraph that front-loads the core purpose, then provides usage guidance, and ends with behavioral notes. It is information-rich but could be slightly more concise. The structure is logical.
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 presence of an output schema, the description does not need to detail return values. It covers all key aspects: purpose, filters, usage order, limits, truncated behavior, and DataCanvas integration. Complete for a complex tool with 9 parameters.
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 100%, and the description adds value by explaining mutual exclusivity (bbox vs. others), HUC pattern lengths, county code format, parameter code discovery via water_list_parameters, and siteOutput options.
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's purpose: 'Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code, filtered by site type and parameter availability.' It specifies the verb 'Find', the resource 'USGS water monitoring sites', and distinguishes from siblings by noting that other tools require a site number from this one.
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 guidance is given: 'Call this first — water_get_readings, water_get_series, and water_get_conditions all require a site number.' It also advises how to handle truncated results (narrow filters or use DataCanvas).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_get_conditionsWater Get ConditionsARead-onlyIdempotentInspect
Get a USGS site's current reading ranked against its full period-of-record daily-mean percentiles for the same calendar day — a "how unusual is this" percentileClass (record-high to record-low), not a flood-stage or drought determination (this tool fetches no authoritative thresholds). The reading is instantaneous but the percentiles are daily-mean, so the ranking is approximate (see historicalContext.comparisonBasis). When the record is too short to rank, returns the reading with historicalContext=null instead of an error. Use water_find_sites and water_list_parameters to resolve inputs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | USGS site number (8–15 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers. | |
| parameterCd | Yes | 5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). Use water_list_parameters to discover codes. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| note | No | Informational note explaining why historicalContext is null or incomplete. Absent when full historical context is available. |
| siteName | Yes | Human-readable USGS site name. |
| unitCode | Yes | Unit of measure for currentValue and the historical percentiles (e.g. "ft3/s", "ft"). |
| qualifiers | Yes | Data qualifier codes for the current reading. |
| siteNumber | Yes | USGS site number (8–15 digits, e.g. "01646500"). |
| parameterCd | Yes | 5-digit USGS parameter code that was queried (e.g. "00060"). |
| currentValue | Yes | Most recent observed value as a string. Empty string when no data is available for the current period. |
| parameterName | Yes | Human-readable parameter name with units (e.g. "Streamflow, ft³/s"). |
| currentDateTime | Yes | ISO 8601 date-time of the most recent observation. |
| historicalContext | Yes | Historical percentile context for the observation's calendar day. Non-null only when historicalContextStatus is "available"; see that field for why it is otherwise absent. |
| historicalContextStatus | Yes | Why historicalContext is or is not populated. 'available': percentiles for the observation's calendar day are present. 'no_matching_day': the stat table has rows but none for that calendar day. 'no_record': the stat table is empty — a new site, or a record too short to compute percentiles. 'unavailable': the statistics service call failed — a transient upstream error, not a statement about the site's record; retry shortly. |
Tool Definition Quality
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint. Description adds valuable behavioral details: the instantaneous vs daily-mean mismatch, the fallback to null historicalContext for short records (no error), and the comparisonBasis field. Discloses approximate nature, which is beyond what annotations provide.
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?
Three sentences, no wasted words. First sentence conveys main purpose and key concept. Second sentence handles edge case behavior. Third sentence gives input resolution advice. Well-front-loaded with the core action.
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?
Description covers edge case (short record), explains approximation, references output schema fields (historicalContext, comparisonBasis). With strong annotations and an output schema present, the description is largely complete. Minor gap: doesn't explicitly state the output is JSON, but that's implied.
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 already provides patterns and descriptions for both required parameters (site, parameterCd). Description adds practical guidance: discover valid values via water_find_sites and water_list_parameters, with example values. Since schema coverage is 100%, the description enhances without redundancy.
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?
Description uses specific verb 'get', identifies resource (USGS site current reading ranked against percentiles), explains the key percentileClass concept, and contrasts with flood-stage/drought determination. Distinguishes from sibling tools like water_get_readings (raw readings) and water_get_series (time series).
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?
Explicitly advises to use water_find_sites and water_list_parameters to resolve inputs. Clearly states what the tool does NOT do (authoritative thresholds) and explains limitations (approximate ranking). Provides context for when to use: to assess how unusual a reading is.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_get_readingsWater Get ReadingsARead-onlyIdempotentInspect
Get the latest instantaneous (~15-min, real-time) values for up to 100 USGS sites in one call — per-site, per-parameter records with timestamp, value, unit, and provisional/approved qualifiers. Each series returns only its 10 most recent records (totalValues reports the true count; truncated=true if any were capped); use water_get_series for a full date-range series. Sites NWIS returns nothing for are listed in missingSites, not dropped silently. Use water_find_sites first to discover site numbers and available parameters.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sites | Yes | One or more USGS site numbers to query. Maximum 100 per call. | |
| period | No | ISO 8601 duration for the lookback period (e.g. "PT2H" = last 2 hours, "P1D" = last 1 day, "P7D" = last 7 days). Default: "PT2H" (last 2 hours of readings). Widening it raises totalValues, but each series still returns only its 10 most recent records — use water_get_series to retrieve a full series. | PT2H |
| parameterCd | No | Parameter codes to return. Omit to get all parameters available at each site. Use water_list_parameters to discover codes. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Query parameters used for this request. |
| total | Yes | Total number of site+parameter time series returned. |
| readings | Yes | Time series per site+parameter combination. |
| truncated | Yes | True when at least one series held more than 10 records and was capped. Per-series counts are in readings[].totalValues; use water_get_series for the full series. |
| missingSites | Yes | Requested site numbers NWIS returned no series for — the site may not exist, or may not measure the requested parameter(s) in the requested period. Empty when every requested site returned data. Verify these with water_find_sites. |
Tool Definition Quality
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, openWorldHint, idempotentHint true. Description adds critical behavioral details: each series returns only 10 records, truncated flag, missingSites reporting, and totalValues count. These go beyond annotations and clarify the tool's limitations.
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 sentences pack all essential information without redundancy. Purpose is front-loaded, each sentence adds value, and structure is logical.
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 (3 parameters, 100 site limit, truncation, missing sites) and presence of output schema, the description covers all key behaviors. No gaps identified.
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 coverage is 100%, so baseline 3. Description enriches each parameter: 'sites' described as USGS site numbers; 'period' explains ISO 8601 format, default PT2H, and impact on totalValues vs returned records; 'parameterCd' mentions omission means all and references water_list_parameters. This adds significant practical meaning.
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 specifies 'Get the latest instantaneous (~15-min, real-time) values for up to 100 USGS sites in one call' with clear output details (timestamp, value, unit, qualifiers). It distinguishes from sibling tool water_get_series by noting that this tool returns only 10 most recent records per series.
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 explains when to use (latest readings for up to 100 sites) and when to use water_get_series (for full series). It also advises using water_find_sites first to discover site numbers and parameters. No explicit 'when not to use' but sufficient context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_get_seriesWater Get SeriesARead-onlyIdempotentInspect
Get a daily or instantaneous time series for one USGS site and parameter over a date range, as time-ordered value records. Large sets (>500 records) return the most recent 500 with truncated=true; with DataCanvas enabled they instead spill to a canvas (canvas_id/table_name) for SQL via water_dataframe_query. Use water_find_sites and water_list_parameters to resolve inputs.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | USGS site number (8–15 digits, e.g. "01646500" for Potomac River at Little Falls). Use water_find_sites to discover valid site numbers. | |
| endDate | Yes | End date in YYYY-MM-DD format (e.g. "2024-12-31"). | |
| canvas_id | No | Canvas ID from a prior water_get_series call to append data to an existing canvas rather than creating a new one. Omit to start a fresh canvas. | |
| startDate | Yes | Start date in YYYY-MM-DD format (e.g. "2024-01-01"). | |
| seriesType | No | "daily" returns one value per day (DV service, typically mean/max/min). "instantaneous" returns ~15-minute readings (IV service). Default: "daily". Use "instantaneous" for high-resolution analysis. | daily |
| parameterCd | Yes | A single 5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). One code per call — this tool returns one series. Use water_list_parameters to discover available codes. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| query | Yes | Query parameters used for this request. |
| notice | No | Advisory when the result was truncated — narrow the date range or enable DataCanvas for full access. |
| values | Yes | Time-ordered value records. Contains all records when not truncated, or the most recent 500 when truncated (no canvas) or a preview slice (with canvas). |
| siteName | Yes | Human-readable USGS site name. |
| unitCode | Yes | Unit of measure for all values in this series (e.g. "ft3/s", "ft"). |
| canvas_id | No | Canvas ID for the DataCanvas holding the full time series. Present only when truncated=true and DataCanvas is enabled. Pass to water_dataframe_describe then water_dataframe_query. |
| truncated | Yes | True when the result exceeds 500 records and was trimmed. Query the full series via water_dataframe_query when canvas_id is present, or narrow the date range. |
| seriesType | Yes | "daily" = one value per day (DV service); "instantaneous" = ~15-minute readings (IV service). |
| siteNumber | Yes | USGS site number (8–15 digits, e.g. "01646500"). |
| table_name | No | DuckDB table name in the canvas holding all records. Present when canvas_id is present. Use as the FROM target in water_dataframe_query SQL. |
| parameterCd | Yes | 5-digit USGS parameter code (e.g. "00060" for discharge). |
| totalRecords | Yes | Total number of records in the upstream result set (before any truncation). |
| parameterName | Yes | Human-readable parameter name with units (e.g. "Streamflow, ft³/s"). |
Tool Definition Quality
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. The description adds context about large set handling (truncation and DataCanvas integration) and the time-ordered nature of results, complementing annotations without contradiction.
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?
Three sentences front-loaded with purpose, followed by key behavioral note and cross-reference to companion tools. No extraneous text; every sentence adds value.
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 6 parameters with full schema coverage and an output schema, the description covers essential behavioral aspects (truncation, DataCanvas) and references to resolve inputs. It does not detail the output structure, but the output schema exists to fill that gap.
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?
Input schema covers 100% of parameters with clear descriptions. The description adds meaning by explaining the output format (time-ordered value records), the daily vs instantaneous distinction, and the canvas_id purpose, going beyond schema basics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets daily or instantaneous time series for one USGS site and parameter over a date range. It distinguishes from sibling tools by mentioning companion tools for resolving inputs, but does not explicitly contrast with other data retrieval tools like water_get_conditions or water_get_readings.
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?
Provides guidance on large result sets (truncation vs DataCanvas spill) and suggests using water_find_sites and water_list_parameters to resolve inputs. However, it does not include when to avoid this tool or alternative tools for other data types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
water_list_parametersWater List ParametersARead-onlyIdempotentInspect
List well-known USGS parameter codes with human-readable names, units, and thematic domain — a static, built-in catalog. Use this first to discover that 00060 = "Discharge" (ft³/s), 00065 = "Gage height" (ft), 00010 = "Temperature, water" (°C), 72019 = "Depth to water level" (ft), etc. Filter by group to narrow results.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| group | No | Filter by thematic domain: "streamflow", "groundwater", "temperature", "meteorological", "water-quality", or "all" (default) for the full catalog. | all |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| total | Yes | Number of parameters returned. |
| parameters | Yes | Matching parameter records with code, name, unit, and group. |
Tool Definition Quality
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint true, idempotentHint true, and openWorldHint false. Description reinforces with 'static, built-in catalog.' No contradictions; behaviors are fully transparent.
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?
Two sentences: first states core functionality, second provides examples and usage advice. No wasted words; front-loaded and efficient.
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 one optional parameter, full schema coverage, and an output schema, the description sufficiently explains what the tool does, how to use it, and what to expect. No gaps.
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 covers parameter 'group' with enums and description. Description adds context by showing example codes and stating 'Filter by group to narrow results,' offering value beyond the 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?
Title and description clearly state the tool lists well-known USGS parameter codes with human-readable names, units, and thematic domain. Examples provided. Distinct from sibling tools which handle data queries and site lookups.
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?
Explicitly says 'Use this first to discover' indicating it's a preparatory step. Advises filtering by group. Could be improved by stating when not to use it, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Claim this connector by publishing a /.well-known/glama.json file on your server's domain with the following structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"maintainers": [{ "email": "your-email@example.com" }]
}The email address must match the email associated with your Glama account. Once published, Glama will automatically detect and verify the file within a few minutes.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Related MCP Servers
- Alicense-qualityFmaintenanceWraps USGS NWIS REST services to query water data such as streamflow, groundwater levels, and water quality.3MIT
- Flicense-qualityDmaintenanceProvides access to real-time water data from the USGS Water Services API, allowing users to fetch instantaneous measurements like stream flow, gage height, temperature, and water quality parameters from thousands of monitoring stations across the US.3
- Alicense-qualityDmaintenanceProvides access to real-time and historical snow conditions, weather data, and snowpack analysis from over 800 SNOTEL stations across the western United States through the USDA Air and Water Database API.2MIT
Try in Browser
Your Connectors
Sign in to create a connector for this server.