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

Annotations already declare idempotent=true, destructive=false, openWorld=true, and readOnly=false. The description goes well beyond them: non-blocking login behavior, authURL return, headless login via TAILSCALE_AUTH_KEY_FILE, polling until reachable, no elevation needed on Windows, and the success condition state=running. The one gap is timing/rate expectations for the polling phase.

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?

Front-loads the one-line purpose before any branching detail, then uses a compact sentence per state, and closes with the success criterion. No sentence is redundant; the parenthetical `tailscale up` disambiguation is worth its length.

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?

An output schema exists, so return-value enumeration is optional, yet the description still names the action enum and the success state. Combined with annotations covering the safety profile, an agent has everything needed to decide to call it and to interpret a non-blocking login result.

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; there are no inputs to disambiguate. The enumerated action values (already_connected | reconnected | needs_login) describe the outcome rather than an input, which adds useful framing but is not parameter 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?

States a specific verb and resource ('Bring this host online on its tailnet (`tailscale up`)') and immediately scopes it ('Connectivity only'), then names the sibling tool that handles the excluded concern (tailscale_set_prefs). An agent can distinguish it from tailscale_disconnect, tailscale_status, and tailscale_set_prefs without opening any 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?

Explicitly routes preference changes to tailscale_set_prefs, and enumerates per-state behavior: already Running returns immediately, Stopped with a valid key does a flag-free up and polls, login-required returns authURL without blocking. This is when-to-use guidance at the level of internal states rather than vague intent.

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 only cover the safety profile (readOnly=false, idempotent=true, destructive=false); the description goes well beyond, disclosing that login is preserved, the operation is fully reversible, the node key does not expire, and that connectivity is interrupted for every user on the machine (hence approval). It also states the success condition (state=stopped) and the possible action values.

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?

Dense but front-loaded: the core action comes first, then the disambiguation clauses, then the approval and success criteria. Every clause carries distinct information and nothing is redundant with the annotations.

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 mutation tool with annotations plus a full output schema, this is complete: reversibility, sibling routing, approval need, and success signal are all present. No pagination/auth/return-format gaps remain.

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% and there is a single optional parameter, so the schema already documents `reason` fully. The description adds no parameter-level detail, but the baseline of 3 applies when the schema carries the burden.

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 ('Disconnect this host') and immediately names the underlying command (`tailscale down`). It explicitly contrasts with both siblings an agent could confuse it with: tailscale_connect (reversal) and tailscale_logout (node key expiry).

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?

Gives explicit when-to-use-this vs when-to-use-the-alternative: use tailscale_logout if you want to expire the node key, use tailscale_connect to undo. Also flags the approval requirement, which is a real gate on invocation.

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, idempotentHint, destructiveHint=false, and openWorldHint, so 'Read-only' largely restates structured data. The description does add real context beyond annotations: the 100.100.100.100 forwarder address, the specific configuration categories returned, and the equivalent CLI invocation for verification. It does not state auth requirements or output shape.

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 tight sentence: the subject (DNS forwarder / MagicDNS config) is front-loaded, the enumerated return contents follow, and the read-only constraint and CLI equivalent are appended without waste. No filler or 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?

No output schema exists, so the description must convey what comes back, and it does by naming resolvers, split-DNS, and cert domains. It is adequate for a single optional-flag read tool, though it could note whether results are scoped to the current profile or whether the call requires a running daemon/connection.

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% for the single 'all' parameter ('Include the full DNS configuration detail'), so the schema carries parameter meaning. The description never references the detail toggle or any flag syntax, adding nothing on this dimension — 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 ('Report') and a specific resource (internal DNS forwarder / MagicDNS configuration), then enumerates what is reported: resolvers, split-DNS, cert domains. No sibling tool touches DNS, so the resource naming alone cleanly separates it from tailscale_status, tailscale_get_prefs, and tailscale_netcheck.

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 rather than stated: the 'DNS status' scope plus 'Read-only' tells an agent this is an inspection call for MagicDNS/split-DNS state, but there is no explicit when-to-use framing or comparison against inspection siblings like tailscale_status or tailscale_netcheck. No exclusion conditions are given.

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, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the exact CLI invocation, the availability-while-Stopped behavior, and the shape of returned fields.

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 terse clauses, front-loaded with the verb and resource, then the mechanism and availability caveat. 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?

