ras_run

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.

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.

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.

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.

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.

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.