Server Quality Checklist

Tool Scores

• validate_insB
  3/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. The description states it 'Reports which mandatory cards are present, plus a few common mistakes' but does not disclose whether this is a read-only operation, whether it modifies any files, what happens if the input is invalid/malformed, or the format of the report it produces. For a validation tool with zero annotation coverage, more behavioral detail would be expected.

  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 compact at two short sentences, front-loaded with the primary purpose in the first line. It lists concrete card names without excess verbiage. Slightly under-specified in behavioral detail but not padded with filler. Efficient overall.

  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?

  The tool has 1 parameter and an output schema (which can carry return-value documentation), so completeness burden is moderate. The description names the specific mandatory cards, which is valuable, but it doesn't detail what 'a few common mistakes' covers or what the output report looks like. Given the output schema exists, the return format may be covered elsewhere, making this adequate but not rich.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the single parameter 'ins' is entirely undocumented by the schema. The description mentions '.ins file' in prose, which implies 'ins' is the file path or content, but it doesn't clarify whether it expects a file path, file content as a string, or something else. The description partially compensates by referencing the file type, but ambiguity remains about the parameter's exact nature.

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

  Purpose4/5

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

  The description clearly states what the tool does: checking an .ins file for SHELXL header cards required before HKLF/END. The verb 'Check' with the specific resource '.ins file' and the specific card names (TITL, CELL, ZERR, LATT, SYMM, SFAC, UNIT, HKLF, END) makes the purpose specific and distinguishable. It lacks explicit sibling differentiation but the purpose is clear.

  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 context: use this to validate an .ins file before running SHELXL. It mentions the specific file type (.ins) and what it checks for, giving the agent a sense of when this is appropriate. However, it doesn't explicitly state when NOT to use this versus alternatives like run_shelx or analyze_results, or what makes this preferable over checking manually.

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

• analyze_resultsB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. It does state what the tool returns (R1, wR2, GooF, max shift/esd, atom count, warning lines), which gives agents confidence about the outcome. However, it doesn't disclose behaviors like what happens if no valid refinement data is found, whether it requires one or both files, or any edge-case handling. No contradiction with annotations since none exist.

  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 compact at roughly two sentences, with the return-value detail front-loaded into the first sentence. Every sentence earns its place by conveying purpose and output expectations. Minor waste is the vague phrase 'SHELXL' which could be slightly expanded, but overall it's efficient.

  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?

  The tool has a modest complexity (2 optional params, output schema exists) and the description is reasonable but not comprehensive. While the output schema exists, which reduces the need to describe return values, the description doesn't explain the relationship between the two optional input parameters or what happens when only one is provided. For a tool with this complexity, it's adequate but has clear gaps in usage context.

  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 0%, so the description carries full parameter documentation burden. The description mentions both 'lst' and 'res' files by name ('from SHELXL .lst and/or .res text') which maps to the two parameters, but it doesn't explain their format, required vs optional status details, or whether one is sufficient. The parameters have generic titles ('Lst', 'Res') with no schema descriptions, so the tool description's brief mention is minimal compensation.

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

  Purpose4/5

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

  The description states a clear purpose: 'Summarise refinement metrics from SHELXL .lst and/or .res text' with a specific verb (summarise) and resource (refinement metrics files). It lists the specific metrics returned (R1, wR2, GooF, max shift/esd, atom count, warning lines), which distinguishes it from sibling 'analyze_solution'. However, it doesn't explicitly differentiate from 'analyze_solution' by name.

  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 context (analyzing SHELXL output files) and mentions it handles both .lst and .res files. However, it doesn't explicitly state when to use this vs 'analyze_solution', nor does it provide exclusion criteria or explain the relationship between the two input files (whether to provide both, or either is sufficient) or prerequisites for usage.

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

