tailscale

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

The annotation destructiveHint: true already signals that this tool can have a destructive effect (de-authorization). The description adds the context about device approval being enabled, which is useful. However, it does not disclose additional behavioral details such as reversibility or immediate network impact, though the schema's parameter description partly covers the meaning of 'authorize' vs 'de-authorize'.

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 only two sentences, with the main action front-loaded. The first sentence states the purpose, and the second provides the REST endpoint. No unnecessary words or repetition; every part adds value and it is highly efficient.

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 tool with two required parameters and no output schema, the description covers the core context: what it does, when it's relevant, and the API call. The only minor gap is the lack of any return value description, but since there is no output schema and the tool's effect is straightforward, this is a minor omission.

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 input schema already provides 100% coverage with clear descriptions for both parameters (deviceId and authorized). The tool description does not add extra meaning beyond the schema, so it does not exceed the baseline score of 3. The parameter descriptions are self-explanatory.

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 clearly states the tool's function: 'Authorize or de-authorize a device' with a specific resource (device) and verb. It also adds the REST endpoint, reinforcing the exact action. This distinguishes it from sibling tools like tailscale_get_device or tailscale_delete_device, which perform different operations.

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 provides a clear usage condition: 'only relevant when device approval is enabled for the tailnet.' This tells the agent when this tool applies. While it doesn't explicitly exclude alternative tools, the tool's unique purpose and the relevance condition offer sufficient guidance for selection.

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 bar is lower. The description adds the context of 'used to register new devices' but does not disclose that the key is secret and typically shown only once. No contradiction exists between description and annotations.

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 two concise sentences, front-loading the primary purpose and then providing the REST endpoint reference. No wasted words or repetition.

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?

The schema fully documents all 6 optional parameters, and the destructiveHint annotation covers safety. However, the description does not mention the response contents (e.g., that the auth key value is returned once), which is important for an agent to know. Overall adequate but with a notable 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%, so all parameters are described in the schema. The description itself does not add any parameter-specific meaning beyond what the schema already provides, 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?

The description clearly states a specific action ('Create a new auth key') and resource ('tailnet'), and includes the purpose ('used to register new devices'). It distinguishes from siblings like tailscale_delete_key and tailscale_list_keys by indicating creation.

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 gives clear usage context by stating the key is for registering new devices, implying when to use this tool. It does not explicitly name alternatives or exclusions, but the purpose is unambiguous enough that usage is clear.

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 destructiveHint annotation already flags destructive behavior; the description adds 'removing it from the tailnet' to clarify the scope but doesn't mention irreversibility or authorization 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, front-loaded with the action and a compact REST endpoint reference; no redundant 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 simple one-parameter delete operation with a destructive annotation, the description adequately explains the effect, though it omits alternatives and response behavior; acceptable given the low complexity.

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 schema provides 100% coverage of the single deviceId parameter with a clear description; the tool description adds no additional detail about the parameter format or sourcing.

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 'Delete a device, removing it from the tailnet' with a specific verb and resource, distinguishing from sibling tools like tailscale_delete_key by targeting devices rather than keys.

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 over alternatives such as tailscale_expire_device_key or tailscale_delete_key; the description only states the action without context 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?

Annotations declare destructiveHint=true, and the description reinforces this with 'revoke' and 'security response'. It adds context about what is deleted (auth keys or API tokens) and the exact REST endpoint, going beyond the annotation's bare destructive flag.

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 two sentences, with the essential purpose in the first and a useful REST reference in the second. 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?

Given a single parameter, destructiveHint annotation, and no output schema, the description provides sufficient context including the REST operation. It does not promise return values, which is appropriate since none are defined.

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 schema describes keyId as 'The key id to delete' with 100% coverage, so the description doesn't need to explain it. However, it adds semantic context by clarifying that the id refers to an auth key or API access token, which aids interpretation.

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?

