gencase

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

The description discloses the primary behavior: it runs an external tool and writes multiple output files, and it explains defaults for output_dir, out_name, and save_modes. However, with no annotations, it omits side-effect details such as overwriting behavior, directory creation, environment requirements, and failure modes.

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 front-loaded with a one-line summary followed by a compact bullet list of five parameters with defaults. There is no filler; every line adds operational detail.

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 five parameters, zero annotation coverage, and no schema-level parameter descriptions, the description covers all invocation essentials, and the output schema covers return values. It is slightly incomplete on selecting this tool relative to siblings and on prerequisites/environment, but it is sufficient to invoke 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 0%, so the description must supply parameter meaning. It does so fully: xml_path accepts *_Def.xml with or without extension; output_dir and out_name have explicit defaults; save_modes is tied to GenCase -save and 'all' is expanded; extra_args is illustrated with an example.

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 opening line names a specific action ('Run GenCase') and defines the resource transformation (case XML → Case.xml + Case.bi4 + optional VTKs). This makes the tool's scope clear and separates it from simulation/post-processing siblings, though it never names those alternatives explicitly.

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?

No explicit when-to-use or when-not-to-use statements; the presence of sibling tools such as run_case and validate_dambreak is not leveraged. The intended use is only implied by the XML-to-case-file conversion description, so an agent must infer when this step is needed.

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