add_ssh_key

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

No annotations are present, so the description carries the full behavioral burden. It does disclose a significant trait the schema cannot express: the key grants root access across all sandboxes. It stops short of stating required permissions/auth scope, what happens on duplicate keys, or whether the operation is idempotent.

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 short clauses, front-loaded with the action and its consequence. The trailing 'HTTP POST /ssh-keys' is endpoint leakage that adds little for an agent, though it does not harm readability.

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 mutation tool with no annotations and no output schema, the description covers purpose and effect but omits permissions needed, duplicate/replace behavior, and what the response returns. Adequate but with clear gaps for a write operation with security impact.

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%: `name` is described in the schema ('Defaults to the key's comment') and `key` carries a format example, so the structured fields do most of the work. The description only says it is a public key, adding no format, encoding, or constraint detail beyond the schema.

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?

States a specific verb and resource ('Add an SSH public key') and immediately qualifies the effect: root SSH access to all sandboxes. That scope statement cleanly separates it from siblings like generate_sandbox_ssh_key or get_sandbox_ssh_key, which operate on a single sandbox's key.

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 use case is implied by 'it lets you into all your sandboxes with SSH as root,' so an agent can infer when this is wanted. However, there is no explicit when-to-use vs when-not guidance and no mention of the alternatives (e.g. generate_sandbox_ssh_key for a per-sandbox key), so half the routing work is left to inference.

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