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

Annotations declare readOnlyHint=false, openWorldHint=false, idempotentHint=false, but the description goes far beyond: it discloses that the call issues a key yet 'moves nothing else,' that the vault does not recover, and that all failures produce identical answers. This adds critical behavioral context about side effects, state changes, and response semantics that the annotations alone do not convey. It also signals the nonce is spent regardless of outcome, reinforcing the non-idempotent nature.

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 bolded section headers and front-loaded purpose ('The second of two calls, and the one that returns a key'). Every paragraph earns its place: one clarifies the signing mechanism, one lists non-effects, one explains vault loss and points to a sibling, and one sets failure expectations. No redundant filler; the length is justified by the complexity of the recovery flow.

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?

For a two-step recovery flow with side effects and no output schema, the description is complete. It covers the required input context (nonce from challenge), what the tool returns (a key), what it does not affect (skills, reputation, etc.), and what it cannot restore (the vault). It even mentions the exact sibling (kolonie.vault.delete) for handling stranded names, leaving no ambiguity about next steps when vault recovery fails.

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 input schema provides 100% coverage, with detailed descriptions for nonce (single-use, spent whether succeeds or fails), handle (citizen being recovered), and signature (base64/base58). The description adds little beyond the schema; it merely reiterates that the nonce comes from the challenge and that the signature uses the private half. Since the schema already documents all semantics, the baseline of 3 is appropriate—this adds minimal supplementary value.

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 unequivocally that this is 'the second of two calls, and the one that returns a key,' with a clear verb-resource pair (recover credentials). It distinguishes itself from the challenge call by referencing it explicitly, and it explains what it does not do ('moves nothing else'). This is fully specific and separates it from siblings like kolonie.credential.recovery.challenge.

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 explicitly places the call in sequence: 'The second of two calls' and refers to the nonce from 'kolonie.credential.recovery.challenge,' making the prerequisite clear. It also names a specific alternative for a related action (kolonie.vault.delete) when vault recovery is impossible, guiding the agent when this tool is not the right choice. The line 'Every way of failing answers identically' also sets expectations for when results are ambiguous.

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