Description uses specific verb 'Delete (revoke)' and identifies the resource as 'an auth key or API access token by id', clearly distinguishing it from sibling tools like delete_device. The REST endpoint reference adds further precision.

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' provides context for when to use (revoking compromised keys), and specifying 'auth key or API access token' distinguishes from device management tools. It doesn't explicitly mention alternatives but the resource scope serves as implicit guidance.

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 destructiveHint annotation already flags this as destructive. The description adds valuable context beyond that: the consequence ('forcing it to re-authenticate') and the security rationale. It does not mention reversibility or permission requirements, but for a single-parameter tool with an annotation, this is adequate behavior disclosure.

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 a single sentence that front-loads the action, then explains the consequence and purpose. It is concise and information-dense without redundancy, earning a top score.

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 tool with one parameter, no output schema, and a clear destructive annotation, the description provides all essential context: what it does, when to use it, and the behavioral result. The REST endpoint adds technical reference. No gaps are apparent.

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 schema already fully describes the parameter (deviceId, type string, 'The device id.') with 100% coverage. The description does not add any param-specific details beyond what the schema provides, so the baseline score 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?

The description uses a specific verb ('Expire') and resource ('a device's node key'), clearly stating the action and its purpose (forcing re-authentication). It distinguishes itself from sibling tools like delete_device or delete_key by focusing on key expiration rather than deletion. The REST endpoint is also provided for precise identification.

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 a clear use case: 'a security response to a compromised or lost device.' This implicitly tells the agent when to use this tool, though it does not explicitly name alternatives or exclusions. For a destructive operation, this context is sufficient to guide selection, but it could be stronger with explicit when-not-to-use statements.

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 covers the safety profile. The description adds the REST endpoint mapping (GET /device/{deviceId}), which is mildly informative but does not disclose additional behaviors such as pagination, response format, or authentication specifics. It meets the baseline for a read-only get 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?

The description is exactly two sentences, with no filler. Every word adds value, and the key information is front-loaded.

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-device get operation with readOnlyHint true, a clear schema, and no output schema, the description is sufficiently complete. It identifies the resource, the identifier, and the underlying endpoint without unnecessary elaboration.

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 both deviceId and fields already explained in the schema. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is 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?

The description clearly states 'Get a single device by id' with a specific verb and resource, distinguishing it from list-oriented siblings like tailscale_list_devices. The endpoint reference reinforces the exact scope.

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 'Get a single device by id' clearly implies when to use this tool (when you have a specific device ID) versus listing devices. It does not explicitly name alternatives, but the context is unambiguous.

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, and the description reinforces this by specifying the REST method GET. It adds the concrete context of retrieving DNS preferences and the example of MagicDNS, which goes beyond the bare annotation. No contradictions found.

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 extremely concise: two short sentences, front-loaded with the core purpose, and no wasted words. The REST endpoint is useful supplementary context.

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, zero-parameter read-only GET, the description is reasonably complete. It states the resource, gives an example, and includes the API path. It could mention return format, but given no output schema and low complexity, it is sufficient.

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?

There are no parameters in the schema, so the baseline is 4. The description does not need to explain parameters; it confirms the operation scope via the endpoint path. No parameter-related confusion exists.

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 uses the specific verb 'Get' with the resource 'tailnet's DNS preferences' and gives a clear example ('e.g. whether MagicDNS is enabled'). This clearly distinguishes it from sibling tools like get_split_dns or list_dns_nameservers by naming the preferences scope.

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 context is implied: use this tool when you need the tailnet's DNS preferences. However, it does not explicitly contrast with alternatives like get_tailnet_settings or list_dns_nameservers, nor does it mention any conditions 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?

Annotations already provide readOnlyHint=true, so the safe read behavior is known. The description adds useful context about the fields returned (capabilities, expiry, usage) and the REST endpoint, but does not go beyond that to include response format or error conditions, which is acceptable for a simple read tool.

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 two sentences, front-loaded with the core action, and includes the REST endpoint for reference. Every word earns its place; no filler or repetition.

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 tool with one required parameter and no output schema, the description adequately covers the purpose, input, and data scope. It lacks detail about the return structure, but no output schema exists and the tool is simple enough that the description is sufficient for correct invocation.

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 the keyId parameter described as 'The key id.' The description does not add meaning beyond the schema, but the schema already fully documents the only parameter, so the baseline of 3 is 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?

The description clearly states 'Get details of a single auth key / API access token by id (capabilities, expiry, usage)', providing a specific verb, resource, and scope. It distinguishes this from sibling tools like list_keys (enumerating keys) and delete_key.

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 'single ... by id' gives clear context that this is for retrieving one specific key when you already have its ID. It does not explicitly mention alternatives like list_keys, but the usage is clear from the wording.

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 agent knows it's a safe read. The description adds valuable context: the response is JSON via the Accept header rather than HuJSON, and it specifies the exact REST endpoint. This goes beyond the annotation without contradicting it.

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-load the purpose and add one critical format detail. No wasted words or repetition of schema 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?

Given the simple one-parameter tool with readOnly annotation and no output schema, the description covers the purpose, endpoint, and response format. It could mention what the policy file contains or when to use the details flag, but the schema covers the flag, so this is largely complete.

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 only parameter 'details' is fully documented in the input schema (100% coverage), so the description doesn't need to add more. The tool description adds no extra meaning beyond the schema, making 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?

The description uses the specific verb 'Get' and identifies the resource as 'the tailnet's ACL / policy file', distinguishing it from sibling tools like tailnet settings or DNS preferences. The mention of the REST endpoint further clarifies the exact operation.

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 provides implied usage (this is the tool for reading the policy file) but does not explicitly state when to use it versus alternatives or any exclusions. With many sibling getters, more explicit guidance would help, but the context is reasonably clear.

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?

With readOnlyHint=true already indicating a safe read, the description adds the result format (map of domain to nameservers) and the REST endpoint, providing useful behavioral context. No additional side effects or auth requirements are relevant for this trivial getter.

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 a single, well-structured sentence that front-loads the action and resource, then provides the return format and API 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?

The tool is a simple parameterless GET operation with no output schema. The description covers the return format and the API endpoint, making it complete for an agent to understand the tool's 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?

The input schema has zero parameters, so the baseline is 4. The description appropriately omits parameter details, and no additional parameter semantics are 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?

The description clearly states the tool retrieves the tailnet's split-DNS configuration and specifies the output format as a map of domain to nameservers. The verb 'Get' and the resource 'split-DNS configuration' distinguish it from sibling DNS tools like get_dns_preferences and list_dns_nameservers.

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 does not explicitly state when to use this tool versus alternatives, but the resource-specific wording 'split-DNS configuration' implies its use for per-domain DNS settings. It lacks explicit exclusions or alternative tool references.

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 nature is established. The description adds contextual detail about the specific settings returned and the REST endpoint, but doesn't disclose response format or pagination. It provides some value beyond annotations but not extensive behavioral detail.

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 a single, well-formed sentence that directly states the purpose and gives a relevant REST endpoint. It is concise with no wasted words, perfectly sized for the tool's simplicity.

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, the description sufficiently covers what the tool does and what it returns (tailnet settings with examples). The absence of an output schema is not a gap because the description provides enough information about the response nature. The tool is simple enough that the description is complete.

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?

There are no parameters, so the description has no need to elaborate on parameter semantics. The schema coverage is 100% (vacuously), and the description adds no conflicting or confusing information. Baseline of 4 is appropriate for a zero-parameter tool.

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 clearly states the tool's function with a specific verb ('Get') and resource ('tailnet's settings'), listing example settings (device approval, key expiry, posture). This distinguishes it from sibling tools that target other resources like devices, users, or DNS.

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 provides clear context by naming the specific resource ('tailnet settings') and even referencing the REST endpoint. Although it does not explicitly mention when not to use it or name alternatives, the scope is self-evident given the sibling tools, making usage conditions clear enough.

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, covering the safety profile. The description adds the REST endpoint (GET /users/{userId}) but discloses no additional behavioral traits such as auth needs, rate limits, or error handling. With annotation coverage, this is acceptable but not enriching.

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 two short sentences: the first states the action clearly, the second provides the REST endpoint. Every word earns its place, with no redundancy or vagueness.

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 tool with one parameter and no output schema, the description sufficiently explains what it does and the endpoint. Minor gap: no indication of return format, but this is not critical for a basic get 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 input schema fully documents userId with a description ('The user id.'). The description's 'by id' adds no new meaning beyond the schema, and schema coverage is 100%, so baseline 3 is 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?

