Server Quality Checklist

Tool Scores

• hydro_find_water_featuresA
  4.3/5.0
  Behavior4/5

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

  Beyond the annotations (readOnlyHint, idempotent, etc.), the description adds valuable context: it names the specific NHD layers (NHDPoint layer 2, NHDLine layer 7), explains return fields (gnis_name, ftype/fcode, reachcode), describes the JSON return structure with counts and truncation, and enumerates error responses. This is rich behavioral disclosure, though it could mention data freshness or rate limits.

  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 well-structured and front-loaded, starting with a clear purpose, then usage guidance, then output format, and finally errors. It is moderately sized and each sentence adds value. Slight verbosity in the return section could be trimmed, but it is not gratuitous.

  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 read-only query tool with no required parameters and a detailed output schema in the description, the tool description is nearly complete. It covers use cases, output format, and error handling. It could be improved by referencing sibling tools for alternatives, but overall it fully equips an agent to select and invoke the tool correctly.

  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 input schema already provides descriptions for all four parameters (100% coverage). The description adds meaningful guidance beyond the schema: it stresses using Polygon/BoundingBox for area searches, clarifies that point features include reachcode, and explains the ftype/fcode vs ftype_label/fcode_label distinction, helping the agent interpret results correctly.

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

  Purpose5/5

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

  The description clearly states the tool finds NHD point & line water features, listing specific examples (springs, waterfalls, dams, gates, levees). It uses a specific verb 'Find' and the resource is well-defined, distinguishing it from sibling tools that focus on waterways/waterbodies/gages.

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

  Usage Guidelines4/5

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

  The description provides explicit 'Use when' examples with concrete queries ('Are there any waterfalls or springs near this point?') and notes the geometric requirement (Polygon or BoundingBox) for point/line features. However, it does not explicitly mention alternative sibling tools when those are more appropriate, so it lacks direct exclusions.

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

• hydro_find_gagesA
  4.4/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent hints, the description extensively discloses behavior: the return payload structure, the unit clarification for dasqmi, explicit error messages, and the guidance about gage point sparsity affecting geometry choice. This is far richer than minimal annotation coverage requires.

  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 well-structured with clear sections for purpose, usage, return values, units, and errors. While longer than the minimal example, each section provides necessary contract-level detail. Minor redundancy exists between the return structure and the unit note, but overall the information is dense and justified.

  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?

  The description covers the full lifecycle of using this tool: what it does, when to use it, how to supply geometry, the exact return format, unit conventions, and error scenarios. With an output schema already present, the description adds no unnecessary return-value explanation and leaves no significant gaps.

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

  Parameters3/5

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

  The input schema already provides 100% coverage for all three parameters, including the mutual-exclusion rule and the recommendation to use Polygon/BoundingBox. The description only reiterates this guidance without adding new parameter-specific meaning, so the baseline score of 3 is appropriate.

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

  Purpose5/5

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

  The description clearly states 'Find NHDPlus stream gages intersecting a geometry' and identifies the specific layer (NHDPlusGage, layer 0). It also explains the gage attributes (NWIS linkage, drainage area) and distinguishes this from sibling tools by focusing on gages rather than waterways or waterbodies.

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

  Usage Guidelines4/5

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

  The description includes an explicit 'Use when:' section with example queries and provides practical advice on using Polygon/BoundingBox because gages are point features. It does not explicitly name alternative tools or when-not-to-use cases, but the context is clear enough for an agent to choose correctly.

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

• hydro_count_featuresA
  4.7/5.0
  Behavior5/5

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

  Despite annotations already declaring readOnlyHint and idempotentHint, the description adds substantial behavioral context: the tool returns ONLY a count (no full attributes), interprets a count of 0, provides exact return JSON structure, and lists specific error messages. This goes beyond what annotations alone convey, covering edge cases and response semantics.

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

  Conciseness5/5

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

  The description is well-organized and every sentence earns its place: a clear purpose, a usage guideline, an interpretation of results, and a concise return/error format. The inclusion of JSON and error examples is justified for agent clarity, and the structure is easily scannable.

  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 relatively simple tool with 4 params and an output schema, the description fully covers the tool's role, output structure, and error conditions. It also addresses the only non-obvious outcome (zero count) and provides enough context for an agent to decide when to invoke it without needing to see the output schema.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the input schema already fully documents all parameters (lat, lon, layer, geometry) with their constraints and inter-dependencies. The tool description adds no extra parameter semantics beyond what is already in the schema, meeting the baseline for full schema coverage.

  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 explicitly states the tool counts features intersecting a point or geometry, using a specific verb ('Return ONLY how many') and resource ('features of a layer'). It differentiates from sibling find_* tools by framing it as a size check, making its purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description tells the agent exactly when to use this tool: 'Use before the find_* tools to gauge result size without fetching full attributes', and for what scenarios (large polygons, densely mapped areas). It also clarifies the meaning of a zero count, effectively guiding when not to proceed.

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

