Disconnect this host from Tailscale

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

Annotations only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the description goes well beyond, disclosing that login is preserved, the operation is fully reversible, the node key does not expire, and that connectivity is interrupted for every user on the machine (hence approval). It also states the success condition (state=stopped) and the possible action values.

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?

Dense but front-loaded: the core action comes first, then the disambiguation clauses, then the approval and success criteria. Every clause carries distinct information and nothing is redundant with the annotations.

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 annotations plus a full output schema, this is complete: reversibility, sibling routing, approval need, and success signal are all present. No pagination/auth/return-format gaps remain.

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 100% and there is a single optional parameter, so the schema already documents `reason` fully. The description adds no parameter-level detail, but the baseline of 3 applies when the schema carries the burden.

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 ('Disconnect this host') and immediately names the underlying command (`tailscale down`). It explicitly contrasts with both siblings an agent could confuse it with: tailscale_connect (reversal) and tailscale_logout (node key expiry).

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?

Gives explicit when-to-use-this vs when-to-use-the-alternative: use tailscale_logout if you want to expire the node key, use tailscale_connect to undo. Also flags the approval requirement, which is a real gate on invocation.

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