The description clearly states the tool retrieves a single user by ID, using a specific verb and resource. It distinguishes from siblings like tailscale_list_users by emphasizing 'single user' versus list retrieval.

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 provides no guidance on when to use this tool versus alternatives such as tailscale_list_users. It implies use when you have a userId, but doesn't explicitly state exclusions or alternative tools.

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 signals a safe read operation. The description adds valuable context by specifying 'subnet routes a device advertises and which are enabled', clarifying the scope of the listing. The REST GET endpoint reinforces read-only behavior, though no additional details like authentication or response format are provided.

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 concise sentences: the first states the core functionality, the second cites the REST endpoint. No redundant or filler content; each sentence carries meaningful 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 one-parameter read-only list tool with a clear schema, the description covers the purpose and partially describes the output (advertised vs enabled routes). No output schema exists, so the description could have mentioned the return format more explicitly, but it is sufficiently complete given the tool's simplicity.

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 schema fully describes the only parameter (deviceId) with 'The device id.' The description does not elaborate on the parameter, but since schema coverage is 100%, the baseline of 3 applies. No extra meaning is added beyond confirming the device context.

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?

Description clearly states 'List the subnet routes a device advertises and which are enabled', specifying the verb (list) and resource (subnet routes of a device). It distinguishes from siblings like tailscale_set_device_routes (which modifies routes) and tailscale_list_devices (which lists devices). The REST endpoint is also provided for further clarity.

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 implies usage context: use this tool to list routes, and the presence of tailscale_set_device_routes in siblings hints at the alternative. However, no explicit when-to-use or when-not-to-use guidance is given, so it remains at baseline implied 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?

