Connect this host to Tailscale

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

Annotations already declare idempotent=true, destructive=false, openWorld=true, and readOnly=false. The description goes well beyond them: non-blocking login behavior, authURL return, headless login via TAILSCALE_AUTH_KEY_FILE, polling until reachable, no elevation needed on Windows, and the success condition state=running. The one gap is timing/rate expectations for the polling phase.

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-loads the one-line purpose before any branching detail, then uses a compact sentence per state, and closes with the success criterion. No sentence is redundant; the parenthetical `tailscale up` disambiguation is worth its length.

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?

An output schema exists, so return-value enumeration is optional, yet the description still names the action enum and the success state. Combined with annotations covering the safety profile, an agent has everything needed to decide to call it and to interpret a non-blocking login result.

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?

The tool takes zero parameters, so the baseline is 4; there are no inputs to disambiguate. The enumerated action values (already_connected | reconnected | needs_login) describe the outcome rather than an input, which adds useful framing but is not 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?

States a specific verb and resource ('Bring this host online on its tailnet (`tailscale up`)') and immediately scopes it ('Connectivity only'), then names the sibling tool that handles the excluded concern (tailscale_set_prefs). An agent can distinguish it from tailscale_disconnect, tailscale_status, and tailscale_set_prefs without opening any 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?

Explicitly routes preference changes to tailscale_set_prefs, and enumerates per-state behavior: already Running returns immediately, Stopped with a valid key does a flag-free up and polls, login-required returns authURL without blocking. This is when-to-use guidance at the level of internal states rather than vague intent.

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