• search_commandsA
  3.5/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral disclosure burden. The description is a search/read operation, which is implicitly non-destructive, but it doesn't disclose behavior like case-sensitivity, pagination, or whether results are limited across names, descriptions, or both. The limit parameter is documented in schema, so some behavior is self-evident.

  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?

  A single sentence that is efficient and waste-free. It captures the search functionality in minimal words with no redundancy or filler.

  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?

  The tool has an output schema, so return values are documented elsewhere. However, with zero annotations and no usage context, the description could add value by noting that SHELXL has many commands and this is the way to discover available instructions. Given the low parameter complexity and presence of output schema, this is minimally adequate but could be richer.

  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 0%, so the description carries full param responsibility. However, with only 2 simple parameters (query, limit) the complexity is low. The description says 'by keyword across names and descriptions' which explains what query matches against, but doesn't explain what 'limit' does beyond schema's default value. Since the schema covers the types and defaults, and the description adds the matching scope, this is adequate.

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

  Purpose4/5

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

  The description states a specific verb+resource ('Search SHELXL instructions') and the scope ('by keyword across names and descriptions'). It clearly distinguishes from siblings like 'list_commands' (which lists all commands) and 'command_help' (which likely shows details for a specific command). It doesn't explicitly name sibling alternatives, but the purpose is distinct enough.

  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 this is for finding SHELXL commands by keyword, versus listing all (list_commands) or getting specific help (command_help). However, it doesn't explicitly state when to use this tool vs. alternatives, nor any exclusions. The context is somewhat clear from the sibling names but not explicitly documented.

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

• solveA
  3.5/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool runs a structure solution and requires specific setup files, but does not disclose what happens on failure (e.g., what if shelxs fails and shelxt fallback is needed), timeouts, whether it modifies files, or what results may be produced. The program parameter and defaults are mentioned implicitly but behavior during execution is not disclosed.

  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 compact and front-loaded with the core purpose in the first sentence. The second sentence adds the prerequisite file setup details in a structured list-like format. There is minimal waste. It could potentially be shorter, but the prerequisite detail is valuable for correct usage.

  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 has an output schema (which reduces the need to explain return values) and the description covers the key prerequisites and method selection. The complexity is moderate (crystallographic structure solution with multiple program options), and the description addresses the main usage concerns. Minor gaps exist in clarifying program parameter values and error/failure behavior, but the core completion is adequate.

  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 0%, so the description must compensate. It explains what the .ins and .hkl files are and their content requirements, which adds meaning beyond the bare schema. However, it doesn't clarify the 'program' (beyond mentioning shelxs/shelxt as solution methods), 'timeout', or 'basename' parameters. The description adds value for the two file parameters but leaves three parameters undocumented.

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

  Purpose4/5

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

  The description clearly identifies the action ('Run structure solution') with a specific resource (the structure solution step of crystallographic data processing). It names the default method (SHELXS direct methods) and the alternative (shelxt for dual-space), which helps distinguish capabilities. However, it doesn't explicitly distinguish itself from the sibling 'refine' tool beyond the implied context, though the difference is reasonably clear from context.

  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 prerequisites: an .ins file set up for solution with specific required instructions (TITL, CELL, ZERR, LATT, SYMM, SFAC, UNIT, plus TREF/FMAP and HKLF/END) and corresponding .hkl data. It also explains when to use shelxt vs shelxs (default vs dual-space). It doesn't explicitly name alternative tools or state 'when not to use', but the prerequisite specification is substantial practical guidance.

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

• command_helpA
  3.6/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the burden. It clearly states the tool is a read-only lookup returning documentation text, which implies no side effects. It doesn't describe behavior for invalid or unknown instruction names (error handling), but as a documentation retrieval tool the lack of mutation concern is acceptable. The description is honest and not misleading.

  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 extremely tight: two sentences plus an example, with zero wasted words. It's appropriately front-loaded with the core purpose and includes a concrete illustrative example for format clarity.

  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 simple (1 required param) and has an output schema, which offloads return-value documentation. For a documentation-lookup tool this is appropriate coverage: the purpose, parameter semantics, and example are all present. It's reasonably complete for its complexity level, though additional notes on help output format or error behavior for invalid names could add a bit more value.

  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 0%, so the description must compensate. The description clarifies that 'name' is a SHELXL instruction name, which adds real meaning beyond the bare schema field 'Name'. The examples ('ANIS', 'L.S.') help clarify the expected format. However, it doesn't specify whether input is case-sensitive or whether special characters/spacing are handled in a specific way.

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

  Purpose4/5

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

  The description clearly states the tool returns the SHELXL instruction signature and full description for a given command name, with concrete examples ('ANIS', 'L.S.'). The purpose is specific (verb 'return' + resource 'instruction signature and description'). It doesn't explicitly distinguish from siblings, though siblings like search_commands and list_commands suggest this is the targeted help-lookup tool.

  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 the signature or description of a specific named SHELXL instruction. However, it doesn't state when NOT to use this vs alternatives (e.g., search_commands for finding commands by keyword, list_commands for enumeration). No exclusions or alternative-tool guidance is provided.

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