• hydro_find_waterbodiesA
  4.7/5.0
  Behavior5/5

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

  Description adds substantial behavior not in annotations: queries layers 8/9, intersects geometry, returns structured result, and lists exact error messages. Annotations already declare readOnly/idempotent, but this details the operational contract.

  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?

  Front-loaded purpose, use-case list, compact return snippet, and error examples. Every section earns its place; no filler despite being longer than average.

  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 read-only query tool with output schema and 4 optional params, the description is remarkably complete: target layers, coordinate alternatives, return shape, and failure modes. No critical gap for an agent to invoke it correctly.

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

  Parameters4/5

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

  Schema covers 100% of parameters, so baseline is 3. Description adds layer mapping (NHDWaterbody layer 9, NHDArea layer 8) and clarifies the feature_class options, plus shared attributes returned. This is extra semantic value, though most parameter syntax remains in 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?

  Opening line names exact targets ('NHD waterbodies ... and areal water features') with examples (lakes, ponds, reservoirs, swamps). This distinguishes from sibling hydro_find_waterways, which implies linear features, and the rest are distinct tools.

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

  Usage Guidelines4/5

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

  Provides explicit 'Use when' examples (e.g., 'Is there a lake within this parcel?'). It gives clear contexts but doesn't state when NOT to use or name alternatives, so not a full 5.

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

• hydro_find_waterwaysA
  4.7/5.0
  Behavior5/5

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

  Beyond the annotations (readOnly, idempotent), the description discloses truncation via 'truncated' field, conditional fields like 'non_network' only present when include_non_network=True, and lists exact error response strings. It also details the data source and attribute set, providing rich behavioral context without contradicting annotations.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: purpose, data source, usage examples, return format, and error messages. Every sentence contributes useful information, and the formatting improves readability. It is thorough yet not verbose.

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

  Completeness5/5

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

  Given the tool's moderate complexity, the description covers input methods, optional flags, return structure, error handling, and provenance information. The presence of an output schema does not make this redundant; the description adds practical examples and clarifies expected outputs. It is fully adequate for an agent to select and invoke the tool correctly.

  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 input schema has 100% coverage with detailed descriptions for each parameter. The description reinforces and adds usage context (e.g., lat/lon for point queries, geometry for polygons/corridors), and explains the meaning of verbose and include_non_network in practical terms. This adds value over the schema alone.

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

  Purpose5/5

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

  The description clearly states the tool finds NHD flowlines (streams, rivers, canals, artificial paths) intersecting a geometry. It uses specific verbs and resources and distinguishes itself from sibling tools like hydro_find_waterbodies and hydro_find_gages by focusing on flowlines/waterways.

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

  Usage Guidelines4/5

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

  The description provides explicit usage scenarios: 'Use lat+lon when...' and 'Use geometry when...', with concrete example queries. It also explains when to set include_non_network and verbose, giving actionable guidance. However, it does not explicitly name alternative tools for when-not-to-use, though the sibling list and purpose make this mostly clear.

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

• hydro_identify_watershedA
  4.7/5.0
  Behavior5/5

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

  Annotations already declare read-only, idempotent, and non-destructive hints, but the description adds substantial behavioral context: the full return JSON structure (finding, count, truncated, features, provenance, query_geometry), error message formats, and the point-vs-polygon intersection behavior. This goes far beyond the annotations and fully discloses side effects (none) and edge cases.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose, then efficiently organized into return schema, use cases, and error responses. Every section earns its place; the JSON return block is compact and informative, and there is no redundant filler.

  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?

  Despite an existing output schema, the description includes a clear return structure and error handling, making it self-contained. It covers usage scenarios, input constraints, output fields, and possible failure modes, leaving no significant ambiguity for an agent selecting or invoking the tool.

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

  Parameters4/5

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

  Schema coverage is 100%—all three parameters (lat, lon, geometry) are described in the schema. The description adds value by explicitly stating the mutual exclusivity of lat/lon vs. geometry, listing supported geometry types including BoundingBox, and noting that coordinates must be WGS84. This supplements, rather than repeats, the schema info.

  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 and resource: 'Identify the HUC12 watershed(s) containing/intersecting a geometry' and adds context 'WBDHU12, layer 12'. It clearly distinguishes from sibling tools (waterways, waterbodies, gages) by focusing on watershed identification, reinforced by concrete use-case questions.

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

  Usage Guidelines4/5

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

  The description includes a 'Use when:' section with three example queries, providing clear context for when to invoke the tool. It also explains the differing behavior for point vs. polygon inputs. However, it does not explicitly mention when not to use it or direct users to an alternative sibling tool, so it lacks explicit exclusions.

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

• hydro_list_layersA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds useful behavioral context by specifying the return structure (layers array with id/name/geometry_type and provenance) and error response format, which goes 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.

  Conciseness5/5

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

  The description is compact and well-organized: it opens with a one-line purpose, then provides a 'Use when' section, a Returns JSON example, and an error response format. Every sentence serves a clear function with no redundancy.

  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 no-parameter listing tool with an output schema and strong annotations, the description fully covers the tool's behavior, output shape, and error handling. It also contextualizes its role among the find_* siblings, leaving no relevant gaps.

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

  Parameters4/5

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

  The tool has zero parameters, so the schema coverage is 100% and the description carries no parameter burden. Per the rubric, a 0-param tool receives a baseline of 4, and no additional parameter explanation is needed.

  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 states 'List the layers available in the NHDPlus HR service (id, name, geometry type)' which clearly identifies the verb (list), the resource (NHDPlus HR service layers), and the specific output fields. It also differentiates from the find_* sibling tools by noting it covers layers 'beyond those wrapped by the find_* tools.'

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

  Usage Guidelines5/5

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

  The 'Use when' section explicitly states two scenarios: discovering available layers beyond the wrapped find_* tools, and confirming current layer IDs. It also names the find_* tools as alternatives for feature-specific queries, providing clear context for when to prefer this tool.

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