ssh_key_update

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the operation is an update and returns updated SSH key information, but it doesn't disclose whether the update is partial or full replacement, whether the ssh_key must be a valid public key format, whether the operation is idempotent, or any side effects like invalidating existing connections. The 'ctx' parameter hints at resource change notifications but the description doesn't explain what that means for the caller.

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 compact and front-loaded with the core purpose. The Args section is well-organized and each parameter gets a brief explanation. The Returns line is useful. Minor waste: the ctx parameter description is vague and the docstring format is slightly redundant with the schema, but overall it's efficient.

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?

The tool has an output schema, so return values are covered. The description covers the required parameter and both optional parameters. However, for a mutation tool with no annotations, it lacks important context: no mention of prerequisites (key must exist), no error conditions (invalid key ID, invalid public key format), no side effects (does updating the key break existing SSH sessions?), and no guidance on whether both optional fields can be updated in one call. The sibling list shows ssh_key_get and ssh_key_list exist, so the description could have referenced them for lookup before update.

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 0%, so the description must compensate. It does explain ssh_key_id (ID or name with example), name (new name, optional), and ssh_key (new public key, optional), which adds meaning beyond the bare schema. However, it doesn't clarify the format of the ssh_key parameter (e.g., OpenSSH format, key type), whether name and ssh_key can be updated independently or together, or what happens if both are omitted. The ctx parameter is mentioned but not explained in terms of how the caller should use it.

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 clearly states the verb 'Update' and the resource 'an existing SSH key', which distinguishes it from ssh_key_create and ssh_key_delete. It also lists the updatable fields (name, ssh_key), making the tool's purpose unambiguous. However, it doesn't explicitly differentiate from ssh_key_get or ssh_key_list, though the verb 'update' makes that distinction obvious.

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 implies usage context: you need an existing SSH key ID and can optionally provide a new name or public key. It doesn't explicitly state when to use this tool versus alternatives like ssh_key_create (for new keys) or ssh_key_delete (for removal), but the sibling names and the 'Update' verb make the primary use case clear. No explicit exclusions or alternative routing guidance is provided.

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