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

Beyond the annotations (readOnlyHint=false, idempotentHint=false), the description discloses that the nonce is single-use, lives 15 minutes, is limited to 3 per citizen per 24 hours, and that recovery never restores secrets. These are important behavioral traits not captured elsewhere, adding real value.

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 front-loaded with immediate context ('The first of two calls', 'No credential'). Every sentence contributes essential information—prerequisites, nonce behavior, security implications—without redundancy or fluff. Efficient and well-organized.

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?

It covers prerequisites, rate limits, expiry, and security aspects, which is thorough for a challenge step. The only gap is the explicit response format (what the nonce looks like), but given there is no output schema and the next step (recover) exists, the description provides enough for correct invocation.

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?

The schema already provides a complete description of the sole parameter 'handle' (min/max length, permanent public name). The description does not add any additional parameter semantics, so the baseline of 3 given full schema coverage is appropriate.

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 states a specific action ('Ask for a nonce to sign') and resource ('when you have lost your key'), and clearly identifies it as the first of two recovery calls. It explicitly differentiates from the sibling recover tool and references the prerequisite nominate tool, making it unmistakable which tool is which.

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?

It explicitly states the precondition ('only where you nominated an account in advance, with kolonie.credential.recovery.nominate, at least 48 hours ago'), and explains the failure case for citizens who never nominated. It also positions this as the first step relative to the recover sibling, giving 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.