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
Glama MCP Gateway
Connect through Glama MCP Gateway for full control over tool access and complete visibility into every call.
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.
Tool Definition Quality
Average 4.7/5 across 7 of 7 tools scored.
Each tool has a clearly distinct purpose: site discovery, parameter lookup, instantaneous readings, time series, conditions, and dataframe analysis. No overlapping functionality.
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.
7 tools is well-scoped for the domain, covering essential operations without excess or deficiency.
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, idempotentHint) cover safety and idempotence. Description adds value by noting the error case when DataCanvas is unavailable, and explaining it's a discovery step. Contradiction not present.
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 sentences, no redundant information. Purpose is stated first, followed by usage workflow and requirements. Every sentence earns its 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?
Given output schema exists, description covers purpose, workflow, prerequisites, error conditions. Sufficient for an agent to understand when and how to use this tool.
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% with a clear description for canvas_id. Description reinforces the parameter's origin ('returned by water_get_series') but does not add new constraints or format details beyond the schema.
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 clearly states the action: 'List tables and columns staged on a DataCanvas by water_get_series.' It uses specific verbs and resources, and distinguishes from sibling tools like water_dataframe_query.
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?
Explicitly provides sequencing: 'Call this after water_get_series returns a canvas_id... Then pass the table name to water_dataframe_query.' Also mentions prerequisite: 'Requires DataCanvas to be enabled on this server instance.'
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds important behavioral details: only SELECT statements are permitted, results are capped at 10,000 rows (with guidance to use WHERE/LIMIT), requires DataCanvas enabled, and returns an error if unavailable. This goes beyond annotations, though the exact behavior when the cap is exceeded (truncation vs. error) is slightly ambiguous.
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 five sentences, each conveying necessary information without redundancy. It is front-loaded with the core purpose, then workflow, constraints, requirements, and error condition. No filler.
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?
Given the tool's moderate complexity, two parameters, the existence of an output schema, and annotations, the description fully covers prerequisites (workflow, DataCanvas), constraints (read-only, row cap), and error scenarios. No gaps remain for an agent to use the tool correctly.
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 baseline is 3. The description adds significant value for the 'sql' parameter: lists available columns with types, and provides a complete example query. For 'canvas_id', it reinforces the schema description. This extra guidance enhances usability beyond the schema alone.
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 explicitly states the tool runs a read-only SQL SELECT on water time-series tables staged by water_get_series. It clearly identifies the verb (run, query), resource (SQL on tables), and read-only constraint, distinguishing it from sibling tools via the workflow.
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 provides a clear workflow: water_get_series → water_dataframe_describe → water_dataframe_query. It specifies that only SELECT statements are allowed, results are capped at 10,000 rows, and recommends using WHERE and LIMIT. It mentions the prerequisite of DataCanvas being enabled. However, it does not explicitly state when not to use this tool or list alternatives.
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses result cap at 500, truncated flag, upstreamTotal, and DataCanvas behavior. Consistent with readOnlyHint annotation; 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Information-dense paragraph that front-loads the core action. Slightly lengthy but every sentence adds value.
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?
Covers purpose, usage, behavior, and parameter guidance thoroughly. Output schema exists so return values need not be explained.
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?
Adds context beyond the schema, e.g., explaining the use of parameterCd and hasDataTypeCd filters, and listing returned fields like 'drainage area' in expanded mode.
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 starts with 'Find USGS water monitoring sites by bounding box, state, county, or HUC watershed code,' clearly stating the verb and resource. It distinguishes from siblings by noting that other tools require a site number from this call.
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?
Explicitly states to 'Call this first to discover site numbers' and names the tools that require the output. Provides guidance on narrowing queries without DataCanvas via filters.
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With annotations already indicating readOnlyHint, openWorldHint, and idempotentHint, the description adds crucial behavioral context: the reading is instantaneous while percentiles are daily-mean (with comparisonBasis documented), and the classification is a 'how unusual is this' ranking. It also discloses the null historicalContext response for insufficient record history rather than error. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded: first sentence states core purpose and what it returns. Subsequent sentences add precise details (percentile classification, approximation caveat, null behavior) and usage tips. Every sentence earns its place with no redundancy. The structure follows a logical flow from summary to specifics.
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?
Given the tool's complexity (historical context, percentile classification), the description covers the main output components, the statistical approximation, edge case handling (null historicalContext), and ties to sibling tools. An output schema exists but the description still adds essential interpretation context. No gaps for an agent to select or invoke this tool correctly.
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?
The input schema already has 100% coverage with good descriptions for both parameters (site and parameterCd). The tool description adds extra value by referencing discovery tools (water_find_sites, water_list_parameters) and giving example values like '01646500' and '00060'. This reinforces retrieval patterns beyond the schema's own documentation.
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 clearly states the tool gets current hydrologic conditions at a USGS site with historical context via percentile classification. It specifies the return contents (current reading, classification) and distinguishes from siblings like water_find_sites (discovery) and water_get_readings (raw data). The verb 'get' and resource 'hydrologic conditions' with qualifiers make the purpose precise.
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 explicitly tells when to use preceding discovery tools: 'Use water_find_sites to discover site numbers; use water_list_parameters to find parameter codes.' It also clarifies what the classification is NOT (flood-stage or drought determination) and mentions the null-case behavior when record history is insufficient. This provides clear when-to-use guidance.
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds critical behavioral details: each series returns only 10 most recent records, truncated flag indicates capping, totalValues reports original count, and missingSites lists sites with no data. 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is thorough but somewhat lengthy. However, every sentence adds value, and the core purpose is front-loaded. Could be slightly shortened, but still well-structured.
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?
Given the moderate complexity (3 parameters, output schema exists), the description is fully complete. It covers return fields, limits, edge cases (truncated, missingSites), and cross-references other tools. Output schema exists but description still provides essential context.
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 has 100% description coverage. Description adds further clarity: explains that period widening increases totalValues but each series still capped at 10 records; mentions water_list_parameters for parameter codes; clarifies sites max is 100 and pattern.
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?
Description clearly states the tool gets latest instantaneous values for USGS sites, with real-time updates. It distinguishes from sibling water_get_series by specifying that water_get_readings is for latest values and water_get_series for date-range queries.
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?
Explicitly says when to use (get latest values) and when not (for date-range use water_get_series). Also advises to use water_find_sites first to discover sites and parameters, providing clear guidance on alternative tools.
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.
| 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
| 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
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses returns (siteNumber, parameterCd, time-ordered records) and DataCanvas spillover behavior (truncation at 500 records, canvas_id/table_name). Annotations provide readOnlyHint, openWorldHint, idempotentHint, and description adds significant behavioral context 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences front-loaded with main purpose, then details on behavior and cross-references. No wasted words; every sentence provides information.
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?
Given 6 parameters, output schema exists, and tool complexity, the description covers all semantics, behavior (DataCanvas, truncation), and sibling references. No gaps.
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%, but description adds value: explains seriesType options ('daily' vs 'instantaneous'), canvas_id usage for appending, and references for site and parameterCd. Provides meaning beyond schema.
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?
Description clearly states it gets time series data for a USGS site and parameter over a date range, with specific mention of daily or instantaneous values. It distinguishes from siblings by referencing water_find_sites and water_list_parameters, and details the DataCanvas behavior.
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?
Explicit guidance to use water_find_sites for site numbers and water_list_parameters for parameter codes. Also notes behavior for large result sets with and without DataCanvas. Does not explicitly state when not to use, but provides clear context.
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.
| 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
| Name | Required | Description |
|---|---|---|
| total | Yes | Number of parameters returned. |
| parameters | Yes | Matching parameter records with code, name, unit, and group. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by stating 'no network call' and 'static lookup', providing performance and behavior details 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 description is two sentences long, front-loaded with the core purpose ('Static lookup'), and includes illustrative examples and the filter option without any extraneous text.
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 simple static lookup tool with one optional parameter and an output schema, the description covers usage context, behavior, and examples completely. No gaps are apparent.
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%, with the only parameter 'group' fully described. The description merely restates 'Filter by group' without adding new semantic meaning, so baseline 3 is appropriate.
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 clearly states it is a static lookup of USGS parameter codes with names, units, and thematic domain. It provides concrete examples (e.g., 00060 = Discharge) and distinguishes itself from sibling data retrieval tools by emphasizing 'no network call' and 'use this first'.
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 explicitly advises 'Use this first' to discover parameter codes, providing clear context for when to use it. However, it does not specify when not to use it or alternative tools, but sibling names imply they are for data retrieval.
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!