usgs-water-mcp-server

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

Annotations declare readOnlyHint=true and idempotentHint=true, so the description need not restate non-mutating behavior. The description goes beyond annotations by clarifying that this is an inspection step in a multi-step workflow, that it produces the table name needed by a sibling tool, and that it errors if DataCanvas is disabled. No contradiction. A small point: it could mention that it returns table names and column types (implied) but still solid given 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?

Four sentences, each building on the previous: what it lists, when to call, what to do next, and failure mode. Front-loaded with the action and resource. No wasted words.

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 single, required, well-explained parameter, a complete output schema, and annotations covering safety, the description covers the workflow placement (after fetch, before query), the error condition, and the next step. Nothing needed to call it correctly is missing.

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

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

Schema coverage is 100%, so the schema already describes canvas_id. The description adds context that canvas_id comes from water_get_series or water_find_sites, which is helpful, but does not add a lot beyond that. Since coverage is complete, baseline is 3, and the description earns a 4 by tying the parameter to the exact provenance.

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 states a specific verb ('List'), a clear resource ('tables and columns staged on a DataCanvas'), and the two functions that produce the canvas. This distinguishes it from siblings like water_dataframe_query, which runs queries, and from the data retrieval functions, by tying it to the DataCanvas staging 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?

Explicitly says to call this after water_get_series or water_find_sites returns a canvas_id, before writing a query, and to then pass the table name to water_dataframe_query. It also names the exact prerequisite sequence and the error condition when DataCanvas is not enabled. This is clear when-to-use and sequential guidance.

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true, so the description's statement that only SELECT is permitted aligns with and reinforces these. The description adds valuable behavioral context beyond annotations: the 10,000-row cap with truncated=true response flag, the requirement for DataCanvas to be enabled, and the error condition when DataCanvas is unavailable. It doesn't detail the exact response structure, but the output schema exists, so that's covered. The only minor gap is not explicitly stating that the tool is non-destructive, but that's already in 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 a single paragraph that front-loads the core purpose (read-only SQL SELECT) and then provides workflow, constraints, and error conditions. It's dense but not bloated; every sentence adds necessary information. The only slight inefficiency is the repetition of the workflow steps, but that's acceptable for clarity. It could be slightly more structured with bullet points, but the current format is readable and efficient.

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 (SQL query execution with constraints), the description is complete: it covers prerequisites, workflow, allowed operations, result limits, error conditions, and how to handle large result sets. The output schema exists, so return values are documented. The description leaves no critical gaps for an agent to call 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?

Schema description coverage is 100%, so both parameters (sql and canvas_id) are well-documented in the schema. The description adds value by explaining the workflow context: canvas_id comes from water_get_series or water_find_sites, and sql should reference the table_name from those tools, with an example query. It also advises running water_dataframe_describe first for exact schema. This goes beyond the schema's basic descriptions, though the schema already covers the core semantics.

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 runs read-only SQL SELECT queries against water data tables staged on a DataCanvas, and explicitly names the prerequisite tools (water_get_series, water_find_sites) and the workflow step (water_dataframe_describe). This distinguishes it from siblings like water_get_readings and water_get_conditions, which are direct data retrieval tools, by emphasizing the SQL analysis capability.

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 an explicit workflow: run water_get_series or water_find_sites to get canvas_id and table_name, then water_dataframe_describe to confirm schema, then water_dataframe_query for SQL analysis. It also states when not to use it (only SELECT permitted) and how to handle large result sets (use WHERE/LIMIT, SELECT COUNT(*) or water_dataframe_describe for true counts). This is comprehensive guidance for an agent.

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

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

Annotations indicate read-only, idempotent, and open-world behavior; the description adds the 500-site cap and truncation behavior, which is valuable. It could disclose the exact meaning of 'upstreamTotal' more, but it provides enough 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 dense but front-loaded with the core purpose and call-first guidance. It includes important nuances about truncation and DataCanvas, but the length is justified given the complexity. It's structured logically with actionable details.

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?

The description covers key usage context, truncation behavior, and integration with sibling tools. With an output schema present, it doesn't need to detail return values. It's complete for an agent to call correctly, including prerequisites and edge cases.

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?

With 100% schema coverage, the description adds limited parameter-specific detail, though it mentions the expanded mode and truncation which relates to siteOutput. The description doesn't compensate much beyond the schema, but the schema is thorough, 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 the tool finds USGS water monitoring sites by various filters and specifies the return fields. It distinguishes itself from sibling tools that require a site number, making its purpose and relationship to other tools explicit.

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 instructs to call this tool first because siblings require a site number, and provides specific guidance on handling truncation, including narrowing filters or using DataCanvas. This is clear direction for when and how to use it.

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

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

The description discloses important behavioral nuances: the reading is instantaneous while percentiles are daily-mean (hence approximate), and that a null historicalContext is returned for short records instead of an error. This goes beyond the read-only and idempotent annotations, providing critical expectations.

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 a single, well-structured paragraph that conveys all necessary information without redundancy. While it is fairly long, every sentence contributes meaning, covering the core function, limitations, and fallback behavior.

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?

