Server Quality Checklist

Tool Scores

• list_common_parameter_codesA
  4.5/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses a key behavioral trait: 'No network call' and 'Returns a static table of {code, name, unit, description}' — describing the returned structure. This is good transparency for a zero-annotation tool, though it could mention whether the table is exhaustive or limited to common codes only.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is compact, two sentences, and front-loaded with the primary purpose. Every sentence earns its place — purpose, examples, return structure, and the non-network caveat. Slightly redundant phrasing could be trimmed, but it is appropriately concise.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness4/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a static lookup tool with 0 params and no output schema, the description is quite complete: it covers what it returns, that it makes no network call, and the example use cases. It could list the full set of supported measurements or any limitations, but for its simplicity it is well-rounded.

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

  Parameters4/5

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

  The tool has 0 parameters and 100% schema coverage (empty schema completes the picture). Baseline for 0-param tools is 4. The description adds useful context about what the returned record fields are ({code, name, unit, description}), which is additional value beyond the empty schema.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description clearly states a specific verb+resource: 'Look up the 5-digit USGS parameter code for a common measurement.' It explicitly distinguishes from siblings by naming the purpose (getting codes before calling get_instantaneous_values) and noting this is a lookup/reference tool vs. the data-fetching siblings.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  It explicitly states when to use it: 'before calling get_instantaneous_values.' It gives the context (for common measurements like streamflow, gage height, water temperature, dissolved oxygen) and lists examples of what kind of lookup it serves, which orients the agent toward the correct choice among siblings.

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

• find_sitesA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and delivers richly: discloses that nameContains is applied client-side after fetching and that the /site/ service silently ignores name-search params; explains result ordering (first maxSites in USGS site-number order by drainage basin); exposes the siteStatus default divergence from get_instantaneous_values; documents the capped results and truncated/totalMatched behavior.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness4/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is long but every paragraph earns its place—each covers a distinct, non-obvious behavioral or usage topic. Front-loaded with the purpose and primary use case, then progressively deeper caveats. Slightly verbose in places but justifiably so for the complexity of the behavior being disclosed.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 10-parameter tool with no annotations and no output schema, the description is remarkably complete. It covers filters, defaults, side effects (truncation, client-side filtering), return quirks (siteNumber length variance, truncating/totalMatched), and ordering semantics. No meaningful gap remains for the agent to make bad decisions.

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

  Parameters4/5

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

  Schema coverage is 60%, so the description adds moderate value. It clearly explains the crucial nameContains client-side behavior (which the schema already touches on, but the description expands with the 'cannot be used alone' and 'narrows rather than replaces' semantics) and the major-filter-required rule. It doesn't re-explain already-covered params like huc/bBox, appropriately relying on the schema for those.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description opens with a specific verb+resource ('Look up USGS station numbers') and immediately ties it to a downstream consumer (get_instantaneous_values), distinguishing it from sibling tools. It gives concrete use cases (place/river name queries) that differentiate it from get_instantaneous_values and list_common_parameter_codes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Provides exhaustive when-to-use guidance: use when you have a place/river name rather than a station number; names get_instantaneous_values as the intended downstream consumer; explicitly contrasts siteStatus/default behavior with get_instantaneous_values; gives concrete strategy advice (pair broad filters with nameContains, prefer narrow filters otherwise) and tells when NOT to raise maxSites.

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

• get_instantaneous_valuesA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and delivers richly. It discloses tri-state `stale` semantics, how `discontinued` works, siteStatus default behavior differing from siblings, per-sensor capping of maxValues, truncation behavior, omission of series without placeholders and the missingParameterCodes signal, provisional ('P') qualifier handling, and that dated queries return readings as old as the window regardless.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness5/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  Long but every sentence earns its place, covering genuinely non-obvious behavior (stale being tri-state, per-sensor capping, no placeholder for missing series, years-old dormant readings). Well organized with thematic paragraphs and a closing pointer to list_common_parameter_codes. None of the length is filler or tautology.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  For a 15-parameter tool with no output schema and no annotations, this is remarkably complete. It covers the cardinality constraint, date-range exclusivity, the two modes' payload implications, staleness semantics, series-to-parameter matching, and sibling-tool handoffs. The only mild gap is no mention of `modifiedSince` or `agencyCd`, but the schema covers those adequately.

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

  Parameters4/5

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

  Schema description coverage is only 33%, so the description must compensate, and it does extensively for the critical params: sites (exact digits, from find_sites, no truncation), bBox (named fields, decimal degree signs, area cap), period (ISO-8601 examples), mode (summary vs values tradeoffs). It adds meaning beyond schema for these. Some params like modifiedSince, agencyCd, siteType get no prose, but those have self-evident schema descriptions.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description begins with a specific verb-resource statement ('Query the USGS Instantaneous Values (IV) service for real-time and recent surface-water and groundwater readings') naming exact data types. It clearly differentiates from siblings: find_sites resolves names to station numbers (this tool does not), list_common_parameter_codes provides parameter codes. The scope is unambiguous.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines5/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  Exceptionally explicit: states the exactly-one-filter requirement (sites/stateCd/huc/bBox/countyCd) and that zero or more than one is rejected. Names alternatives explicitly ('call find_sites first', 'use list_common_parameter_codes first'). Distinguishes from find_sites' default siteStatus behavior and explains when summary mode should be used.

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