tailscale_delete_tailnet

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

The description adds substantial behavioral context beyond the annotations: irreversibility, exactly which resources are destroyed, the local refusal behavior when confirmTailnet does not match, the typo-guard semantics of confirmTailnet, and the environment-variable based targeting. It also cautions that the tool is UNVERIFIED against a live tailnet, which is valuable risk information. No contradiction with destructiveHint=true.

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 dense but every sentence carries operational weight. The most critical warning—IRREVERSIBLE and what is destroyed—is front-loaded, and the parameter and credential caveats are organized into clear follow-up sentences. The length is justified given the destructive and high-stakes nature of the operation.

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 destructive operation with no output schema, the description covers what the agent needs: the default target, how to override it, the confirmation requirement, the credential limitations, the expected error behavior, and how the tool might be absent entirely due to TAILSCALE_READONLY / TAILSCALE_TOOLS. The description is complete enough to prevent dangerous misinvocation.

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%, so the baseline is 3. The description adds meaningful value to both parameters: it explains that tailnet may be an id from tailscale_list_org_tailnets, and it clarifies the confirmTailnet guard's actual limitations—that on the explicit-tailnet path it proves only self-agreement rather than authorization. This goes beyond the schema's descriptions, though the schema already covers the literal mechanics.

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: 'Permanently delete a tailnet.' It immediately distinguishes this from the many sibling delete tools by stating the resource scope and the irreversible removal of devices, users, ACLs, and keys. The title 'Delete tailnet' is reinforced with precise details rather than merely restated.

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 description gives explicit selection guidance: it targets the configured tailnet by default, and names tailscale_list_org_tailnets as the source for an alternative explicit tailnet. It also states the intended use case—tearing down API-only tailnets created by tailscale_create_org_tailnet—and warns about credential scoping and expected 403/404 failures for unreachable tailnets.

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