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

Annotations already declare destructiveHint=true and openWorldHint=true, so the safety profile is covered, but the description goes beyond them: down 'leaves the tailnet at once' (immediate destructive effect) and authKeySecret warns to use an ephemeral key because 'a reusable one lets the sandbox log in again by itself after a long pause' — a real persistence/security trait. Missing only permission/reversibility detail.

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?

Front-loaded with a one-sentence summary of the resource, then a compact per-action map. Minor inefficiency from the 'Paid sandboxes.' fragment and some phrasing overlap, but no filler and every clause carries operational meaning.

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 multiplexed, destructive, no-output-schema tool this is close to sufficient: each action's effect, the key mechanism, and the immediate leave-on-down behavior are stated. It could say a bit more about what status returns and any permission requirements, but nothing critical for correct invocation is absent.

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 60% and the description adds meaning the flat schema lacks by mapping parameters to actions — up(id, authKeySecret?, hostname?, tags?) versus status(id) and down(id). It also clarifies authKeySecret names a job secret and carries the ephemeral-key caveat, exceeding the schema's own text.

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 resource (a sandbox's Tailscale network membership) and enumerates the three operations: join with an auth key, view tailnet addresses, or remove the machine. Each action verb is explicit, so an agent can tell this apart from generic network siblings like runtime_sandboxes_network or runtime_networks_wireguard without opening a schema.

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 per-action breakdown (up/status/down) implies when each sub-operation applies, and 'Paid sandboxes' is a useful eligibility constraint for up. However, there is no explicit when-not guidance, no prerequisites, and no routing to alternative network tools for an agent unsure whether this is the right tool.

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