Add device

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

Annotations provide only readOnlyHint=false, but the description goes further: it states the device is created immediately, a WireGuard tunnel file is saved per location with a locally generated private key, the key is never shown in replies, and linux_machine devices self-register and can later be moved/rotated. It also discloses the device-slot consumption and the admin token need. This is thorough disclosure beyond annotations with no contradiction.

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 somewhat long but every clause earns its place—two device kinds, file handling, key security, device-slot cost, and token requirement. It is logically organized by kind, with prerequisites and outcomes stated clearly. Not overly terse, but justified by the tool's complexity.

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 description covers the essential operational facts: what each kind produces (files vs. commands), the key generation and privacy, the view-only constraint for phone_or_computer, and the admin token requirement. It omits the exact return shape, but since no output schema exists, a brief note on the return (e.g., the commands or success message) would have been slightly more complete. Still, it covers the critical usage context.

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?

Although schema coverage is 100%, the description enriches each parameter: it maps 'kind' to concrete device types, explains 'folder' as the save location with a default, clarifies 'split_tunnel' behavior (keeps SSH for remote servers), and defines 'temporary_minutes' with automatic deletion semantics. This adds meaning the schema alone doesn't convey.

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 opens with a specific verb and resource ('Add a new device to the account') and then splits into two clearly defined kinds ('phone_or_computer' and 'linux_machine') with distinct behaviors, outcomes, and prerequisites. This distinguishes it from sibling tools like move_device or rotate_device, which address different lifecycle operations.

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?

It gives explicit conditions for each kind: phone_or_computer for WireGuard apps on mobile/desktop, linux_machine for servers or agent machines. It also notes the admin-scope token requirement and that these devices are view-only until switched. It doesn't explicitly name alternatives like update_device or remove_device, but the use context for this creation tool is clear and actionable.

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