With no output schema, the description compensates by naming representative returned fields (AcceptRoutes, AcceptDNS, ExitNode, Hostname, RunSSH, ShieldsUp), so the agent knows what comes back. Nothing needed to call 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 and the schema coverage is trivially 100%. Baseline for a parameterless tool is 4.

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 (Return), resource (this host's current effective Tailscale preferences), and even the underlying command (`tailscale get --json`). An agent can immediately distinguish it from the sibling tailscale_set_prefs and from status-style tools.

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?

Gives a concrete usage condition — 'works even while Stopped' — which tells the agent when this tool is still valid. It does not explicitly name tailscale_set_prefs as the write alternative, but 'Read-only' makes the read/write split 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/idempotentHint/destructiveHint=false, so safety is covered. The description still adds real context beyond them: the policy sources (MDM/GPO/registry) and the precise scope boundary versus device posture, which is the main confusion risk for this 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?

Two compact sentences with the resource and its sources front-loaded, followed by the usage condition and the scope caveat. Every clause earns its place; nothing is redundant with the annotations or schema.

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 zero parameters, no output schema, and a full annotation set, the description carries exactly the load it needs to: what is listed, where the policy comes from, when to reach for it, and what it is not. Nothing needed to call it correctly is 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 no parameters, so there is no parameter semantics to explain; baseline for a 0-param tool is 4. The description correctly does not invent parameters and instead spends its words on scope.

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?

Specific verb (List) plus precise resource (effective LOCAL system policy applied to Tailscale via MDM/GPO/registry), and it names the underlying CLI command. It also actively disambiguates from the nearest confusable concept ('NOT Tailscale device posture'), so an agent can place it 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?

Gives an explicit triggering scenario: use it to explain a preference that a set/up change did not persist, which implicitly routes the agent here after failures from the set_* siblings. It does not name those sibling tools directly, so the alternative selection is inferred 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, idempotentHint=true and destructiveHint=false, so 'Read-only' in the description largely repeats structured data. The one genuinely additive behavioral fact is that suggest returns a single node rather than a list, which is useful but thin; no detail on pagination, latency of suggestions, or failure modes.

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?

A single dense sentence that front-loads the core action and appends the filter, the alternate mode, the safety note, and the follow-up tool in a logical order. 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 two-parameter, read-only listing tool with no output schema, the description covers what is listed, how to filter, the suggestion variant, and the next step. It does not describe the shape of returned node data (name, IP, location), which would be the remaining 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 both parameters are already documented, and the description's mention of country filtering and the suggest mode only restates them. Baseline 3 applies since the schema does the heavy lifting and the description adds no format or constraint detail.

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 tailnet nodes advertising as exit nodes') and explicitly names the sibling used to act on the result ('Select one with tailscale_set_exit_node'). An agent can distinguish this read/lookup tool from tailscale_set_exit_node without opening either 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?

Gives clear usage context: use it to enumerate exit nodes, optionally filtered by country, or to get a single suggestion, and directs the agent to tailscale_set_exit_node for selection. No explicit when-not-to-use guidance or mention of alternatives such as tailscale_status, 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 readOnlyHint, idempotentHint, and destructiveHint=false, so the trailing 'Read-only.' largely restates structured data. The genuinely additive information is that profiles are machine-local and the tool wraps `tailscale switch --list`, which helps an agent reason about scope but is thin behavioral context.

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?

Front-loaded and very short, with the core purpose in the first clause. The closing 'Read-only.' is redundant with the readOnlyHint annotation and could have been spent on return-value detail instead, but the payload is otherwise waste-free.

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-argument, read-only list command with full annotation coverage, the description covers purpose and execution context adequately. With no output schema, a hint about the shape of the returned profile list would have closed the remaining 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?

The tool takes zero parameters, so per the baseline this dimension starts at 4 and there are no parameter semantics for the description to clarify or omit. Nothing here degrades the score.

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 precise verb+resource ('List the Tailscale account/login profiles') and pins the scope to 'on this machine', with the backing CLI command for corroboration. It is unambiguously distinct from sibling tailscale_switch_profile, which mutates the active profile rather than listing them.

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 — an agent can infer this is the discovery step before tailscale_switch_profile, but the description never says when to prefer this tool or that switching is the natural follow-up. No exclusions or prerequisite conditions are given.

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, destructiveHint=false, openWorldHint=true, so 'Read-only' is largely redundant. The description does add value beyond annotations by disclosing the return format ('Returns JSON') and the categories of data returned, which matters since there is no output schema, but it says nothing about execution cost, runtime, or whether it contacts external relays.

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?

A single compact sentence, front-loaded with the action and resource, followed by two short factual clauses. Nothing is padded and every element (diagnostic list, return format, safety) 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, non-destructive diagnostic whose safety profile is fully covered by annotations, the description supplies the key missing pieces: what is measured and that JSON comes back. It stops short of describing the JSON shape or typical latency of the check, but nothing essential to invoking it correctly is 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 no parameters and the schema is empty, so there are no parameter semantics to explain. Per the baseline for zero-parameter tools, a 4 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 states a specific verb ('Analyze') and resource ('local network conditions'), then enumerates the concrete diagnostics it surfaces: DERP relay reachability & latency, NAT type, UDP, IPv6. That is enough to separate it from siblings like tailscale_status or tailscale_ping, though no sibling is named explicitly, which keeps it 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?

Usage is implied by the content ('analyze network conditions') but the description never says when to reach for this versus tailscale_ping, tailscale_dns_status, or tailscale_status, and gives no preconditions or exclusions. Adequate for a read-only diagnostic but leaves routing to inference.

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, idempotentHint, destructiveHint=false, and openWorldHint, so the safety profile is covered before the description starts. The description does add one genuine behavioral detail — that the result reports the connection path (DERP relay vs direct) — but says nothing about how `count`/`untilDirect` interact, latency expectations, or failure 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?

A single sentence that front-loads the action, the peer target, and the diagnostic payoff, with zero filler. Nothing is repeated or padding.

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 all three parameters fully specified in the schema and the safety profile carried by annotations, an agent has nearly everything it needs; the description usefully signals the return content despite no output schema. It would be stronger if it noted the tool's relationship to netcheck and typical latency of a ping.

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 each parameter (target, count, untilDirect) is documented in the schema with defaults and bounds. The description adds no syntax, format, or interpretation detail beyond that, 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?

The description states a specific verb and resource ('Ping a peer at the Tailscale layer') and even cites the underlying command (`tailscale ping`), plus the key output (DERP relay vs direct path). It does not explicitly contrast itself with the nearest diagnostic sibling, `tailscale_netcheck`, so it falls short of full sibling differentiation.

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 reach for this tool versus `tailscale_netcheck`, `tailscale_status`, or `tailscale_whois`, nor any prerequisites (e.g., peer must be online/authorized). The only guidance is the appended 'Read-only', which restates the annotations rather than advising 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/idempotentHint and destructiveHint=false, so safety needs little restating. The description adds genuinely non-obvious behavior: which backends are live, whether REST credentials are configured, the effective tailnet, and the exact reason a tool is unavailable (risk_gated vs. needs_credentials) with the environment variables that resolve each case.

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?

Dense but front-loaded: the report contents come first, the "use when missing" trigger follows, and the closing "Read-only" is a one-word reinforcement of the annotations. It is a single long sentence chain, so readability could be improved, but no sentence is wasted.

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 parameters, no output schema, and annotations covering the safety profile, the description still enumerates exactly what the response contains (version, backends, tailnet, risk level, per-tool availability plus cause) and what the agent should do with each cause. Nothing needed to invoke or interpret this tool 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 the baseline is 4 and there is no schema semantics to augment or omit.

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 (report) and a precise resource set: server version, live backends, effective tailnet, risk level, and a per-tool availability catalog. This is clearly distinguishable from diagnostic siblings like tailscale_status, tailscale_version or tailscale_whoami, which report tailnet state rather than server/tool-catalog state.

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?

"Use this when a tool you expected is missing" gives an explicit trigger condition, and the description enumerates the two remediation branches (risk gating vs. credentials) so the agent knows this is the routing tool for absent capabilities. No alternative tool is named for that job, so it stops short of full when/when-not/alternatives coverage.

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 cover the safety profile (readOnly=false, idempotent=true, destructive=false, openWorld=true), and the description adds genuinely new context: the operation redirects ALL of the host's traffic and therefore requires user approval. That approval gate is a behavioral trait annotations do not convey, though return-shape and failure modes are only gestured at.

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, with the core routing behavior and the clear semantics front-loaded before the warning. No filler; every sentence carries load.

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 an output schema present, the description need not explain return values, and it appropriately notes the resulting status plus the approval requirement and clearing behavior. Only the absence of a pointer to sibling discovery tools keeps it short of fully 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?

Schema coverage is 100%, so both parameters (exitNode, allowLanAccess) are already documented in the schema. The description's mention of passing an empty string to clear merely echoes the schema description rather than adding syntax or format detail.

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 (route this host's internet traffic through a tailnet exit node), names the underlying CLI command, and clearly distinguishes itself from siblings like tailscale_list_exit_nodes by being the setter rather than the lister.

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 when the tool applies (redirecting this host's internet traffic) and covers the clear-via-empty-string case plus the user-approval requirement. It does not, however, point at the sibling an agent should call first to discover available exit nodes (tailscale_list_exit_nodes), leaving that inference to the agent.

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 idempotent, non-destructive, open-world behavior, but the description adds real value beyond them: the write is incremental/partial (unspecified prefs are left untouched) and no full flag set is required, which is precisely what an agent needs to avoid clobbering settings. It does not warn about the connectivity impact of prefs like shieldsUp, but that is a minor omission given annotation coverage.

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 tight clauses with zero filler, and the scoping statement ('no connect/disconnect, no complete-flag-set requirement') is front-loaded where it matters most.

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-required-param mutation tool with annotations and an output schema (so return values need not be explained), the description covers purpose, scope, and sibling routing. The remaining gap is that the set of settable preferences is left entirely to the schema, which an agent could underestimate for an 11-param 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?

Eleven parameters with only 36% schema description coverage, and the description names none of them — not even the boolean/string shape or that booleans toggle on/off. It only gestures at the class ('benign prefs'), so it fails to compensate for the coverage gap and adds little meaning beyond the 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?

States a specific verb and resource ('Incrementally change one or more preferences via `tailscale set`') and immediately scopes it away from connect/disconnect and the full-flag-set semantics. It also names the sibling tools (exit-node, routes) that own the excluded settings, so an agent can distinguish it from tailscale_set_exit_node and tailscale_set_routes without opening any 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?

Explicitly says when this tool applies (partial, single-or-multiple prefs, no complete flag set needed) and when it does not (exit-node and route changes belong to dedicated tools). It stops short of telling the agent to read current state with tailscale_get_prefs first, so there is one obvious inference left.

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?

Beyond the annotations (which already declare non-read-only, idempotent, non-destructive, open-world), the description adds genuinely useful context: route changes alter connectivity and require user approval, and advertised routes still need admin-console approval. It stops short of describing failure modes or propagation timing.

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?

Front-loaded with the primary action and packed with the CLI hint, approval warning, and withdrawal rule in a few tight sentences. Slightly dense with the parenthetical CLI reference, but nothing is wasted.

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 an output schema present, return values needn't be explained, and the description covers both modes, the approval gate, and the withdrawal semantics. It is largely complete for a two-parameter toggle 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 parameters are already documented, including '[] withdraws all'. The description restates the empty-array withdrawal but adds no format or syntax detail beyond the schema, 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?

The description states a specific verb+resource (advertise subnet routes / toggle accepting routes) and even names the underlying CLI equivalent, so the agent can distinguish it from siblings like tailscale_set_exit_node and tailscale_set_prefs. The two distinct sub-actions are explicitly called out.

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 explains the context (advertise from this host, toggle accepting peer routes) and the approval prerequisite, but never names alternatives or states when to prefer set_routes vs set_exit_node. Usage is implied rather than prescribed.

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 readOnly/idempotent/non-destructive, so the bar is lower, yet the description adds real value: it defines exactly when 'connected' is true (BackendState=Running AND Self.Online), warns that a persistent Tailscale IP does not imply connectivity, and notes the plain-status exit code is intentionally ignored. It omits auth requirements or rate limits, but the semantic caveats are genuinely useful.

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?

Front-loaded with the core purpose, and each subsequent sentence addresses a real pitfall (connected semantics, IP persistence, exit code). Dense but nearly every clause earns its place; only the exit-code note is arguably marginal.

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 status tool with a full output schema, the description is more than sufficient, even pre-explaining the normalized 'state' and 'connected' output semantics. Nothing an agent needs to call or interpret 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 description coverage is 100% with a single well-documented 'peers' boolean, so the schema already carries parameter meaning. The description adds nothing about the parameter, 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 ('Report') and resource ('this host's Tailscale connection state'), with the scope 'this host' distinguishing it from sibling tools like tailscale_whoami or tailscale_netcheck. An agent can tell what it returns 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 'this host' scope implicitly narrows it relative to peers/host-oriented siblings, but there is no explicit when-to-use statement or named alternative. Usage is inferable from the scope rather than spelled 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?

Adds genuinely non-obvious behavior beyond the annotations: that the switch changes which identity/tailnet controls the node, that user approval is required, and that the resulting status is returned. Annotations already declare non-read-only, non-destructive, non-idempotent, so the description's contribution is the impact/approval context. It stops short of disclosing reversibility, side effects on existing connections, or failure modes.

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 tight sentences, front-loaded with the action, followed by the warning and the id source, ending with the return behavior. The CLI equivalent and warning glyph earn their 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-param mutation tool with an output schema, the description covers the identity impact, approval requirement, id provenance, and return signal. 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?

Schema coverage is 100% and the single param already documents 'Profile id from tailscale_list_profiles', which the description repeats rather than extends. No added syntax, format, or edge-case meaning beyond what the schema states, 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 ('Switch the active Tailscale account/login profile') and pins it to the exact CLI operation. It is clearly distinct from the read-only sibling tailscale_list_profiles and from unrelated setters like tailscale_set_prefs.

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 routes the agent to tailscale_list_profiles to obtain the required id, and flags the user-approval prerequisite. It does not, however, state when-not to use this (e.g. between connect/disconnect) or how it interacts with other profile-affecting 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is fully covered. The description's 'Read-only' largely restates that, and adds only the underlying CLI invocation; it does not describe the shape of results or latency of the optional upstream check.

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?

A single compact sentence that front-loads what is reported and appends the optional behavior. Every clause earns its place with 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 trivial zero-required-parameter, single-parameter tool with no output schema, the description gives enough to call it correctly, and the annotations carry the safety profile. It could briefly note that the upstream check requires network access, but nothing essential 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%, so the schema already documents checkUpstream as 'Also check the latest available release.' The description's 'optionally checking for updates' adds a small amount of framing but no format, cost, or network-behavior detail beyond what the schema provides, 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?

States a specific verb (Report) and resource (client and daemon versions), and even names the underlying command (`tailscale version --json`). This clearly distinguishes it from siblings like tailscale_status, tailscale_server_info, and tailscale_whoami, which report different data.

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 'optionally checking for updates' implies when the checkUpstream parameter matters, but there is no explicit guidance on when to prefer this tool over tailscale_status or tailscale_server_info, nor any stated prerequisites. Usage is implied 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, idempotentHint=true, and destructiveHint=false, so the description's 'Read-only' adds no new safety information. The only extra context is the underlying CLI invocation (`tailscale whoami --json`), which is minor and does not describe output behavior or auth needs beyond what annotations already cover.

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 very short sentences with zero waste; the purpose is front-loaded and the parenthetical CLI hint is appropriately compact.

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 with no output schema, the description gives enough to know what it returns at a high level. It could be slightly richer about what identity fields are included, but nothing essential to 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?

There are zero parameters, so the schema carries no burden and the baseline is 4. The description adds no parameter information, but none is needed for a parameterless 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 states a specific verb ('Show') and resource ('machine + user identity of this node'), making clear it returns the local node's identity rather than another node's. It does not explicitly name a sibling like tailscale_whois or tailscale_status to sharpen the boundary, but 'of this node' is enough to distinguish it from remote-identity tools.

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 or when-not-to-use guidance is given, and no alternatives are mentioned. The agent can infer the purpose from the title, but the description provides no routing information against siblings such as tailscale_status or tailscale_whois.

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, idempotentHint, openWorldHint, and destructiveHint, so the appended "Read-only" is redundant. The only extra context is the reference to the underlying `tailscale whois --json` command, which adds little behavioral insight beyond what the structured data already covers.

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 result, with no wasted words. Appropriately sized for a single-parameter lookup tool.

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 lookup with full schema coverage and rich annotations, the description is nearly complete. With no output schema, a brief note on the returned fields (machine name, user, maybe node) would have closed the remaining 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 coverage is 100% and the single ip parameter is well documented ("optionally with :port"), so the baseline is 3. The description adds no meaning beyond what the schema 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 ("Show") and resource ("the machine and user associated with a Tailscale IP"), making it clearly distinct from the sibling tailscale_whoami which resolves the local identity. An agent can pick between the two without opening either 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?

Usage is implied (given an IP, resolve its owning machine/user) but there is no explicit when-to-use or when-not-to-use guidance, and no named alternative. The contrast with whoami is inferable but not stated.

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