tslink

Overview Schema Source Related Servers Discussions Admin

Update a person's app access

people_update

Destructive

Modify an existing person's app access on your Tailscale network: replace app grants, adjust access deadlines, or refresh invitations while preserving current permissions.

Instructions

Replace an existing person's app set when apps is supplied; omission preserves grants. Only explicit for/until changes existing deadlines. Uses the same membership, gateway routing and invitation completion as people_add. Retrying without lifetime changes resumes transport work. Removed apps remain denied. never requires ack_never; public/browser access stays finite. Requires owner authority for new routes or device sharing. Bearer links stay hidden unless print_links is true; invite is a compatibility field with no effect. Unknown POSTs require owner-verified reconcile_invites; replace_invites binds replacement to the recorded ID and preserves deadlines.

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": {
      "who": "<who>"
    },
    "name": "people_update"
  }
}

Input Schema

Name	Required	Description
`qr`	No	Return QR payload text only; never image bytes.
`for`	No	Relative lifetime (descending unique units w,d,h,m,s,ms,us,ns) or until <RFC3339\|YYYY-MM-DD\|YYYY-MM-DDTHH:MM>. Local unless offset given; DST gaps/folds require an offset. Minimum 1h. Presets: 1h, 8h, 24h, 3d, 7d. New grants default to 24h; update omission preserves deadlines. Never requires ack_never for members and device-invited guests; finite guest grants retain the configured maximum.
`who`	Yes
`apps`	No	App names, or [all] for all current private HTTP/file apps. Required on add; omission on update keeps the app set.
`until`	No	Absolute deadline (RFC3339, YYYY-MM-DD, YYYY-MM-DDTHH:MM); conflicts with for.
`invite`	No	Compatibility field; necessary invitations are automatic.
`ack_never`	No
`qr_invite`	No	App invitation QR or @gateway; requires qr and print_links. Treat as a credential.
`print_links`	No
`replace_invites`	No	Update without apps/for: owner-confirmed app or @gateway to recorded old invite ID. Requires remote absence for the same NodeID. A stale gateway invitation can be retired as target_gone when current gateway ownership is proven, including accepted shares; preserves grants and deadlines.
`reconcile_invites`	No	Update: owner-verified app or @gateway to invite ID mapping, or none after checking absence. Unknown POSTs cannot be retried blindly.

Output Schema

Name	Required	Description
`guide`	No
`access`	No
`person`	Yes
`portal`	No	Independent home portal configuration and exact runtime address when available.
`invites`	Yes
`message`	Yes
`complete`	Yes
`guide_zh`	No
`warnings`	No
`membership`	No
`qr_payload`	No
`qr_warning`	No
`invite_requirement`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed8 schema fields changedv0.3.0Oct 27, 2026

removedInput schema / anyOf

Removed value: -[
-  {
-    "properties": {
-      "qr": {
-        "const": true
-      }
-    },
-    "required": [
-      "qr"
-    ]
-  },
-  {
-    "required": [
-      "apps"
-    ]
-  },
-  {
-    "required": [
-      "for"
-    ]
-  },
-  {
-    "required": [
-      "until"
-    ]
-  },
-  {
-    "properties": {
-      "invite": {
-        "const": true
-      }
-    },
-    "required": [
-      "invite"
-    ]
-  }
-]

changedInput schema / properties / for / description

Previous value: -"Relative lifetime (descending unique units w,d,h,m,s,ms,us,ns) or until <RFC3339|YYYY-MM-DD|YYYY-MM-DDTHH:MM>. Local unless offset given; DST gaps/folds require an offset. Minimum 1h. Presets: 1h, 8h, 24h, 3d, 7d. New grants default to 24h; update omission preserves deadlines. Never requires ack_never and a tailnet-member login; device-invited guests have the configured public maximum."New value: +"Relative lifetime (descending unique units w,d,h,m,s,ms,us,ns) or until <RFC3339|YYYY-MM-DD|YYYY-MM-DDTHH:MM>. Local unless offset given; DST gaps/folds require an offset. Minimum 1h. Presets: 1h, 8h, 24h, 3d, 7d. New grants default to 24h; update omission preserves deadlines. Never requires ack_never for members and device-invited guests; finite guest grants retain the configured maximum."

removedInput schema / properties / invite / default
```
Removed value: -false
```

addedInput schema / properties / invite / description

Added value: +"Compatibility field; necessary invitations are automatic."

changedInput schema / properties / reconcile_invites / description

Previous value: -"Update --invite only: owner-verified app or @gateway to invite ID mapping, or none after checking absence. Unknown POSTs cannot be retried blindly."New value: +"Update: owner-verified app or @gateway to invite ID mapping, or none after checking absence. Unknown POSTs cannot be retried blindly."

changedInput schema / properties / replace_invites / description

Previous value: -"Update with invite only, no apps/for: owner-confirmed app or @gateway to recorded old invite ID. Requires remote absence for the same NodeID. A stale gateway invitation can be retired as target_gone when current gateway ownership is proven, including accepted shares; preserves grants and deadlines."New value: +"Update without apps/for: owner-confirmed app or @gateway to recorded old invite ID. Requires remote absence for the same NodeID. A stale gateway invitation can be retired as target_gone when current gateway ownership is proven, including accepted shares; preserves grants and deadlines."

addedOutput schema / properties / access

Added value: +{
+  "items": {
+    "additionalProperties": false,
+    "properties": {
+      "access_state": {
+        "type": "string"
+      },
+      "app": {
+        "type": "string"
+      },
+      "message": {
+        "type": "string"
+      },
+      "url": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "app",
+      "access_state",
+      "message"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

addedOutput schema / properties / membership

Added value: +{
+  "enum": [
+    "member",
+    "non_member"
+  ],
+  "type": "string"
+}

First observedv0.1.0Oct 19, 2026

TDQS

A4.4/5.0

Behavior5/5

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

The description adds substantial behavior beyond the annotations: replacement semantics, deadline preservation, retry behavior, denied removed apps, owner authority requirements, hidden bearer links, compatibility of invite, and reconcile requirements for unknown POSTs. These details align with destructive=true and non-idempotent hints and materially help an agent avoid unsafe calls.

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?

The description is front-loaded with the core update semantics and every sentence contains relevant technical detail. It is dense and semicolon-heavy, which reduces readability slightly, but given the complexity it remains appropriately sized.

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

Completeness4/5

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

For a complex, destructive, open-world update tool with an output schema, the description covers most behavioral and operational concerns. A minor gap is that the required who identifier is not explained in the description, and some schema-described parameters like qr are only indirectly referenced.

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

Parameters5/5

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

Despite 73% schema coverage, the description adds important semantics for multiple parameters: apps replacement vs. omission, for/until deadline behavior, print_links visibility, invite having no effect, ack_never not being required, and the owner-verified nature of reconcile_invites/replace_invites. It meaningfully supplements the schema rather than repeating it.

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?

The description states a specific verb and resource: updating an existing person's app set, with clear replacement vs. preservation semantics. It distinguishes itself from people_add by describing update-specific behavior, though it does not explicitly contrast with people_grant or people_revoke.

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?

It gives clear usage conditions: supply apps to replace the app set, omit apps to preserve grants, and use explicit for/until to change deadlines. It references people_add for shared behavior but does not fully route the agent among sibling tools such as people_grant or people_revoke.

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