tslink

Overview Schema Source Related Servers Discussions Admin

Invite someone to a device

invite_device

Shares a registered TSLink service device with a person outside the tailnet by emailing a Tailscale invitation, or returns a bearer invite URL instead.

Instructions

Sends a real device-sharing invitation to a real email address outside the tailnet, so confirm the service and address with the user before calling this. It shares one TSLink-owned service device with that person. For an HTTP or file service it also saves their access: a grant this call creates has no expiry (use people_add with for/until to limit it), a grant they already have keeps its deadline, and a binding that expires cannot create a permanent grant, so it gets 24h or a refusal. Set print_link true to receive a bearer invite URL instead of having Tailscale send the email.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "service": "<service>",
      "email": "<email>"
    },
    "name": "invite_device"
  }
}

Input Schema

Name	Required	Description
`email`	Yes	Recipient email address.
`service`	Yes	Exact registered service name whose device is shared.
`multi_use`	No	Allow the invitation to be accepted more than once.
`print_link`	No	Do not send email; return the API-provided invite URL for the user to deliver. Anyone holding that URL can accept.
`allow_exit_node`	No	Allow the recipient to route traffic through the shared device as an exit node. Needs the owner's opt-in (mcp.allow_elevated_invites in config.json); otherwise refused with mcp_elevated_invite_refused.

Output Schema

Name	Required	Description
`id`	No
`kind`	Yes
`role`	No
`email`	No
`grant`	No	Person grant saved by the common access action.
`created`	No
`emailed`	Yes
`message`	No
`service`	No
`accepted`	No
`device_id`	No
`multi_use`	No
`recipient`	No
`invite_url`	No	Bearer invitation URL. Present only when the invite was created with print_link true or when invite_list was called with show_urls true; anyone holding it can accept the invitation.
`target_kind`	No
`access_state`	No
`allow_exit_node`	No
`last_email_sent_at`	No
`remote_side_effect_plan`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.3.0Oct 27, 2026

addedOutput schema / properties / access_state
```
Added value: +{
+  "type": "string"
+}
```

addedOutput schema / properties / grant

Added value: +{
+  "description": "Person grant saved by the common access action.",
+  "type": "object"
+}

addedOutput schema / properties / message
```
Added value: +{
+  "type": "string"
+}
```

changedOutput schema / required

Previous value: -[
-  "kind",
-  "id",
-  "emailed",
-  "remote_side_effect_plan"
-]New value: +[
+  "kind",
+  "emailed",
+  "remote_side_effect_plan"
+]

First observedv0.1.0Oct 19, 2026

TDQS

A4.1/5.0

Behavior5/5

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

Annotations only declare the generic mutation profile (readOnly=false, openWorld=true, idempotent=false); the description adds the genuinely non-obvious effects: a real email leaves the system, a created grant has no expiry, an existing grant keeps its deadline, and an expiring binding yields 24h or a refusal. It also discloses the allow_exit_node config gate, which the annotations do not cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the important warning (a real invitation goes to a real address outside the tailnet) before the mechanics, and every sentence carries information. The middle sentence chains four expiry conditions together and is dense enough to require a second read.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an open-world mutating tool with an output schema available, the description covers the side effects, the grant-expiry semantics, the elevated-permission gate, and the print_link delivery alternative. An agent has everything needed to call it safely without guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters are already documented and the baseline is 3. The description adds some meaning for print_link (a bearer URL anyone holding can accept) and for the expiry consequences of the grant, but the remaining parameters are largely restated from the schema rather than extended.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb+resource: sends a device-sharing invitation to an email address outside the tailnet, for one TSLink-owned service device. It names people_add as the alternative for expiring grants but does not distinguish itself from siblings like invite_user, share, or guest_create, so the sibling routing is incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit precondition ('confirm the service and address with the user before calling this') and points to people_add with for/until when a time-limited grant is wanted. It stops short of stating when to prefer invite_user or share instead, so the alternative landscape is only partly mapped.

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