Annotations already declare readOnlyHint=true, and the description adds value by disclosing the scope ('all devices') and the type of information returned. No contradictions; it just doesn't discuss pagination or rate limits, but with annotations covering safety, this is sufficient.

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 two short sentences that front-load the action and resource, then provide the REST endpoint. No superfluous words; every part adds context.

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?

This is a simple list tool with one optional parameter and no output schema. The description covers scope, returned fields, and the API endpoint, and the sibling set clarifies its unique role among device-related operations.

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 input schema has 100% coverage: the sole 'fields' parameter is described with its enum and meaning. The description does not add parameter-specific information, so the baseline of 3 applies because the schema carries the semantic weight.

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 clearly states 'List all devices in the tailnet' with a specific verb and resource, enumerates the returned attributes (name, addresses, OS, last seen, tags), and distinguishes this tool from siblings like get_device or list_device_routes.

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 implies usage for listing all devices and includes the REST endpoint for context, but it does not explicitly mention when not to use it or point to alternatives such as get_device for a single device. The context is clear, yet exclusions are absent.

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 annotation readOnlyHint=true already conveys the safe read-only nature. The description adds that it lists 'global' nameservers, clarifying scope, and provides the REST endpoint, which is a useful reference but not a behavioral trait. It does not discuss pagination or response format, but these are less critical given the tool's simplicity.

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 two short sentences. The purpose is front-loaded in the first sentence, and the second sentence provides a technical reference without adding fluff. Every word 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?

The tool is a simple list operation with no parameters, a read-only annotation, and no output schema. The description sufficiently conveys that it returns the global DNS nameservers; it is complete for this low-complexity 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?

