Tailscale MCP by usefulapi

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

The annotation already flags destructiveHint=true, so the agent knows this is a state-changing call. The description adds the approval-mode precondition and reveals the endpoint is dual-purpose (authorize and de-authorize via one boolean), but it never states the consequence of de-authorizing (loss of tailnet access) or any permission requirements.

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?

Two sentences, zero filler: the behavior and its precondition come first, with the endpoint reference trailing. Nothing could be removed without losing information.

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 simple two-parameter mutation with a fully documented schema and an annotation covering the destructive aspect, the description is nearly sufficient. Only the effect of the authorized=false branch and the returned result are left unstated, which is a minor gap given no output schema exists.

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 description coverage is 100%, and both parameters (deviceId, authorized) are fully documented in the schema, so the baseline is 3. The description adds no syntax or format detail beyond what the schema already provides.

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 states a specific verb pair (authorize/de-authorize) and its resource (device), plus the exact REST endpoint, so the operation is unambiguous. It does not name a sibling tool, but 'authorize' is inherently distinct from delete_device, set_device_name, and expire_device_key in the sibling set.

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?

It supplies a clear precondition: the tool is only relevant when device approval is enabled for the tailnet, which tells an agent when this call matters versus not. It stops short of naming an alternative tool or explaining what to do in non-approval tailnets, so it is clear context without explicit exclusions.

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

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

Annotations supply only destructiveHint=true, and the description adds the underlying REST call (POST /tailnet/{tailnet}/keys) without contradicting them. It does not disclose the practically important traits of a key-creation call: that the key secret is typically shown only once, the OAuth scope required, or rate limits. Useful but thin given annotations cover little.

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?

Two short sentences, front-loaded with the action and resource, and the REST endpoint is tucked at the end. No filler and nothing redundant.

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 six-parameter mutation tool with no output schema, the description covers the what but omits the critical return behavior — the newly minted key/secret — as well as permission prerequisites. Since no output schema exists, the description is the only place that could explain what the caller receives.

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 description coverage is 100%, with all six parameters (tags, reusable, ephemeral, description, expirySeconds, preauthorized) documented in the schema itself, so the baseline is 3. The description adds no parameter syntax, defaults, or interaction detail beyond what the schema already provides.

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 ('Create a new auth key for the tailnet') and adds the business purpose (registering new devices). It is clearly distinguishable from list_keys/get_key/delete_key siblings by verb, though it never names a sibling it is not.

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?

There is no when-to-use vs when-not guidance. The parenthetical 'used to register new devices' hints at context but does not route the agent among alternatives such as list_keys (to inspect existing keys) or delete_key/expire_device_key.

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

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

Annotations already declare destructiveHint=true, so the destructive nature is covered. The description adds useful consequence detail ('removing it from the tailnet'), but says nothing about irreversibility, what else is torn down (routes, keys, tags), or permission requirements.

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?

Two short, front-loaded sentences with no filler; the effect statement comes before the REST mapping. The endpoint line is mildly redundant but useful for mapping to the API.

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 single-parameter destructive tool with no output schema, the description covers purpose and effect adequately, but omits irreversibility and permission expectations that an agent should know before invoking a delete.

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 description coverage is 100% and the single parameter is self-explanatory ('The device id to delete'). The description's REST path template mirrors deviceId without adding format or sourcing detail, so the baseline 3 applies.

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 ('Delete a device') plus the concrete effect ('removing it from the tailnet'), so the agent knows exactly what happens. It does not explicitly differentiate from near-neighbors like tailscale_expire_device_key or tailscale_delete_key, but the resource noun makes the target unambiguous.

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?

No guidance on when to delete a device versus alternatives such as expiring its key or authorizing/deauthorizing it, and no prerequisites (offline requirements, admin scope) are stated. Usage is only implied by the verb.

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

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

Annotations already declare destructiveHint=true, so the safety profile is largely covered. The description adds that this is a revoke operation tied to a security response and cites the REST endpoint, but it does not say whether revocation kills active sessions, whether it is reversible, or what permissions the caller needs.

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?

