Create and install an SSH key (blind)

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

With no annotations, the description carries the full behavioral burden and does so well: it discloses local key generation, private-key storage locations (secret store + private agent, or a 0600 file), interactive steps (host-key fingerprint confirmation, optional one-time SSH password), the remote side effect (writing authorized_keys), and a post-install access test. It omits failure/reversibility behavior and required permissions, keeping it short of a 5.

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?

Two sentences, front-loaded with the primary action and ending with the return contract. The procedural clauses are dense but each conveys a distinct step or side effect, so there is little waste; it is packed rather than padded.

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?

There is no output schema, but the description compensates by stating it returns only alias and fingerprints. Given a mutating, interactive tool with no annotations, it covers generation, storage, prompts, installation and verification; only error handling and idempotency are left unaddressed.

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 50%, so the description must compensate, and it partly does: 'secret store + private ssh-agent, or a 0600 file' explains the storage enum, and 'optionally asks them for a one-time SSH password' explains the password flag. The alias parameter remains undocumented in both schema and description, leaving one gap.

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 names a specific verb+resource (generates an ed25519 key, installs the public key in authorized_keys, tests access) and even states the scope of what it returns, so an agent knows exactly what the tool accomplishes. It does not, however, explicitly differentiate itself from sibling tools like ssh_exec or secret_write, which is what separates a 4 from a 5.

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 narrated flow (generate key, confirm host fingerprint, install, test) strongly implies the scenario of provisioning SSH access to a host, but the description never states when to use this over alternatives such as ssh_exec or the secret_* tools, nor any when-not conditions. Usage is only implied.

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