Server Quality Checklist

Tool Scores

• ras_results_summaryA
  3.9/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It transparently states the tool reads the HDF, does not require HEC-RAS, and presents units according to the project. It does not explicitly state whether it modifies the file, but the summary nature implies read-only; still, an explicit read-only statement would be stronger.

  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 a single dense sentence that efficiently conveys the tool's scope. It is front-loaded with the core purpose and lists components without redundant fluff. It is long but earned by the number of features.

  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?

  The tool is complex, and the description covers the major output areas: plan info, QA, unsteady summary, volume accounting, runtime, cross sections, 2D mesh, reference lines, and boundary conditions. It also notes units and the no-HEC-RAS requirement. With no output schema, this provides a solid mental model, though a simple example or output format hint would be slightly more complete.

  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 parameters are already well-documented. The description adds context by mentioning top-N in the cross-section summary, which aligns with top_n, but does not add significant new semantics beyond the 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 opens with 'One-screen summary of a HEC-RAS results HDF' which clearly identifies the tool's action (summarize) and resource (results HDF). It enumerates the included components, distinguishing it from sibling tools like ras_results_timeseries and ras_results_compare.

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

  Usage Guidelines3/5

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

  The description implies usage—when you need a consolidated overview of a results file—but does not explicitly contrast with sibling tools or state when not to use it. The note 'No HEC-RAS needed' is a useful prerequisite, but more explicit guidance would be better.

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

• ras_results_timeseriesA
  3.9/5.0
  Behavior3/5

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

  The description discloses downsampling to 'at most max_points' and the default first-location behavior, adding valuable behavioral context beyond the schema. With no annotations, the description carries full burden, but it does not clarify the exact output structure for peak/time of peak/min/mean or how errors like missing HDF are handled.

  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 front-loads the core purpose and then methodically details kind-specific parameters in a single dense paragraph. While compact, the run-on structure for kinds could be easier to parse, but each sentence contributes necessary information without fluff.

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

  Completeness3/5

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

  For a 6-parameter tool with no output schema and no annotations, the description covers parameter semantics and downsampling well, but leaves gaps about the returned data format (what exactly 'peak / time of peak / min / mean' looks like) and error behavior. This is adequate but not fully complete.

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

  Parameters5/5

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

  The description significantly enriches the schema: it specifies location formats (e.g., 'River/Reach/Station' for xsec), allowed variables per kind, mesh_cell requirements, and the role of max_points. This goes well beyond the schema's short descriptions, making parameter usage unambiguous.

  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 returns 'One time series from a results HDF' with derived statistics like peak and mean, and enumerates the supported kinds (xsec, ref_line, ref_point, boundary, mesh_cell). This specific verb+resource phrasing distinguishes it from sibling tools such as ras_results_summary and ras_results_compare.

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

  Usage Guidelines3/5

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

  The description explains kind-specific usage and notes 'Omit location to get the first one,' which gives practical context. However, it does not explicitly state when to choose this tool over alternatives like ras_results_summary or ras_results_compare, leaving usage implied rather than directly contrasted.

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

• ras_results_compareA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the alignment behavior ('exact' or 'interpolated'), the metrics computed, and the special xsec ranking mode with counts of increased/decreased/unchanged. It does not mention output format or error handling, but for a read-only comparison tool, the behavioral detail is substantial.

  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 dense but efficient, packing all key information into two sentences. The first sentence lists metrics and alignment; the second details the special mode. It could be slightly more readable but no sentence is wasted.

  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?

  Given 9 parameters, no output schema, and no annotations, the description covers the main usage modes and metrics clearly. It also references sibling tool conventions for parameters. It lacks return-value structure and edge-case behavior, but for the tool's complexity, it is largely complete.

  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 coverage is 44%, so the description must compensate. It adds meaning to the 'location' parameter (optional for xsec to trigger ranking) and the 'variable' parameter implicitly through delta volume. However, many parameters like label_a, label_b, and mesh remain unexplained, and the description points to a sibling tool for some parameter semantics rather than defining them.

  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 compares two runs (baseline vs scenario) and lists specific metrics (delta peak, timing shift, RMSE, NSE, delta volume). It also describes a distinct ranking mode for xsec without location, which differentiates it from sibling tools like ras_results_timeseries.

  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 implicitly establishes when to use this tool—when comparing two HDF files—and references ras_results_timeseries for parameter conventions, which helps an agent understand the usage context. It does not explicitly state exclusions or when not to use, but the comparison purpose is clear.

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

