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
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.6/5 across 7 of 7 tools scored.
Each tool targets a distinct aspect of USGS water data: site discovery, parameter lookup, current conditions, real-time readings, time series, and DataCanvas-based analysis. No two tools overlap in purpose.
All tool names follow the pattern water_<verb>_<noun>, using snake_case consistently. Verbs are descriptive (find, get, list) and the naming clearly indicates each tool's function.
Seven tools cover the core workflows for accessing USGS water data without being excessive. The count is well-scoped for the domain.
The tool set covers the full lifecycle: site discovery, parameter lookup, current conditions, real-time readings, time series retrieval, and large dataset analysis via DataCanvas. No obvious gaps for typical use cases.
Available Tools
7 toolswater_dataframe_describeWater Dataframe DescribeARead-onlyIdempotentInspect
List tables and columns staged on a DataCanvas by water_get_series. Call this after water_get_series 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. 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 time-series tables staged on a DataCanvas by water_get_series. Workflow: water_get_series (get canvas_id + table_name) → water_dataframe_describe (confirm schema) → water_dataframe_query (SQL analysis). Only SELECT statements are permitted. Results are capped at 10,000 rows; use WHERE and LIMIT clauses to stay within budget. 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 tables by the names returned in water_get_series table_name. Columns available: date_time (VARCHAR), value (VARCHAR), qualifiers (VARCHAR), site_number (VARCHAR), parameter_cd (VARCHAR), unit_code (VARCHAR). 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. 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 | Total rows matched by the query before the 10,000-row cap. When row_count > rows.length, add WHERE or LIMIT clauses to retrieve specific subsets. |
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. Filter by site type (stream gage, groundwater well, lake) and parameter availability. Returns site numbers, names, coordinates, types, and (in expanded mode) drainage area and altitude. Call this first to discover site numbers — water_get_readings, water_get_series, and water_get_conditions all require a site number. To check which parameters or data types a site carries, use the parameterCd or hasDataTypeCd filters. Results are capped at 500 sites; when truncated=true the full upstream count is in upstreamTotal — narrow the query with bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd to get all matches.
| Name | Required | Description | Default |
|---|---|---|---|
| huc | No | Hydrologic Unit Code (HUC) — 2, 4, 6, or 8 digits (e.g. "02070010" for Potomac/Shenandoah). Scopes results to a watershed. | |
| 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 "SS:CCC" or comma-separated list (e.g. "51:013" for Arlington, VA). 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"). | |
| 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. | |
| 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; see truncated/upstreamTotal for overflow). |
| total | Yes | Number of sites returned in this response (at most 500). |
| notice | No | Advisory when results were capped — add narrowing filters to retrieve all matches. |
| filters | Yes | Filters applied to this query. |
| truncated | Yes | True when the upstream result set exceeded the 500-site cap. Narrow filters (add bbox, countyCd, huc, siteType, parameterCd, or hasDataTypeCd) to retrieve all matches. |
| 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?
Annotations already indicate read-only, open-world, and idempotent behavior. The description adds important behavioral details: results capped at 500 sites, the truncated/upstreamTotal mechanism, and the difference between basic and expanded output. 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 concise (about 4 sentences) and front-loaded with the primary function and usage instructions. Every sentence provides necessary information without redundancy.
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 (8 parameters, output schema, annotations), the description fully covers how to use the tool, its limitations (500-site cap), and how it fits into the tool ecosystem. No gaps identified.
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?
All 8 parameters have descriptions in the schema (100% coverage). The tool description adds extra context, such as example HUC codes, bounding box format, common siteType values, and how to use parameterCd with water_list_parameters. This goes beyond the schema descriptions.
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's purpose: finding USGS water monitoring sites by various criteria. It explicitly distinguishes this tool from sibling tools by noting that it should be called first to discover site numbers needed by other tools.
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 explicit guidance on when to use this tool ('Call this first'), how to narrow queries when results are capped, and how to use filters like parameterCd and hasDataTypeCd. It also mentions sibling tools that require its output.
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 current hydrologic conditions at a USGS site, placed in historical context. Returns today's current reading alongside a percentile classification (record-high, above-normal, normal, below-normal, low, record-low) derived from the full period-of-record daily statistics. Answers "is this flooding or drought?" — not just a raw number. Use water_find_sites to discover site numbers; use water_list_parameters to find parameter codes. When the site has insufficient record history, returns the current reading with historicalContext=null rather than an error.
| 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. Null when the stat service has no data for this site. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds a key behavioral detail: when historical record is insufficient, it returns historicalContext=null instead of an error. This goes beyond annotation data.
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 three sentences, each adding distinct value: purpose, output interpretation, and edge-case handling. No redundant or extraneous content.
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 presence of complete annotations, full schema coverage, and an output schema, the description adequately covers purpose, usage context, edge cases (insufficient history), and prerequisite tools. It is fully informative for an agent.
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 descriptions for both parameters. The description does not add new semantic information about the parameters beyond reinforcing the use of prerequisite tools for discovery, providing no additional meaning 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 defines the tool as retrieving current hydrologic conditions with historical context, emphasizing percentile classification to answer 'is this flooding or drought?'. It distinguishes itself from siblings like water_get_readings by highlighting the added interpretive value.
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 specifies when to use this tool (to assess flooding or drought) and mentions prerequisite tools (water_find_sites, water_list_parameters) for discovering inputs. It does not explicitly contrast with siblings like water_get_readings but implies its purpose through the 'not just a raw number' phrasing.
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 values (~15 min real-time updates) for one or more USGS monitoring sites. Returns per-site, per-parameter records including timestamp, value, unit, and provisional/approved qualifiers. Accepts up to 100 site numbers in one call. Use water_find_sites first to discover valid site numbers and available parameter codes. Groundwater depth is available via parameterCd=72019 (Depth to water level, ft below land surface). For a date-range time series, use water_get_series instead.
| 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). | 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. |
Tool Definition Quality
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true. The description adds operational details: ~15 min update frequency, 100 site limit, per-site per-parameter record structure, and qualifier types. No contradictions. Adds value beyond 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 4 sentences, each serving a distinct purpose: function, return format, constraints, and guidance to related tools. No fluff, well organized, and front-loaded with main action.
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, the description adequately explains return structure (per-site per-parameter records with timestamp, value, unit, qualifiers). Covers site limits, period default, parameter examples, and ties to sibling tools. Complete for the tool's complexity.
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 each parameter described. Description reinforces the 100 site limit, explains period default (PT2H), provides an example parameter code (72019), and directs to water_list_parameters for more codes. Adds context 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?
The description clearly states it retrieves latest instantaneous values for USGS monitoring sites, specifying real-time updates, per-site per-parameter records with relevant fields (timestamp, value, unit, qualifiers). It distinguishes from sibling tool water_get_series for date-range queries, providing a specific verb and resource.
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 first for site discovery and water_list_parameters for parameter codes. Provides example parameter code (72019) for groundwater depth. States when to use water_get_series instead. Also mentions 100 site limit and default period behavior.
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 time series of daily or instantaneous values for a USGS site and parameter over a date range. Returns siteNumber, parameterCd, and time-ordered value records. When the server has DataCanvas enabled, large result sets (>500 records) spill to a canvas — the response includes canvas_id and table_name for SQL analysis via water_dataframe_query. Without DataCanvas, returns the most recent 500 records with truncated=true. Use water_find_sites to discover valid site numbers. Use water_list_parameters for parameter codes.
| 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 | 5-digit USGS parameter code (e.g. "00060" for discharge, "00065" for gage height). 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?
Annotations declare readOnlyHint, openWorldHint, idempotentHint. The description adds critical behavioral context: DataCanvas spill behavior (>500 records creates canvas_id/table_name), truncation without DataCanvas (truncated=true, 500 record limit). 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?
Description is efficient (4 sentences) and front-loaded with primary purpose. It covers return fields, DataCanvas behavior, and cross-references. Minor repetition of 'daily' and 'instantaneous' from schema, but overall concise and well-organized.
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 complexity (6 params, output schema exists, sibling tools), the description is comprehensive. It explains return types, edge cases (truncated, canvas spill), prerequisites (site/parameter discovery), and optional behavior (canvas_id). Output schema handles return value details, so description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds significant meaning: site number format (8-15 digits, example), parameterCd usage (5-digit, examples), startDate/endDate format (YYYY-MM-DD), canvas_id purpose (append vs fresh), seriesType default and high-resolution use case. All parameters are well-explained 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?
The description uses specific verb 'get' and resource 'time series' with clear qualification (daily/instantaneous, USGS site, parameter, date range). It explicitly names sibling tools for discovery (water_find_sites, water_list_parameters), distinguishing purpose.
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 states when to use (to retrieve time series data) and references sibling tools for prerequisites (site/parameter discovery). It lacks explicit 'when not to use' statements but provides sufficient context via alternatives.
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
Static lookup of well-known USGS parameter codes with human-readable names, units, and thematic domain. No network call. 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!