command_help

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.

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.

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.

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.

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.

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.