• ras_project_copyA
  4.2/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 of behavioral disclosure. It properly explains scope (all project files), the safety guarantee ('original model is never modified'), and the default exclusion of results HDFs/logs unless include_results=true. This is substantial behavioral context, though it doesn't cover edge cases like overwrite behavior or error handling.

  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 two sentences, front-loaded with the primary purpose, and every clause provides useful detail. There is no fluff or repetition of schema content.

  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?

  Given the tool's moderate complexity, no annotations, and no output schema, the description covers the essential aspects: what gets copied, the exclusion default, and the intended use-case timing. It could mention what happens on overwrite or return behavior, but those are minor gaps for a copy operation.

  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 coverage is 100%, so the baseline of 3 applies. The description adds some context about file types and relative references, but it does not add meaning beyond what the schema already provides for each parameter. For example, include_results behavior is already documented in the 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 opens with a clear action verb and specific resource: 'Copy a whole HEC-RAS project folder to a new folder,' listing the exact file types included. This clearly distinguishes it from sibling tools like ras_run or ras_plot, which perform different operations.

  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 explicitly states when to use the tool: 'Use it BEFORE editing or running so the original model is never modified.' It provides clear context for use but does not name specific alternatives or explicitly state when not to use it, though the sibling list implicitly covers alternatives.

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

• ras_flow_set_hydrographA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description discloses that it edits a copy of the project, returns a before/after summary, can create a boundary if none exists ('kind' parameter), and supports a wide range of hydrograph types. It also mentions the count line rewrite behavior, adding useful implementation detail.

  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 a single dense paragraph of about 150 words, but it is front-loaded with the core purpose. Every sentence adds substantive information, and while it could be organized with bullet points for readability, it is appropriately sized for the tool's complexity.

  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 has 15 parameters and no output schema, the description is remarkably complete. It covers operations, boundary selection methods, supported boundary types, the copy behavior, and the return summary. It even references ras_project_info for boundary_index, which helps the agent understand how to obtain required context.

  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 description adds meaning beyond the schema by explaining the semantics of key parameters: 'values' can be any length, 'multiplier' scales existing values, 'qmult' is applied at run time, and 'interval' has examples. It also clarifies relationships between selection parameters (boundary_index vs river/reach/rs vs area/bc_line).

  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 'Edit ONE boundary condition table in an unsteady flow file (.u##):' which is a specific verb+resource combination. It enumerates the operations (replace values, scale, set qmult, change interval) and distinguishes itself from sibling tools by focusing on unsteady flow file editing.

  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?

  It provides clear guidance on how to select the boundary (boundary_index, river/reach/rs, or area/bc_line) and lists supported hydrograph types. However, it does not explicitly name alternative tools for when not to use it, though the usage context is strongly implied.

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

• ras_manifest_writeA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses key behaviors: writes a JSON manifest, reports missing referenced files, and does not require HEC-RAS. It also details the manifest structure, which goes beyond the schema. However, it does not mention overwrite behavior or return value, which are minor gaps for a write tool.

  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 three sentences, front-loaded with the main purpose and followed by important usage and behavior details. No redundant wording; every sentence earns its place.

  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 complex tool with 11 parameters, nested objects, no output schema, and no annotations, the description gives invocation timing, manifest contents, error reporting, and a system requirement. It falls short only on return value and overwrite semantics, but overall it provides sufficient context for an agent to 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?

  Schema coverage is 100%, so the baseline is 3. The description adds meaning by explaining how parameters compose the manifest: files each with sha256, ras_run QA status, edits from ras_plan_set/ras_flow_set_hydrograph, tool_calls as {tool, args, ok}, and out_json as the write target. This enriches the schema's terse 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 uses a specific verb and resource ('Write a provenance manifest (JSON) for one modelling step') and enumerates the manifest contents (files with sha256, ras_run QA status, edits, tool calls, notes). This clearly distinguishes it from sibling tools like ras_run or ras_results_summary, which focus on execution or analysis.

  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?

  It explicitly states when to use the tool: 'Call it at the end of a run so the run can be audited or re-compared later.' This gives concrete timing and intent. It does not name alternatives explicitly, but the sibling list makes it clear this is the manifest-writing step, and the context is sufficient.

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

• ras_plotA
  4.4/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 behavioral burden. It states the output (PNG path), clarifies that overlays involve 1-4 runs, notes peak annotations for hydrographs, and specifies mesh_max is for a single HDF. It does not mention overwrite behavior or permissions, but these are less critical for a plot-generation tool.

  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 a single dense paragraph with no fluff. The first sentence states the core purpose, and each subsequent sentence explains a distinct plot mode with relevant constraints. It packs necessary detail without redundancy.

  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?

  Given 11 parameters, no output schema, and no annotations, the description covers the major behavioral branches and return value. It could be more explicit about which parameters are required for each plot type and what happens if both hdf and hdfs are provided, but it is largely sufficient for a complex 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 only 55%, and the description compensates well. It explains how hdfs and labels work together, which plot types use hdf vs hdfs, the meaning of reach for profile plots, the optional mesh for mesh_max, and that kind/location/variable/mesh follow ras_results_timeseries semantics. This adds meaning beyond raw schema fields.

  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 action ('Make a PNG figure') and clearly identifies the resource ('results HDF(s)'). It then distinguishes three distinct plot modes (hydrograph, profile, mesh_max), each with a clear behavior, which sets it apart from sibling tools like ras_results_compare or ras_results_summary.

  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 gives clear context for when to use each plot variant: hydrograph for time series, profile for river station maxima, mesh_max for 2D maps. It references ras_results_timeseries for parameter details, but it does not explicitly state when not to use this tool versus alternatives like ras_results_compare.

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