• refineA
  3.6/5.0
  Behavior3/5

  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 the input requirements and the outputs (.lst summary and .res model), which is helpful. However, it doesn't disclose side effects—refinement typically writes intermediate files including potentially overwriting .res, .lst, .fcf, and log files—nor does it mention error behavior when input is invalid. The output description adds context but stops short of full behavioral disclosure.

  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 two concise paragraphs. The first delivers the core purpose efficiently, and the second covers inputs/outputs. No filler or redundant phrasing. Slightly more could be added on parameters, but it's tight and front-loaded with the most important information.

  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?

  The tool has 5 parameters (0% schema coverage), multiple sibling tools, and an output schema. The description identifies the key inputs, outputs, and supported programs. However, for a computation-heavy tool with no annotations, it would benefit from disclosing expected runtime implications, file side effects, or common failure modes. The presence of an output schema lightens the return-format explanation burden, but the behavioral/parameter gaps remain.

  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 0%, so the description must compensate. It explains what ins and hkl are (the .ins file and .hkl reflection data) through the prose. However, it doesn't explain program (beyond the CGLS mention), timeout, or basename semantics—these are named in the schema but their purpose isn't elaborated in the description. Partial compensation, leaving several parameters underspecified.

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

  Purpose4/5

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

  The description clearly states the tool runs least-squares structure refinement using SHELXL or CGLS via shelxt, with a specific verb (refine) and resource (structure). It distinguishes itself from siblings like solve (solving vs refining) and validate_ins, though it doesn't explicitly name these alternatives.

  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 specifies prerequisites (complete .ins file with L.S./CGLS and HKLF instructions, plus .hkl data), which gives the agent clear context for when this tool is appropriate. It doesn't explicitly call out when NOT to use it, but the prerequisites effectively gate usage. It mentions the program parameter supports shelxl or CGLS via shelxt, which is useful guidance.

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

• shelx_infoA
  3.7/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the full burden of disclosure. The description clearly signals this is a read-only informational query (reports configuration), which is useful. However, it doesn't describe the output format or what happens if no SHELX directory is configured, which could be relevant behavioral context.

  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?

  One sentence that conveys the tool's complete purpose with zero waste. It efficiently covers what the tool does (reports information) and what it reports (directory and available programs). No filler or 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?

  For a zero-parameter informational tool with an output schema, the description is reasonably complete. It tells the agent what information will be provided. It could mention what might cause the report to differ (e.g., uninstalled/unconfigured SHELX), but for such a simple tool, the description covers the essential purpose adequately.

  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 0 parameters, and the schema shows no properties. With no parameters to document, baseline is 4. The description appropriately focuses on the tool's function rather than parameter semantics since there are none.

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

  Purpose4/5

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

  The description states the tool reports the configured SHELX directory and available programs. This is a specific verb+resource ('report which directory') that clearly distinguishes it from siblings like run_shelx, solve, and refine, which perform actions rather than information queries. The purpose is clear and specific.

  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 this is an informational tool to be used before running SHELX programs, but it doesn't explicitly say when to use it versus alternatives like list_commands or command_help. The context of being an info/reporting tool distinguishes it from action tools, but there's no explicit when/when-not guidance.

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

• analyze_solutionA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears the transparency burden. It discloses what the tool returns (R1, alpha, space group, Flack x, atom count), which is helpful, but doesn't describe edge cases such as expected behavior if inputs are empty/null or malformed, or how multiple solutions 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 is reasonably concise with three short paragraphs, front-loading the purpose. The second paragraph adds meaningful param context. Slightly verbose in naming file extensions but no wasted sentences.

  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 two optional params, no annotations, and an output schema that presumably defines return fields, the description adequately explains what data to pass and what will be returned. It could be more explicit about null-handling and scenario guidance for partial inputs, but is complete for the core use case.

  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 0%, so the description must carry the param documentation burden. It does explain that 'lxt' is the listing text and 'res' is a solution model, and that both are optional-ish ('Pass the listing text as lxt and a solution model as res'). However, it doesn't clarify what happens if only one is provided or the expected format/text constraints of each.

  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 verb ('Summarise'), the resource ('a SHELXT structure-solution run'), and the specific inputs/outputs. It distinguishes from the sibling analyze_results by specifying it targets SHELXT output files (.lxt/.res).

  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 on when to use it (after a SHELXT run) and what inputs to pass (.lxt and .res text). It doesn't explicitly state when NOT to use it or name alternatives like analyze_results, which slightly limits the score.

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

