remove_user_ssh_key

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

The description simply restates the action without adding behavioral context beyond annotations. Annotations already mark it destructive and idempotent. The description doesn't disclose irreversibility, permissions, or effects on user access.

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?

One short sentence with no wasted words. It is appropriately concise for a simple action, though it could be more informative without becoming verbose.

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 simple operation and existing annotations, the description is under-specified. It lacks context about finding key_id, whether the removal affects active sessions, or any prerequisites. The output schema exists, so return values aren't needed, but the description is still minimal.

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 has no property descriptions (0% coverage), and the description does not explain key_id or device. The agent must infer meaning from property names alone. The description adds no parameter semantics.

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 uses a specific verb ('Removes') and resource ('SSH key'), clearly identifying the action. It aligns with the tool name and distinguishes from sibling tools like list_user_ssh_keys and set_user_ssh_keys. However, it lacks explicit scoping (whose key, from where), so not 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?

No guidance on when to use this tool versus alternatives. It doesn't mention using list_user_ssh_keys to find key_id or that this is the removal counterpart to set_user_ssh_keys. No context or exclusions are provided.

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