• ras_project_infoA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It explicitly states 'No HEC-RAS install needed' and describes optional expansions in behavior. The verb 'Inspect' implies read-only, and it does not suggest any side effects. This adds useful behavioral context beyond the schema.

  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 dense but information-rich, front-loaded with 'Inspect a HEC-RAS project' followed by a structured list of returned items. It is slightly long but each phrase adds value, and there is no fluff. It could be slightly more scannable, but overall it earns a 4.

  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 complexity and the absence of an output schema, the description does an excellent job of explaining what is returned and how optional parameters alter the output. It covers the main project elements, boundary condition details, and the behavior of include_values, making it a complete reference for an agent without needing additional context.

  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%, so baseline is 3. The description adds meaningful semantics for 'plan' and 'include_values' by explaining what detailed boundary conditions are included and how include_values affects output. This exceeds the schema descriptions, justifying a 4.

  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 'Inspect a HEC-RAS project' and enumerates specific items returned (plans, geometries, flow files, boundary conditions, current plan, Ras.exe path). This is a specific verb+resource with clear scope, distinguishing it from sibling tools like ras_run or ras_plot.

  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 clear context about what can be inspected and optional behaviors (e.g., passing 'plan' for detailed boundary conditions, include_values for full hydrograph). However, it does not explicitly name alternatives or state when not to use this tool, so it falls short of a 5.

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

• ras_plan_setA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description discloses key behaviors: it returns before/after values, rewrites the plan file, and requires a copied project. It also defines format constraints for intervals and dates. This adds significant transparency beyond the schema.

  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?

  Three sentences lead with purpose, then safety note, then format constraints. Every sentence provides distinct, necessary information with no redundancy or fluff.

  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?

  Given 14 parameters and no output schema, the description adequately covers the tool's scope, return behavior, and key format constraints. It also references ras_project_copy for the copy requirement. Minor omission: it does not explicitly mention that the plan must exist or that unlisted settings remain unchanged, but this is acceptable for a settings 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%, so the baseline is 3. The description adds valuable format details for interval strings ('10SEC','1MIN','15MIN','1HOUR') and date formats ('02JAN1900 0000' or ISO), which are not fully enumerated in the 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 clearly states it changes settings of one plan (.p##) in place, enumerating the settings: simulation window, intervals, cores, short id, title, description, geometry, and flow file. This specific verb+resource scope distinguishes it from siblings like ras_run or ras_project_copy.

  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 instructs to edit a copy of the project (ras_project_copy) and warns that the tool rewrites the plan file. This provides a clear prerequisite and effectively communicates when not to use it (on original files), while referencing a sibling tool.

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

• ras_runA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full responsibility. It discloses blocking behavior, watchdog handling of TCU dialog, timeout killing, copy-to-run_dir safety, and the list of returned metrics and warning/error categories. It also hints at file modifications via 'delete .c## preprocessor files' parameter and advises caution for in-place runs.

  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 dense but efficient, covering purpose, execution model, safety, return values, and constraints in a single block. It is front-loaded with the primary action and then details. While somewhat long, every sentence provides essential operational information, making it acceptable for a complex 9-parameter tool.

  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 complexity (9 params, no output schema, no annotations), the description is remarkably complete. It explains return fields, blocking behavior, watchdog, safety modes, prerequisites, and usage cautions. It even covers error-handling guidance ('Gate on status/usable') and environmental requirements (Windows).

  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?

  Although the schema already describes all 9 parameters (100% coverage), the description adds meaningful context beyond the schema. For example, it explains the safety implication of run_dir ('safe'), the default for accept_tcu, and the timeout default. This enriches the parameter understanding without repeating schema definitions.

  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's function: 'Run one HEC-RAS plan headless' and perform QA. It uses a specific verb ('run'), names the resource (HEC-RAS plan), and differentiates from sibling tools by focusing on execution and result QA rather than file operations or plotting.

  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 practical guidance: use run_dir for safe copying, warns 'use on a copy!' when running in place, and instructs to 'Gate on status/usable, not on ok'. It also notes the requirement for Windows and HEC-RAS installation. It does not explicitly list alternatives but the sibling tools clearly serve different purposes.

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