• list_commandsA
  3.9/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the burden. It discloses the key behavior: returns the complete set of instructions in alphabetical order. For a read/list operation this is reasonably transparent, though it doesn't mention output format or whether results are paginated.

  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?

  A single, efficient sentence that conveys the core purpose plus the alphabetical ordering detail. Zero wasted words.

  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 has zero parameters and an output schema exists, so the description's job is minimal. 'List every SHELXL instruction alphabetically' fully captures what's needed. It's complete for a no-parameter listing 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?

  The tool has zero parameters, so there's nothing for the description to elaborate beyond the schema. Per the rubric, 0 params = baseline 4. The description appropriately doesn't waste space on them.

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

  Purpose4/5

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

  Clear verb+resource: 'List every SHELXL instruction the server knows about (alphabetical).' States it's an alphabetical listing of known instructions. It's distinguishable from siblings like search_commands and command_help by its exhaustive/listing nature, though it doesn't explicitly name them.

  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 when to use: when you want the full list of available SHELXL instructions. However, it doesn't explicitly contrast with search_commands (for finding specific ones) or command_help (for details on a single command). No exclusions or alternatives are named.

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

• run_shelxA
  4.1/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters3/5

  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.

  Purpose5/5

  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.

  Usage Guidelines4/5

  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.

• list_solution_keywordsA
  4.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral burden. It discloses that the tool returns a sorted keyword list or a message if the program is unsupported, which is useful. However, it doesn't detail edge cases like what happens with invalid program strings, case-sensitivity, or the exact format of the return value. The return-behavior disclosure is adequate but not rich.

  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 an intro paragraph, an enumeration of covered programs, an Args section, and a returns statement. Each sentence earns its place — there's no filler or redundant content. The differentiation from sibling tools is front-loaded in the second paragraph.

  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 single-parameter list tool, the description is quite complete: it enumerates valid inputs, differentiates from the sibling list_commands, and states the return behavior. An output schema exists, so return format is handled structurally. It's not the most complex tool, and the description covers the essential decision-making information an agent needs.

  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 0%, so the description must compensate for the undocumented 'program' parameter. It does so well: the Args section enumerates the six valid program values explicitly, giving the agent a precise enumerated set even though the schema itself lacks an enum. This substantially adds meaning beyond the bare 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 is very specific: it lists keywords for SHELX solution programs, explicitly naming the tool's verb ('List') and resource (keywords for solution programs). It clearly differentiates from the sibling list_commands by stating it covers solution programs (shelxs, shelxd, shelxt, etc.) rather than SHELXL refinement.

  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 explicitly contrasts with list_commands, stating 'Unlike list_commands (which covers SHELXL refinement), this covers the programs that find or phase a structure.' It also enumerates the exact supported programs (shelxs, shelxd, shelxd_mm, shelxt, shelxc, shelxe), giving the agent clear when-to-use guidance.

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

• solution_helpA
  4.6/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 disclosing behavior. It states that the tool returns a signature and full description, or a not-found message for invalid keywords—important for setting expectations. It also enumerates the exact families of keyword types covered, providing concrete behavioral scope. It does not explicitly claim to have no side effects, but the return-based wording implies a read-only lookup.

  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, followed by compact coverage details, a usage pointer, and an Args section. Each sentence adds value—there's no filler or redundancy. The line breaks and sections (Covers, Use, Args, Returns) make it scannable and effectively sized for the information it conveys.

  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?

  Considering the tool's modest complexity (2 string params, no annotations, output schema present), the description covers purpose, scope, prerequisite usage, parameter details, and return behavior. It also addresses the error case (not-found). The existence of an output schema covers return structure, so the description doesn't need to detail that further. It is complete for an agent to select and invoke correctly.

  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 schema provides only names/types with no descriptions, so the parameter meaning rests entirely on the description. The Args section explains each parameter with allowed values for program (enumerating all six variants) and explicit examples for keyword (TREF, -a, SAD), adding substantial semantic meaning beyond the bare 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 specific verb+object ('Return the signature and description for one SHELX solution keyword'), precisely identifying the tool's function. It further distinguishes itself from siblings by enumerating the covered programs/keyword types and referencing list_solution_keywords, making clear it's the detailed-lookup counterpart to that listing tool.

  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 explicit context for when to use this tool: after discovering valid names via list_solution_keywords, which is named as a prerequisite. It also clearly scopes the tool to solution keywords (shelxs/shelxd/shelxt/shelxc/shelxe), implicitly excluding other command help. However, it doesn't explicitly state 'use command_help for non-solution commands,' so it's slightly short of a full when-not/alternatives statement.

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