The description fully equips an agent to use the tool correctly: it explains the metric, the approximation, the null case, and points to sibling tools for input discovery. Given the output schema exists, the absence of output details is acceptable.

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 schema already fully describes the parameters (site and parameterCd) with patterns and examples. The description adds value by advising the use of water_find_sites and water_list_parameters to resolve valid values, enhancing parameter semantics 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 tool's purpose: retrieving a current reading ranked against daily-mean percentiles, explicitly distinguishing it from flood/drought assessments. It names specific resources (USGS site, parameter code) and contrasts with sibling 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?

It explicitly states when to use the tool (when percentile ranking is needed) and when not to (not for flood-stage or drought determination). It also directs users to water_find_sites and water_list_parameters for input resolution, giving clear contextual guidance.

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

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description goes beyond these by revealing the 10-record cap per series, the truncated flag and totalValues mechanism, and the missingSites behavior — non-obvious operational details an agent must know to interpret results correctly. 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?

Three dense, information-rich sentences. The core function is front-loaded, followed by the most critical limitation (10-record cap) and the alternative tool, then the missingSites behavior. Every sentence earns its place with zero fluff or repetition.

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 an output schema exists (so return shape is already defined), the description covers the essential operational context: what data is returned, the truncation policy, how missing sites are handled, and the recommended discovery workflow. Nothing an agent needs to call and interpret the tool correctly is missing.

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 description coverage is 100%, so the schema already documents parameters well (baseline 3). The description adds meaningful behavioral context, particularly for the period parameter — widening it raises totalValues but still caps each series at 10 records — and explicitly directs users to water_get_series for full retrieval. This extra nuance lifts it above the baseline.

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 opens with a specific verb ('Get') and resource ('instantaneous values for up to 100 USGS sites'), and precisely scopes the output (per-site, per-parameter records with qualifiers). It explicitly contrasts itself with water_get_series ('use water_get_series for a full date-range series'), making the purpose unambiguous and distinguishable from siblings.

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?

It names the alternative tool (water_get_series) for full series and explicitly recommends water_find_sites as a prerequisite ('Use water_find_sites first to discover site numbers and available parameters'). It also clarifies expected behavior for missing sites, providing clear when-to-use and when-not-to-use context.

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

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

Annotations provide readOnlyHint, openWorldHint, idempotentHint. Description adds valuable behavioral context: truncation behavior for large sets, canvas spillover with DataCanvas enabled, and reference to SQL query via water_dataframe_query. This goes 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?

Three sentences, dense and front-loaded. Each sentence contributes: what, behavior on large sets, and how to resolve inputs. No fluff.

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 doesn't need return details. Covers truncation, canvas spillover, and input resolution. Sufficient for an agent to call correctly without knowing specific response structure.

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 meaning: clarifies truncation as a consequence of large sets and canvas spillover. It explains that canvas_id is for appending to existing canvas. The description complements schema details with usage semantics, especially around truncation and canvas behavior.

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?

States a specific verb (get), resource (time series for one USGS site and parameter), and scope (daily/instantaneous over a date range). It distinguishes from siblings by mentioning water_find_sites and water_list_parameters as resolving inputs, and by referencing water_dataframe_query for canvas spillover.

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?

Clear context for when to use: it returns daily or instantaneous series for one site/parameter. It doesn't explicitly say when not to use it vs. water_get_conditions or water_get_readings, but it does reference sibling tools for resolving inputs. Slight gap in exclusion criteria.

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

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

Annotations already indicate read-only, idempotent, and closed-world behavior. The description adds that the catalog is 'static, built-in,' which further clarifies that no external calls or mutations occur. While it doesn't mention error cases or rate limits, the bar is lower given annotations, and the added context is meaningful.

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, front-loaded with the main purpose, then providing concrete examples and usage. It is concise, well-organized, and avoids unnecessary fluff.

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 simple nature of the tool and the richness of the schema, the description is complete. It covers what the tool returns (codes, names, units, domain), gives usage guidance, and provides examples. No critical information is missing for an agent to use it 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 fully describes the 'group' parameter with an enum and default, including a detailed description. The tool description merely repeats the filter concept ('Filter by group') without adding new semantics. Since schema coverage is 100%, the baseline is 3, and the description does not exceed it.

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 function: listing USGS parameter codes with human-readable names, units, and thematic domain. It distinguishes itself from sibling tools (dataframe operations, site/conditions/readings/series) by focusing on the code catalog, and even provides concrete examples (00060 = 'Discharge' ft³/s).

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 usage guidance is provided: 'Use this first to discover...' and 'Filter by group to narrow results.' This tells the agent when to invoke this tool (before data retrieval) and how to use the filter, which is sufficient given the sibling tools context.

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