john_crack

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It does not mention whether the tool runs in the foreground, how long it might take, whether it creates session files, or any side effects (e.g., writing to a pot file). For a resource-intensive tool like John the Ripper, this is a significant omission.

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 only two sentences, no unnecessary words. It is front-loaded with the primary purpose and quickly lists supported modes. This is appropriately concise and well-structured for an AI-readable description.

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 tool's complexity (9 optional parameters, no output schema, no annotations), the description is too thin. It doesn't explain what happens after the command completes, how to retrieve results, or how the tool interacts with siblings like john_status and john_show. The agent would need to infer the workflow from the schema and sibling names, which is a gap.

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 100%, so the parameters are already well-documented. The description mentions 'wordlist' and 'incremental' modes, but these map directly to the 'wordlist' and 'incremental' parameters without adding new semantics. It provides a conceptual overview but no additional detail beyond the schema.

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 explicitly states the tool's function: 'Start password cracking with John the Ripper.' This clearly distinguishes it from sibling tools like john_status, john_show, and john_restore, which are auxiliary operations. The mention of supported modes ('wordlist, incremental, and single crack') further clarifies the tool's scope.

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 phrase 'Start password cracking' provides clear context for when to use this tool versus the siblings. It implies you should invoke this when you have hashes to crack, while the other tools are for monitoring, restoring, or inspecting results. However, it does not explicitly exclude alternatives or list when-not-to-use scenarios, so it falls short of a 5.

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