run_shelx

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

No annotations are provided, so the description carries the full burden. It discloses that workdir defaults to a throw-away temp dir, that timeout aborts the run, and that return_output controls whether generated files are included in the reply. It notes output includes program output, return code, and generated files. Does not mention potential side effects like file deletion, but as a console-program runner this is reasonably transparent.

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 prose intro is one clear sentence, followed by a tight argument list with brief one-line descriptions. Front-loaded with the core purpose. Minor waste: the returns line re-states return_output which is already in the arg list, but overall efficient.

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?

Output schema exists, so return-value explanation is not required. With 7 parameters and no annotations, this description covers purposes of all params and key behaviors. Given it's a generic exec wrapper (no output schema coverage needed for return format), the description is appropriately complete for an experienced crystallography domain agent.

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 explain parameters. It does define each param's purpose (program enum list, ins full text, hkl optional, basename file base, timeout seconds, return_output include). However, it provides little beyond restating schema field names — e.g., it does not specify default for timeout (120s), default basename, or constraints on program values beyond listing them. Adequate but not rich compensation for the 0% coverage.

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?

Description states a specific verb+resource ('Run a SHELX console program on supplied input files and return its output') and lists all valid programs. It clearly distinguishes from siblings like solve, refine, and list_commands by framing itself as a generic execution wrapper rather than a domain-specific operation.

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 explains when hkl is needed (for refinement) and when workdir can be omitted (throw-away temp dir). It provides context for when the tool applies, though it does not explicitly say 'use X command instead for Y case' — e.g., when to prefer solve/refine sibling tools over run_shelx. Clearly the generic exec tool, and siblings are domain wrappers.

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