Two tight clauses: the semantic action and scope come first, with the REST pointer as a trailing reference. No filler, nothing repeated.

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 one-parameter delete tool with destructiveHint already set and no output schema, this is close to sufficient. The only missing piece an agent might want is whether deletion is permanent and whether other tools should be preferred instead.

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 description coverage is 100%, so the single keyId parameter is already fully documented. The description's 'by id' phrasing aligns with the schema but adds no format, prefix, or syntax detail beyond it.

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+resource ('Delete (revoke) an auth key or API access token by id') and even names the underlying REST operation, so an agent can distinguish it from siblings like tailscale_expire_device_key or tailscale_delete_device without opening the 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?

The phrase 'a security response' hints at the context in which this tool is used, but it never states explicit when-to-use vs. when-not conditions, nor does it name tailscale_expire_device_key as the alternative for softer key invalidation. Usage is only implied.

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

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

Annotations already declare destructiveHint=true, so the safety profile is covered. The description usefully adds what the destruction actually means — the node key is invalidated and the device must re-authenticate — which is behavioral detail beyond the annotation, though it omits whether the device entry/data survives.

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?

Two tight clauses with the core action and the motivating scenario front-loaded, followed by the endpoint reference. No filler.

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 single-parameter mutation with no output schema and destructiveHint already set, the description supplies the action, the rationale, and the endpoint. It leaves the device-id format and post-expiry state unstated, a minor gap.

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?