The tool has zero parameters, and the input schema is empty. The description therefore has no parameters to explain; the baseline for 0-param tools is 4, and the description appropriately omits any parameter details.

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 clearly states a specific action ('List') and resource ('global DNS nameservers configured for the tailnet'), distinguishing it from sibling tools like list_dns_searchpaths or list_devices. The verb and object leave no 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?

No explicit guidance is provided about when to use this tool versus alternatives. The description simply states what it does; it does not mention when one should prefer this over list_dns_searchpaths or other list operations, nor any 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 annotation already establishes the read-only nature. The description adds the Tailscale REST endpoint and the tailnet scope, which is useful context but does not go beyond that. There is no contradiction.

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 a single, focused sentence that includes the resource, scope, and underlying REST call. It is front-loaded and contains 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 simple read-only list operation with no parameters and no output schema, the description sufficiently explains what is listed and which tailnet it applies to. It does not describe the return format, but that is not required given the simplicity and available annotations.

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 has zero parameters, so the description cannot add parameter-level meaning. The description does mention the REST path with a {tailnet} placeholder, providing some context about the underlying API despite the empty schema.

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 clearly states the action ('List') and the specific resource ('DNS search paths (search domains)') and scopes it to 'the tailnet'. This distinguishes it from sibling tools like list_dns_nameservers and get_dns_preferences.

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 explicit guidance is given about when to use this tool versus alternatives. It merely describes what the tool does; there is no mention of when not to use it or comparison to related DNS/list tools.

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, and the description confirms a read-only list operation. It adds that the tool lists auth keys and API access tokens, and cites the REST endpoint, but it does not disclose default scoping (e.g., only the caller's own keys unless 'all' is true) or pagination behavior, which would be useful behavioral context beyond the annotation.

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 a single sentence that front-loads the core purpose ('List auth keys and API access tokens for the tailnet') and includes a useful REST endpoint reference. It contains no redundant or vague wording, earning a high score for conciseness.

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 tool with one optional parameter and no output schema, the description states the operation and the API path, which is largely sufficient. The parameter schema covers the 'all' behavior, and the read-only annotation is clear. However, it could be more complete by mentioning the default scoping (only caller's own keys) directly in the description, though this is already in the schema.

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 input schema has high coverage: the sole parameter 'all' includes a complete description explaining its effect. The tool description itself adds no parameter-specific context, but given 100% schema coverage, the baseline score of 3 is 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?

The description uses a specific verb 'List' and clearly identifies the resource as 'auth keys and API access tokens for the tailnet', distinguishing it from sibling tools like get_key, create_auth_key, and delete_key. The REST endpoint reference adds further precision.

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 implies usage for listing all keys in the tailnet, but does not explicitly state when to use this tool over alternatives like get_key, nor does it provide exclusions or prerequisites. There is no mention of 'use get_key for a single key' or similar guidance, making the usage context only implicit.

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, and the description adds the tailnet scope and filtering options without contradicting annotations. It does not disclose pagination, return format, or auth requirements, but for a simple read-only list operation this is acceptable. The REST endpoint reference adds minor implementation detail.

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 two concise sentences: the first states the action and filters, the second provides the REST endpoint. Every word adds value, with no redundancy or 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 simple read-only list tool with no output schema, the description adequately conveys the tailnet scope, filtering capability, and REST endpoint. It does not explicitly state the return type (array of users), but 'list users' implies a list, and no complex behavior requires further explanation.

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 three parameters (type, role, status) already documented. The description's mention of 'filtered by type, role or status' only restates what the schema provides, adding no extra syntax or behavioral meaning beyond baseline.

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 clearly states the tool's function: 'List users of the tailnet' with optional filtering by type, role, or status. This uses a specific verb and resource, and distinguishes it from sibling tools like tailscale_get_user (singular) and tailscale_list_devices.

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 provides clear context on when to use the tool: to list tailnet users, with optional filters. It does not explicitly mention alternatives or when not to use it (e.g., when needing a single user), but the purpose is unambiguous enough for simple list operations.

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 annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds the tailnet scoping and REST endpoint reference, but does not disclose output format, authorization needs, or rate limits. This is acceptable for a simple list operation but adds no major behavioral context beyond annotations.

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 a single, information-dense sentence. It states the action, resource, scope, and REST endpoint without fluff. Every word 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 simple zero-parameter read-only tool, the description is complete enough: it says what the tool returns (webhook endpoints) and the scope. No output schema exists, but the description provides sufficient context for an agent to invoke the tool correctly. It could be improved by noting any output fields or pagination, but that is not critical for invocation.

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 has zero parameters, and schema coverage is 100% (vacuously). Per the rubric, a 4 is the baseline for zero-parameter tools. The description does not need to explain parameters since none exist.

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 uses the specific verb 'List' with the resource 'webhook endpoints' and scope 'for the tailnet', clearly distinguishing it from all sibling tools which focus on devices, keys, DNS, etc. It also provides the REST endpoint for precision.

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 makes it clear this tool is for listing webhook endpoints, which is the only webhook-related tool among siblings, so context is clear. It lacks explicit when-not-to-use or alternative recommendations, but given its unique purpose, the usage context is adequately 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?

The destructiveHint annotation already indicates mutation, and the description's 'Set (rename)' is consistent. The REST endpoint mentions the HTTP method (POST), which is a minor additional context. However, it does not disclose other behavioral traits such as reversibility, impact on device connections, or required permissions, so it adds limited value beyond the annotation.

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, each earning its place: one states the operation, the other gives the REST endpoint. No unnecessary words, well front-loaded.

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 tool with no output schema, the description is adequately complete. It clearly identifies the action and target. The lack of usage guidance and behavioral details is acceptable for such a straightforward operation, though it could briefly mention potential consequences.

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 both 'deviceId' and 'name' having simple descriptions. The tool description does not add any further meaning beyond what the schema already provides, so it meets the baseline for high coverage.

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 clearly states the operation: 'Set (rename) a device's name.' It identifies the specific resource (device) and the action (rename). It distinguishes from siblings as the only tool for renaming devices, and the REST endpoint confirms the specific operation.

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 implies usage for renaming a device but provides no explicit guidance on when to use this tool versus alternatives. It does not mention any prerequisites, side effects, or when not to use it, so the usage context is only implied by the tool's name and description.

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, and the description adds concrete behavioral detail: it REPLACES the enabled set and only affects advertised routes. It also notes the underlying REST endpoint. This goes beyond the annotation without contradicting it.

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 three short, information-dense sentences. All statements earn their place: what is set, the replacement behavior, and the equivalent REST call.

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 only two parameters, full schema coverage, a destructive annotation, and explicit replacement semantics, this description is complete for its complexity. It also supplies the endpoint, making the behavior fully predictable.

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 each parameter is already documented. The description adds no new parameter-level semantics; it mostly restates what the schema says ('REPLACES the enabled set'). Baseline 3 is appropriate because 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?

The description clearly states a specific verb ('Set') and resource ('subnet routes ENABLED for a device'), and distinguishes itself from sibling tools by emphasizing that it replaces the enabled set. This is unambiguous and distinct from list_device_routes.

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 practical usage context: routes must come from those the device advertises, and the call replaces the enabled set. It does not explicitly name alternatives or when-not-to-use, but the context is clear enough for a sibling set of route/device tools.

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 annotation destructiveHint already indicates mutation; the description adds that tags are replaced, which is critical behavioral context, and also reveals the underlying REST endpoint.

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 concise sentences front-load the purpose and include the replacement warning and REST endpoint without 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 simple 2-parameter mutation with no output schema, the description fully covers intent, behavior, and context. No gaps identified.

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% as both parameters have descriptions in the schema. The tool description adds no new parameter-level semantics.

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 uses the specific verb 'Set' with the resource 'device's ACL tags', and explicitly notes the replacement behavior, which distinguishes it from sibling tools like set_device_name or set_device_routes.

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 explicit when-to-use or alternative guidance is provided, though the purpose implies usage for setting device tags. Sibling tools cover related operations but are not referenced.

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