hash_crack

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

With no annotations, the description carries the transparency burden. It explicitly discloses the tool is offline ('Not network-gated'), writes hashes to a temporary file under the output directory, and returns a structured dict with status, cracked credentials, command, and mode. The default wordlist (rockyou) and use of John the Ripper are also stated, providing solid behavioral expectations.

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 structured with headers (USECASE, INSTRUCTIONS, INPUT_DESCRIPTION, etc.) and an Args/Returns block. It has some redundancy between the two parameter sections, but each part conveys useful information and the overall organization aids scanning.

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 lack of schema descriptions and annotations, the description compensates well: it explains inputs, output, example, prerequisites, related tool, offline behavior, and file-writing side effect. It could provide more detail on the result dict structure, but it enumerates the key fields and the output schema is indicated as available. This is robust for a 4-parameter tool.

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 descriptions are absent (0% coverage), so the description's parameter explanations are essential. The INPUT_DESCRIPTION and Args block define each parameter: hashes (newline-separated), wordlist (path with default), hash_format (--format value), and name (temp file label). The example further illustrates usage with a real hash and format, making parameter semantics clear.

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 opens with a specific action: 'Crack supplied hashes offline with a wordlist (John the Ripper).' It clearly identifies the resource (hashes) and method (offline wordlist cracking), distinguishing it from sibling tools like hash_identify (which identifies hash types) and hydra_bruteforce (online attacks). The USECASE section reinforces this by specifying 'hashes you already possess'.

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 USECASE states 'Recover plaintext for hashes you already possess' and PREREQUISITES adds 'operates only on hashes you supply; no target contact,' clarifying the offline, owned-data context. RELATED_TOOLS points to hash_identify, suggesting a potential preceding step, though it does not explicitly say when to use hash_identify instead; the context is generally sufficient.

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