Only one parameter (deviceId) with 100% schema description coverage, so the schema already carries the semantics. The description references deviceId only implicitly via the REST path and adds no format or sourcing detail, so baseline 3 applies.

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 (expire) and resource (device's node key), plus the concrete consequence (forces re-authentication). This clearly separates it from siblings like tailscale_delete_device or tailscale_delete_key, which have different destructive semantics.

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 frames the use case: 'a security response to a compromised or lost device.' That is clear context for when to reach for this tool, but it does not name the alternative actions (delete device vs. delete key) or state when not to use it.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered by structured data. The description adds only the REST endpoint mapping (GET /device/{deviceId}), with no note on error behavior for an unknown id, rate limits, or what a device record contains.

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?

Two short sentences with zero filler, front-loading the action and following with the endpoint mapping. Nothing is redundant or padded.

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 simple single-resource read with full schema coverage and readOnly annotations, the description covers what an agent needs to invoke it. It could optionally mention return shape, but with no output schema and a trivial GET, this is a minor gap.

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 description coverage is 100%, and the only real semantic nuance — that 'fields=all' includes posture attributes and routes while 'default' is a subset — is already documented in the schema. The description adds nothing about parameters, so the baseline 3 applies.

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 ('Get a single device by id') and adds the underlying REST call, which pins down exactly what is fetched. It is distinguishable from list_devices and its other siblings by the 'single device' + id framing, but it never names a sibling explicitly.

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?

There is no when-to-use guidance, no stated prerequisites, and no mention of alternatives such as tailscale_list_devices or the device-mutating siblings. The requirement of a deviceId only implicitly suggests usage.

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

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

The readOnlyHint annotation already establishes this is a safe, non-mutating read. The description adds modest value by naming the concrete settings covered (MagicDNS) and the underlying REST endpoint, but says nothing about return shape, tailnet scoping requirements, or access/auth constraints beyond what annotations provide.

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?

Two short sentences with the purpose front-loaded and no filler. The trailing REST endpoint mapping is borderline, but it is compact and adds a locator for the underlying resource.

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 parameterless, read-only getter with no output schema, the description gives the resource, an example of the returned content, and the API path it wraps. Nothing an agent needs to invoke it correctly is missing.

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 there is nothing for the description to disambiguate; the baseline for a parameterless tool applies.

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 ('Get the tailnet's DNS preferences') and clarifies scope with an example field (MagicDNS). It does not, however, distinguish itself from DNS-adjacent siblings such as tailscale_get_split_dns, tailscale_list_dns_nameservers, or tailscale_list_dns_searchpaths, so the sibling differentiation bar for a 5 is unmet.

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?

There is no explicit guidance on when to call this versus the other DNS tools in the sibling set. The REST endpoint mapping hints at scope but is not usage guidance, and no exclusions or preconditions are offered.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds value beyond that by disclosing the concrete return facets (capabilities, expiry, usage) and pinning the exact REST call GET /tailnet/{tailnet}/keys/{keyId}, which no structured field provides.

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?

One sentence, zero filler, purpose front-loaded before the endpoint reference. Nothing is repeated from structured fields and every clause earns its place.

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 one-parameter read-only lookup with no output schema, the description covers purpose, identifier, return facets, and the underlying endpoint. Minor gaps remain (error behavior for an invalid/expired keyId, expected auth scope), but nothing essential for calling it correctly is missing.

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% with a single documented keyId, so the schema carries the parameter burden. The description's 'by id' restates that without adding format, source, or format examples, matching the baseline-3 case where the schema does the heavy lifting.

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 (Get) and resource (a single auth key / API access token) and clarifies it is a by-id single-record fetch, which distinguishes it from tailscale_list_keys. It also names the returned facets (capabilities, expiry, usage) so the agent knows what the call produces.

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?

Usage is only implied: 'by id' signals that a keyId (presumably from tailscale_list_keys) is a prerequisite, and 'single' contrasts with the list variant. There is no explicit when-to-use/when-not statement or named alternative, so guidance stays at the implied level.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description nonetheless adds a genuinely useful behavioral detail absent from structured data: the response is JSON via the Accept header, not HuJSON, which affects how an agent parses the result. It omits auth scope requirements and any rate-limit or caching behavior.

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?

Two tight sentences: the purpose and output format come first, and the raw endpoint reference is a compact trailing clause. Nothing is redundant or padded.

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?

With no output schema, the description usefully discloses the response encoding (JSON rather than HuJSON), which is exactly the kind of return-value context an agent needs. What is missing is permission/scope expectations and any note that the endpoint may fail for tailnets without ACLs.

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 description coverage is 100% with a single optional 'details' flag, so the schema already explains the parameter fully. The description says nothing about the parameter, so it adds no meaning beyond the schema — the baseline 3 for high coverage applies.

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 (Get) and resource (the tailnet's ACL/policy file) and even names the underlying REST endpoint GET /tailnet/{tailnet}/acl. No sibling tool touches policy files, so the agent can distinguish it immediately.

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?

Usage is implied by the read-only 'Get' framing and the REST endpoint mapping, but there is no explicit when-to-use or when-not-to-use guidance, nor any note about what to do if the policy is empty or access-restricted. No sibling alternative exists to route to, which limits how much guidance is feasible.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description goes beyond that by disclosing the return structure (a domain → nameserver map) and the underlying REST endpoint, which is genuinely useful given there is no output schema. It does not mention auth requirements or tailnet scoping rules.

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?

Two compact clauses: the purpose/return shape is front-loaded, and the REST endpoint reference is tucked behind an em dash. Every element earns its place with no redundancy.

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 zero-parameter, read-only tool with no output schema, the description supplies the essential missing piece — what the return value looks like — plus an endpoint reference. Only minor details (auth scope, empty-config behavior) are absent.

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. The description has no parameters to explain and correctly does not pad the text with parameter commentary.

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 ('Get') and a precise resource ('the tailnet's split-DNS configuration'), then clarifies the return shape as a domain → nameservers map. This distinguishes it from siblings like get_dns_preferences, list_dns_nameservers, and list_dns_searchpaths without ambiguity.

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?

Usage is implied by the resource name — an agent will read this when it needs the split-DNS config — but the description never states when to prefer it over get_dns_preferences or the list_dns_* siblings, nor does it mention prerequisites or exclusions.

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

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

The readOnlyHint=true annotation already establishes the safety profile, so the description only needs to add context. It supplies the REST mapping (GET /tailnet/{tailnet}/settings), confirming a pure read of a single tailnet-scoped resource, but says nothing about auth/permission requirements or the shape/size of the returned settings object.

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?

Two short sentences with the core purpose front-loaded and the REST endpoint appended as a compact implementation reference. No filler, no restatement of the title, every clause carries information.

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 zero-parameter, read-only getter with no output schema, the description covers what the tool returns at a category level and how it is invoked. The main residual gap is that the returned settings structure is not characterized at all, which matters slightly since no output schema exists to fill that in.

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 and there are no argument semantics to add. The description's mention of {tailnet} in the endpoint path implies a tailnet-scoping context that the empty schema does not express, which is a small bonus but not a substitute for real parameter documentation.

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 (Get) and resource (the tailnet's settings), and the parenthetical enumeration of setting categories (device approval, key expiry, posture) tells the agent this is broader than the narrower tailnet-scoped siblings like tailscale_get_dns_preferences or tailscale_get_policy_file. It stops short of explicitly naming those siblings, so it is clear but not maximally differentiated.

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?

There is no explicit when-to-use statement, prerequisite, or named alternative. Usage is only implied by the scope hint ('the tailnet's settings') and the enumerated categories, which lets an agent infer this is the tool for tailnet-wide policy/approval configuration rather than device or DNS lookups, but nothing is stated outright.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds only the REST mapping (GET /users/{userId}), which is minor surface detail; it says nothing about permissions/scopes, error behavior for unknown ids, or rate limits.

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?

Two short sentences, zero filler, with the action and lookup key front-loaded. Every element earns its place.

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 single-parameter read tool with full schema coverage and a readOnlyHint annotation, this is nearly complete. The only unstated item is which auth/scope is required, which is a minor gap given no output schema exists to explain.

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% for the single userId parameter, so the schema already documents it fully. The description repeats 'by id' without adding format, source, or acquisition guidance, so baseline 3 applies.

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 ('Get a single user by id'), which clearly distinguishes it by implication from the sibling tailscale_list_users. It does not explicitly name the sibling or contrast them, so it stops short of a 5.

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 phrase 'by id' implies the lookup scenario, but there is no explicit when-to-use guidance, no statement of alternatives (e.g. use list_users to enumerate), and no prerequisites. Usage is only inferable.

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

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

readOnlyHint=true already tells the agent this is a safe read, so the bar is lower. The description adds useful substance by distinguishing advertised routes from enabled routes and mapping to GET /device/{deviceId}/routes, but omits any mention of pagination, response shape, or required permissions.

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?

Two tight sentences with the purpose front-loaded and the endpoint mapping as a compact secondary clause. Nothing is redundant or padded.

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 one-parameter read-only tool with full schema coverage and no output schema, the definition covers what the tool returns at a conceptual level (advertised and enabled routes). Only minor gaps remain, such as whether the device must be authorized or online for routes to appear.

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% for the single deviceId parameter, so the schema already documents it. The description reinforces the parameter's role via the REST path {deviceId} but adds no format or sourcing guidance beyond that, making the baseline 3 appropriate.

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 (List) and resource (subnet routes a device advertises) with the scope clarified as advertised vs enabled routes. It does not explicitly name the sibling tailscale_set_device_routes, leaving the agent to infer the read/write distinction from the verb alone.

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?

No when-to-use guidance, prerequisites, or named alternatives. The description never says to pair this with tailscale_set_device_routes for changes or tailscale_get_device for broader device info, so selection relies entirely on the tool name.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds real value by enumerating the returned fields (name, addresses, OS, last seen, tags) and mapping to the underlying REST call, but omits pagination/result-size behavior, which matters for a full-tailnet listing.

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?

Two short sentences, front-loaded with the core action and scope, then the field list. The REST endpoint reference is mildly extraneous for an agent but costs little; nothing is padded.

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?

With a fully covered single-parameter schema and no output schema, the description usefully compensates by naming the returned fields. The remaining gap is the absence of any note on result volume/pagination for what is by definition a full-tailnet listing.

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 description coverage is 100%, so the single 'fields' enum parameter is already fully documented in the schema, including the 'all' vs 'default' semantics. The description mentions returned fields but never references the 'fields' parameter, adding nothing beyond the schema. Baseline 3 applies.

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 ("List all devices in the tailnet") and even enumerates the returned fields, so the agent knows exactly what it gets. It distinguishes itself implicitly from tailscale_get_device (singular) via "all devices," but never names the sibling explicitly.

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?

Usage is implied by "List all devices in the tailnet" — an agent can infer this is the bulk-read tool versus tailscale_get_device for one device. There is no explicit when-to-use statement, no mention of when to prefer tailscale_list_device_routes or filtering options, and no prerequisites called out.

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

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

Annotations already declare readOnlyHint=true, so the safe-read profile is covered. The description adds the underlying REST endpoint (GET /tailnet/{tailnet}/dns/nameservers), which confirms the read nature but supplies no rate limits, auth requirements, or scoping caveats beyond what the annotation already conveys.

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?

Two tight sentences with zero filler: the operation and scope come first, followed by API provenance. Nothing is redundant and nothing needs trimming.

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 parameterless read-only list tool with no output schema, the description covers what the tool does and where it maps in the API. It stops short of describing the shape of the returned nameserver list, a minor gap given the simplicity of the operation.

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 there is nothing for the description to disambiguate. Baseline of 4 applies; the description adds no parameter detail because none is needed.

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 (List) and resource (global DNS nameservers for the tailnet), which is distinct from sibling tools like list_dns_searchpaths and get_split_dns. It does not explicitly name those siblings to differentiate, so it lands just short of a 5.

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?

No when-to-use, when-not-to-use, or alternative guidance is given. The agent must infer from the resource name alone that this covers global nameservers rather than search paths, split DNS, or DNS preferences — all of which are available as siblings.

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

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

The readOnlyHint=true annotation already establishes the safety profile, so the bar is lower. The description adds the underlying REST mapping (GET /tailnet/{tailnet}/dns/searchpaths), which is reference context but discloses no additional behavior such as return format or scope constraints.

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?

Two short sentences, purpose front-loaded, no filler. The REST reference is compact and the entire definition is tight.

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 zero-parameter, read-only list tool with no output schema, the description covers what an agent needs to select and invoke it. Return-shape detail is absent but is a minor omission given the tool's simplicity and annotation coverage.

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?

With zero parameters, the baseline is 4. There is nothing for the description to document, and the {tailnet} placeholder in the URL is organizational rather than an agent-supplied parameter.

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 (List) and resource (DNS search paths) scoped to the tailnet, with a clarifying parenthetical ('search domains') that disambiguates from the sibling tailscale_list_dns_nameservers. It does not explicitly name siblings, so it falls just short of a 5.

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?

There is no explicit when-to-use or when-not-to-use guidance and no mention of alternatives like tailscale_get_dns_preferences or tailscale_get_split_dns. Usage is only implied by the purpose for this simple read-only listing, which is the minimum viable level.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered. The description adds the underlying REST call (GET /tailnet/{tailnet}/keys), which is useful provenance, but says nothing about ordering, pagination, or the scope requirement needed to see other users' keys beyond what the schema already notes.

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?

Two short sentences with no filler; the core capability is stated first and the REST reference trails as supporting detail. Nothing could be removed without losing information.

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 read-only list tool with a single optional boolean, no output schema, and annotations covering safety, the description plus schema is nearly sufficient. Only the relationship to the sibling get/create/delete key tools is missing, which is a minor gap.

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?

With 1 optional parameter at 100% schema description coverage, the schema fully documents the 'all' flag including its scope caveat and default. The description contributes no additional parameter meaning, so the baseline of 3 applies.

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?

A specific verb (List) plus a well-defined resource (auth keys and API access tokens for the tailnet), and the REST endpoint mapping pins the exact operation. It is distinguishable from siblings like tailscale_get_key (singular fetch) and tailscale_create_auth_key (mutation), though it never names them explicitly.

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?

There is no statement of when to choose this tool over tailscale_get_key or how it relates to tailscale_create_auth_key/tailscale_delete_key. The only hint of usage is the scoping concept embodied in the 'all' parameter, and that lives in the schema rather than the description. Implied usage at best.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered by structured data and the bar is lower. The description adds the REST endpoint reference, which is useful orienting context, but says nothing about pagination, result limits, or required auth scope for a listing operation.

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?

Two compact sentences, front-loaded with what is listed and followed by the filtering scope and API mapping. Nothing is redundant and nothing wastes space.

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 simple read-only list tool with zero required parameters, full schema coverage and no output schema, the description covers purpose, scope and API mapping adequately. Only minor gaps remain, such as whether the default return is filtered or complete and any result-size caveats.

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 description coverage is 100% and two of the three parameters carry enums with documented values, so the schema does the heavy lifting. The description only restates the filterable fields (type, role, status) already enumerated in the schema, adding no syntax or combination semantics beyond it.

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 gives a specific verb and resource ('List users of the tailnet') plus the scope of optional filtering by type, role or status, and even maps to the underlying REST endpoint. It is clearly distinguishable from tailscale_get_user (singular) and tailscale_list_devices, though it never names a sibling explicitly, which keeps it just short of a 5.

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 presence of filter parameters and the 'optionally filtered' phrasing implies when the tool is useful (enumerating the tailnet's user base with narrowing), but there is no explicit when-to-use guidance and no statement of when an alternative such as tailscale_get_user would be preferred. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, so the safety profile is covered structurally. The description adds the REST endpoint mapping, which is useful corroborating context, but says nothing about pagination, result volume, or the shape of the returned webhook list.

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?

Two short sentences, zero filler, with the purpose front-loaded before the API reference. Every sentence earns its place.

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 zero-parameter read-only list tool with annotations covering safety, this is nearly complete. The only gap is that with no output schema present, the description could say what the returned webhook records look like or whether results are paginated.

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 there is no parameter semantics to explain; baseline is 4. The description correctly implies the tailnet is resolved from context rather than passed as an argument.

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 (List) and resource (webhook endpoints) scoped to the tailnet, and even names the backing REST endpoint (GET /tailnet/{tailnet}/webhooks), so the operation is unambiguous. It does not explicitly distinguish itself from any sibling, though no other webhook tool exists to confuse it with.

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?

No guidance on when to use this versus alternatives, no prerequisites, and no exclusions. The usage is implied by the tool name, but the description itself supplies no routing context.

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

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

Only destructiveHint=true is annotated, so the description carries more burden than a fully-annotated tool. It adds the underlying REST mapping (POST /device/{deviceId}/name), which is useful context, but says nothing about required permissions, whether the rename affects DNS name/machine identity, or its reversibility.

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?

Two short sentences, front-loaded with the action and its clarifying synonym. The REST endpoint sentence is marginal but small enough not to be bloat.

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 simple two-parameter rename with full schema coverage and no output schema, the essentials are present. However, the destructive hint is never explained (what a rename disrupts, permission needs), leaving gaps for a mutation tool.

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 description coverage is 100%, so both deviceId and name are already documented in the schema; the description adds no format, constraint, or naming-rule detail beyond it. Baseline 3 applies when the schema does the heavy lifting.

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+resource pair ('Set (rename) a device's name'), and the parenthetical disambiguates rename from other 'set' operations. It is easily distinguished from siblings like tailscale_set_device_routes and tailscale_set_device_tags.

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 no when-to-use guidance, no prerequisites, and does not reference any alternative tool. Usage is only implied by the verb itself, leaving the agent to infer when renaming is appropriate.

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

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

Annotations already flag destructiveHint=true; the description adds real value by disclosing the replacement semantics ('REPLACES the enabled set') and that the input must be a subset of advertised routes. It omits permission/auth requirements and the response behavior, but the mutation semantics are well conveyed.

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?

Two tight sentences with the mutation constraint and source-of-input context front-loaded, plus the REST endpoint for reference. No wasted words.

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 2-parameter, no-output-schema mutation tool, the description covers the critical replacement behavior and input source. Minor gaps around auth requirements and return/error behavior, but nothing an agent would likely get wrong.

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 both parameters are already documented in the schema, including the REPLACES note on routes. The description adds no syntax or format detail beyond that, so the baseline 3 applies.

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 (Set) and resource (subnet routes ENABLED for a device), and clarifies these come from the advertised routes. This clearly distinguishes it from the sibling tailscale_list_device_routes reader.

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?

Explains the key condition ('from the routes it advertises') and that it REPLACES the enabled set, which routes the agent appropriately. It does not explicitly name an alternative tool or state when-not-to-use, so it stops short of a 5.

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

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

Annotations already declare destructiveHint=true, and the description earns credit by explaining exactly what is destroyed: all existing tags are REPLACED, not merged. It does not, however, mention permission/tag-ownership requirements or whether the change is reversible.

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?

Three short sentences, front-loaded with the action and the most important destructive consequence, plus a compact API reference. Nothing is padded.

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 two-parameter mutation with a full schema and a destructiveHint annotation, the description covers purpose, replacement semantics, and the endpoint well. The only meaningful omissions are authorization requirements for tag assignment and confirmation of return behavior.

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 description coverage is 100%, so the schema already documents both parameters, including the format example ["tag:server"] and the replacement semantics. The description adds no further parameter detail (e.g. deviceId format, tag naming rules), so the baseline 3 applies.

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 ('Set a device's ACL tags') and even names the underlying REST operation. It is clearly distinguishable from siblings like tailscale_set_device_name and tailscale_set_device_routes, which target different attributes.

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?

Usage is implied by the verb and the explicit REPLACES warning, but there is no statement of when to prefer this over alternatives (e.g. route setting, name setting) or any prerequisite such as needing admin/tag-ownership rights to assign ACL tags.

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