tslink

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

Annotations cover the safety profile (readOnly, idempotent, openWorld=false), and the description adds substantive detail beyond them: the data source ('reads the local registry') and the honest limits of the answer (no live tailnet policy, no backend authentication). That is exactly the kind of scope disclosure annotations cannot carry.

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 tool's purpose, followed by usage and caveats. Tight overall, though the second sentence packs usage, semantics, and two caveats into one long clause.

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?

Output schema exists so return values need no explanation. The description supplies data source, answer scope, and explicit non-coverage, which is everything an agent needs to call this correctly and interpret the result without overclaiming.

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

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

Schema description coverage is 100% and the single 'service' parameter is fully documented in the schema, so the description adds no syntax or format meaning beyond it. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb (explain) and resource (one service's access) and enumerates exactly what the answer contains: exposure, allow-list enforcement, and uncovered layers. This is clearly distinguishable from sibling read tools like access_log or access_summary.

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 usage context ('use this to answer "who can reach this?" honestly') and a boundary condition (it proves nothing about live tailnet policy or backend authentication). It stops short of naming a sibling alternative for when live-policy answers are needed, so it is clear context without full routing 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?

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), yet the description still adds real context: ordering, a truncation flag, absent payload fields (query strings, headers, bodies), and viewer-scope suitability. It stops short of state-rate/size limits on 'limited', but the additions are substantive rather than restatements.

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 return shape is front-loaded, and the routing sentence follows immediately, so the most decision-relevant facts come first. Five short sentences with minimal waste, though 'The event list is limited; summaries cover all matches' partly re-states the routing already given in the prior sentence.

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 values needn't be explained here, and the safety profile is fully annotated. However, with six entirely undocumented parameters in both schema and description, an agent cannot construct a filtered query (e.g., valid timestamp format for since/until) without guessing, which leaves the definition incomplete for its 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?

Schema description coverage is 0% across six parameters (app, who, limit, since, until, decision), so the description must compensate and largely does not. It never names a parameter, and gives no hint about time formats for since/until, what 'who' accepts, or what the limit's maximum of 10000 means operationally. Only the vague phrase 'all-match counts' implies filtering 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?

States a specific verb and resource ('Return individual local access events') plus ordering ('newest first'), counts, and a truncation flag. It draws an explicit boundary against the sibling access_summary, so an agent can pick between them 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?

'Use access_log to inspect specific events; use access_summary for counts without event records' names the alternative and the exact condition that selects it. The follow-up sentence ('The event list is limited; summaries cover all matches') reinforces the tradeoff so the agent knows when results will be incomplete.

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, it discloses important non-obvious behavior: summaries cover all matches regardless of the event limit, denied events do not advance last allowed access, and query strings/headers/bodies are absent. It also confirms no credentials, network calls, or writes and notes viewer-scope suitability, which adds auth context not present in 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 front-loaded with the core aggregation purpose and then adds usage, behavioral caveats, and privacy notes. It is dense but every sentence contributes; the first sentence is long yet appropriately information-rich.

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 needn't explain return values, and it does cover aggregation behavior and data absence well. However, for a six-parameter tool with no schema descriptions, the missing filter semantics (especially since/until formats and who/app meaning) leave notable gaps 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 description coverage is 0%, so the description must carry the burden for six parameters. It mentions 'event limit' and 'denied events' in passing and references app/login as grouping dimensions, but it never explains the app, who, since, until, or decision filters or their accepted formats, leaving most parameters semantically opaque.

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 (aggregate) and resource (local access events) and enumerates the resulting audit counts and traffic metrics. It clearly distinguishes itself from access_log by contrasting totals/trends with individual events, so an agent can select 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?

It explicitly says when to use this tool versus the sibling: 'Use access_summary for totals and trends; use access_log for individual events.' It also notes suitability for viewer scopes, giving a clear permission context.

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

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

Beyond the annotations, the description discloses key behavior: Funnel publishes to the public internet, the tool writes a registry entry, installs a background service unless no_daemon_install is true, reports installation announcements to stderr, and returns URL/enrollment evidence after setup. It also explains incomplete setup behavior and recipient expiry nuances.

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 dense and somewhat run-on, but it is appropriately sized for a destructive 24-parameter configuration tool. The most important safety warning about funnel and public exposure 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 complex, destructive, open-world tool, the description covers the essential selection, safety, installation, and post-setup behavior. It does not restate every advanced parameter or the existing-entry replacement consequence, but the rich schema and annotations cover those details.

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 high at 83%, so the schema already carries most parameter detail. The description still adds useful cross-parameter meaning for funnel safety, allow/for/until expiry behavior, and daemon installation, though it does not cover all 24 parameters.

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?

Although the tool name 'add' is generic, the description states the specific action: writing a registry entry for a proxy, file, or TCP service on the user's Tailscale network. It also distinguishes the tool from the sibling 'share', so an agent can identify its role.

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 explicitly gives an alternative-selection rule: use this instead of 'share' when the user wants a named configured service rather than a one-shot share. It also adds a clear safety instruction to ask the user before enabling Funnel public exposure.

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 substantial behavior beyond the annotations: the restart is queued asynchronously via daemon reconciliation, 'queued is not evidence that reconciliation finished' warns against treating the response as completion, enrolled identity and other apps are preserved, and there is a role-based permission restriction. None of this is recoverable from readOnlyHint/destructiveHint/idempotentHint.

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?

Four tight sentences, front-loaded with the action ('Queue restart...') followed by side effects, the async caveat, and the permission limit. The telegraphic fragments ('Keeps... does not restart...') are efficient and every sentence carries unique 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?

With an output schema present, return values need not be explained, and annotations already cover the destructive/idempotent profile. The description still supplies the async reconciliation model, side-effect preservation, and the operator restriction, so an agent has everything needed to decide and call correctly.

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 single 'app' parameter has 0% schema description coverage, so the description must compensate. It only clarifies the referent ('this app', 'public Funnel app') without giving identifier format or naming conventions, so it adds partial meaning but does not fully fill the gap.

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: 'Queue restart of this app's TSLink gateway node on daemon reconciliation.' It further sharpens scope by declaring what it does NOT do ('does not restart the third-party app process or install a daemon'), which separates it from the many other app/lifecycle siblings.

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 clear when (queue a restart that daemon reconciliation will pick up) and an explicit when-not ('Reduced operators cannot restart a public Funnel app'). It does not name a sibling alternative, so it falls short of the full 5 but leaves no ambiguity about applicability.

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 read-only, idempotent, non-destructive, and closed-world, and the description still adds substantial context: operations are credential-free and bounded, redirects are never followed, non-loopback addresses are never probed, and results exclude auth/health verification. That is above and beyond the structured hints.

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, zero filler. The core capability is front-loaded and each following clause adds a distinct boundary or output note.

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 need not be explained, yet the description still notes that confidence and already-registered services are returned. Safety profile, scope restrictions, and limits are all covered.

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 is no parameter surface for the description to clarify. Schema coverage is listed at 100%, leaving nothing to compensate for.

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 ('Discover local listening TCP services') plus the mechanism ('credential-free, bounded loopback HTTP fingerprints'). No sibling tool in the list does local service discovery, so the agent can select it unambiguously.

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 bounds behavior clearly (no redirects, no non-loopback probes) but gives no explicit when-to-use framing or routing to alternatives such as 'health' or 'doctor' for verification tasks. 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 cover readOnly, idempotent, non-destructive, and openWorld, so the bar is lower. The description still adds real value beyond them: it enumerates what is inspected (local config, registry, credentials metadata, runtime state), states it writes nothing, and discloses the non-obvious error behavior — returning health_exit_code instead of failing.

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, then the trigger, then the behavioral guarantees. Every clause carries information; nothing is padded or repeated from 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?

An output schema exists, so return values need not be re-explained, and the description still names the output shape (findings by severity, health_exit_code). For a non-destructive, single-optional-parameter diagnostic tool, an agent has everything needed to call it.

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 only one optional boolean that is fully documented in the schema itself. The description adds no syntax or semantics 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?

States a specific verb+resource: run local TSLink diagnostics and return findings by severity. It also distinguishes itself from the sibling `status` tool by noting it is the deeper fallback when status was not enough.

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 trigger ('when a share or URL is not working and status was not enough') and names the alternative (`status`) that no longer suffices. The single parameter's own schema adds the condition for reaching out externally.

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 readOnlyHint=false, but the description adds real context the annotations cannot: regrant=true is required to revive expired access, Funnel regrant re-enables public internet exposure, and changes touch local state only with no invitations, live tailnet calls, or access-log dependency. It stops short of saying precisely what a reset destroys in terms of the prior deadline record, which keeps it off a 5.

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 action and scope, then alternatives, then edge cases; nearly every sentence carries operational meaning. The phrasing is dense and occasionally run-on ('using for from the operation time or an absolute until'), which slightly hurts scanability.

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 destructive, non-idempotent mutation with an output schema (so return values are already covered), the description supplies purpose, routing, prerequisites and the regrant edge case. The remaining omissions are the meaning of 'service' and 'ack_never' — minor against a largely complete picture.

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 low at 33% (only 'for' and 'until' are described), so the description must compensate, and it largely does — it explains 'who' (person grant for service; omit for Funnel), 'for' vs 'until' as relative vs. absolute, and the meaning of regrant for both grant and Funnel cases. 'service' and 'ack_never' remain unexplained in the description, leaving a partial gap.

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 — reset/extend an existing person-app grant or acknowledged Funnel deadline — with the scope of extension or shortening. It explicitly distinguishes itself from the sibling people_grant (change vs. create), so an agent can route 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 explicit alternatives and selection rules: 'use extend to change an existing deadline; use people_grant to create a person-app grant', plus 'who selects the person grant for service; omit who for Funnel, which is owner-only'. It also adds a prerequisite ('Confirm target and duration with the owner') and exclusions ('revoked people cannot be revived').

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 basic safety flags (readOnly false, destructive false), and the description adds substantial context beyond them: owner-only restriction, the bearer link being hidden unless print_link is true and only retrievable at creation, the public-acknowledgement requirement, no result from remote API calls, and visitor auth needs.

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

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

It is a dense single block but front-loads the owner-only scope and core action before secondary caveats. Every clause carries information, though the sentence packing slightly reduces scannability.

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?

Although an output schema exists, the description still summarizes the return (grant metadata, recipient message, configured edge state) and covers auth prerequisites, the visitor exemption, and the live-Funnel caveat, leaving nothing critical for correct invocation unstated.

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 50%, so the description must compensate, and it partially does by explaining print_link behavior and the public/Funnel exposure. However, it adds little meaning for app, pin, or label, leaving half the parameters to the schema alone.

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: creating a time-limited browser guest grant for one proxy app, including gate configuration and Funnel exposure. It also explicitly distinguishes itself from the sibling guest_show, so an agent can route correctly without opening schemas.

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 names the alternative explicitly ('Use guest_create for a new link; guest_show cannot recover an existing token') and gives the condition that selects each. It further directs the agent to 'check status separately for live Funnel availability', providing when-to-use and where-not-to-look 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?

Annotations already declare read-only, idempotent, non-destructive and closed-world, but the description adds substantive context beyond them: owner-only authorization, reading from local state, that the grants array excludes bearer tokens and secret hashes, that no remote API calls occur, and that it does not verify live Funnel availability. It also notes visitors need no OIDC or tailnet account.

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 with the owner-only constraint and the read scope front-loaded, followed by sibling routing and behavioral caveats. Every clause carries information an agent needs.

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 detail is optional, yet the description still notes the shape and the deliberate omission of secrets. Authorization, data source, side-effect profile and the non-verification caveat are all covered.

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 is nothing for the description to disambiguate. No parameter-level meaning is added or needed.

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

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

States a specific verb and resource ('read all browser guest grants from local state') and enumerates what is included: expiry, revocation status and use counters. It also names the sibling it is not, guest_show, so an agent can route 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?

Explicitly routes usage: 'Use guest_list to find grant IDs across apps; use guest_show to inspect one known ID.' This is a clear when-to-use plus a named alternative with the condition that selects it.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds material context the annotations cannot convey: revocation is irreversible with these tools, it does not remove the app or disable Funnel configuration, it returns no bearer tokens, it makes no remote API calls, and it does not verify live Funnel availability. That is a genuinely rich behavioral profile beyond the structured hints.

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 permanent-state and owner-only constraints are front-loaded, and every sentence carries a distinct fact. It is on the dense side and slightly overloaded with caveats, but there is no filler or repetition of the title.

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 values need not be enumerated; the description still adds the useful note that grant metadata is returned and no bearer tokens are included. Combined with the irreversibility and no-remote-call notes, an agent has everything needed to invoke this correctly.

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 has only one parameter at 0% description coverage (a bare string with minLength 1), so the description must carry the burden. It partially compensates by implying the ID identifies a single grant and by specifying failure behavior ('unknown IDs return not_found'), but it never states what kind of ID this is or where to obtain it (guest_list/guest_show). Partial coverage, not full.

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 ('permanently mark one browser guest grant revoked in local state') and explicitly differentiates from the two nearest siblings: 'guest_show only inspects it, and guest_create issues a new grant.' An agent can distinguish this from every guest_* sibling without reading 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?

It gives an explicit selection rule ('Use guest_revoke to deny further use of one link') plus named alternatives (guest_show for inspection, guest_create for issuing new grants), so the when-to-use vs when-not-to-use decision is fully specified rather than inferred.

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 cover read-only/idempotent/non-destructive/closed-world, and the description still adds substantial behavior: owner-only auth requirement, not_found on unknown IDs, no remote API calls, no bearer token recovery, no live Funnel verification, and that visitors need no OIDC or tailnet account. This goes well beyond the 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?

Front-loaded with the owner-only constraint and the core action, and every clause adds a distinct fact (scope, error case, alternatives, limits). The multi-clause semicolon structure is dense but not padded; a slight reduction in length would improve scanability.

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 shape need not be spelled out, yet the description still summarizes what is returned. With annotations, error semantics, auth requirement, and adjacent tools all covered, an agent has everything needed to invoke this correctly.

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 0% for the single 'id' parameter. The description identifies it as a browser guest grant ID and defines the error case for unknown IDs, but adds no format, prefix, or ID-source detail (e.g., where to obtain the ID beyond guest_list). Baseline-minimal parameter meaning.

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 (look up) and resource (one browser guest grant by ID) plus the scope of the return (metadata, expiry, revocation status, use counters). It explicitly contrasts itself with the sibling guest_list, so an agent can route correctly without opening a 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 explicit when-to-use: guest_show for one known grant, guest_list to discover IDs, guest_create to make a new link. Prerequisites (owner-only) and a boundary condition (does not verify live Funnel availability) are stated outright.

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

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

Annotations already establish readOnly, idempotent, non-destructive and closed-world behavior. The description adds a genuine trait beyond them: that the read is passive and does not probe nodes or mutate configuration, which matters for an agent deciding between this and an active diagnostic.

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 front-loaded sentence with no filler; the scope of the read and its non-invasive nature are both stated immediately.

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 values need no explanation, and a zero-parameter read tool has no prerequisite or auth detail to carry. What it reads is stated; only the relationship to sibling diagnostics is left implicit.

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 per the baseline a 4 applies. With zero inputs there is no parameter semantics for the description to add 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?

The description gives a specific verb ("Read") and resource ("app health and node expiry observations"), which is more precise than the bare name "health". It does not name a sibling tool, but the "without probing" clause implicitly separates it from diagnostic tools like doctor.

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 "without probing or changing configuration" implies when to prefer this over a probing/diagnostic tool, but it never names an alternative (e.g. doctor) or states an explicit when-to-use condition. Usage is inferrable 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?

Goes well beyond the annotations (which only declare non-read-only, idempotent, non-destructive). It discloses transactional single-write semantics, precisely what is preserved (access lists, tags, people scope, portal routes, enrolled node, no re-enrollment), how omitted/empty/zero values behave, reset semantics, and an authorization requirement verified in the write transaction.

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?

Tight and front-loaded, leading with the core mutation and transaction scope before edge-case rules. It is information-dense with near-zero waste, though several concepts (defaults, reset, proxy-only fields, auth) are packed into few sentences.

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?

Annotations carry the safety profile and an output schema exists, so return values need not be described. The description fills the remaining behavioral gaps — preservation guarantees, default/reset rules, proxy scoping, and owner auth — leaving nothing an agent needs to call it correctly.

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

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

With 88% schema coverage the baseline is 3, but the description adds real meaning: omitted fields retain stored value, empty/0 selects the default, reset restores defaults, and path/status-range/body_contains are proxy-only. That scoping and default logic is not fully derivable from the schema alone.

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 — changing one app's health check — and scopes it to a single registry transaction, which contrasts implicitly with the read-only 'health' sibling. It is clear what the tool does, though it never names the sibling explicitly to seal the 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?

Usage conditions are implied by 'Change only one app's health check' versus the read sibling, and preconditions are present ('Owner scope only', owner required for routed apps). However, it never explicitly says when to reach for this over alternatives like 'health', leaving selection 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 only declare the generic mutation profile (readOnly=false, openWorld=true, idempotent=false); the description adds the genuinely non-obvious effects: a real email leaves the system, a created grant has no expiry, an existing grant keeps its deadline, and an expiring binding yields 24h or a refusal. It also discloses the allow_exit_node config gate, which the annotations do not cover.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful context that it calls the Tailscale API and sends nothing, and it interprets the complete=false result as meaning at least one device could not be checked.

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 compact sentences with no wasted wording. It front-loads the purpose, then gives the key usage guidance, then explains the complete=false flag.

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 output schema exists, annotations are rich, and the single parameter is fully documented in the schema. The description covers the remaining agent-relevant behavior: when to use it, that it sends nothing, and what complete=false indicates.

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

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

Schema description coverage is 100%, and the single show_urls parameter is already documented in the schema, including the redaction warning. The description does not mention show_urls or add meaning beyond the schema, 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 states a specific verb and resource: it lists open tailnet user invitations and TSLink-owned device invitations. It also distinguishes the tool from sibling invite_revoke and invite_resend by framing it as the lookup step before those mutations.

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 explicitly says to use this before invite_revoke or invite_resend to find an invite id, naming the relevant alternatives and the condition that selects this tool. It also clarifies that the tool reads the Tailscale API and sends nothing, reinforcing when it is appropriate.

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

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

Annotations already declare readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds meaningful context beyond those: this actually sends a real email (an external side effect), requires user confirmation, and only applies to a subset of invitations. It does not, however, say anything about rate limits, duplicate-resend behavior, 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 short sentences, each doing distinct work: the core action plus confirmation warning is front-loaded, followed by the eligibility constraint and the id-lookup pointer. 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?

With annotations covering the safety profile and an output schema covering return values, the description fills exactly the remaining gaps: side-effect disclosure, confirmation requirement, eligibility precondition, and parameter provenance. 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%, so the schema already documents the kind enum and invite_id. The description adds provenance for invite_id ('Use invite_list to find the id'), which is mildly useful, but does nothing for the kind parameter. Baseline 3 applies when the schema carries the load.

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 ('Sends another real invitation email to the original recipient') with clear scope. It explicitly distinguishes the eligible case (a Tailscale-emailed invitation) from the ineligible one (print_link), so an agent can tell it apart from siblings like invite_user or invite_revoke.

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 clear precondition ('only works for an invitation Tailscale emailed; a print_link invitation has no recipient to email') and a pointer to invite_list for obtaining the id. It even calls out the need to confirm with the user first. It stops short of naming the alternative tool to use for the print_link case, so it is not a full when/when-not/alternatives statement.

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?

Goes beyond the annotations by disclosing irreversibility ('cannot be un-revoked') and a user-confirmation requirement, which the destructiveHint/idempotentHint flags alone do not convey. This is exactly the extra context that raises confidence for a destructive, open-world mutation.

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 sentences, front-loaded with the confirmation caution, then the irreversibility consequence, then the id-lookup pointer. Every sentence carries distinct, actionable information 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?

With an output schema present and annotations covering the safety profile, the description fills the remaining gaps: irreversibility, confirmation, and how to obtain the required id. Nothing needed 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 description coverage is 100%, and the enum values for 'kind' are documented in the schema, so the baseline is 3. The description adds a minor provenance pointer ('from invite_list') but no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource: 'Cancels a real outstanding invitation on the user's tailnet.' This clearly identifies the action and scope, distinguishing it from the many other revoke/list siblings (guest_revoke, people_revoke, invite_list) 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?

Explicitly instructs to 'confirm with the user before calling this' and directs the agent to 'Use invite_list to find the id,' covering both the caution and the precondition. It also states the alternative for reversing course ('issue a new one instead'), so when/when-not is fully specified.

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?

Goes far beyond the annotations: it warns that a real email is sent, discloses that elevated roles are refused with the specific error mcp_elevated_invite_refused with the config gate (mcp.allow_elevated_invites), and notes the bearer URL grants access to anyone holding it. These are non-obvious behavioral facts an agent cannot infer from the structured 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?

Front-loads the key warning (real send, confirm first) and each subsequent sentence carries distinct information (print_link alternative, elevated-role gate, self-service fallback). No filler sentences.

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 and an output schema, the description supplies everything an agent needs: the write consequence, the permission gate, and the alternative delivery path. Return-format concerns are already covered by the output 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?

Schema coverage is 100%, so the baseline is 3; the description adds meaning beyond it by tying role elevation to the refusal/opt-in behavior and explaining that print_link returns a bearer URL that bypasses email delivery. Marginally redundant with the schema on print_link but genuinely additive on role.

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 concrete verb and resource ('Sends a real Tailscale invitation to a real email address') and scopes it to joining the user's tailnet. This distinguishes it from device-invite (invite_device) and existing-member management siblings without needing the schema opened.

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 clear precondition ('confirm the address and role with the user before calling this') and an explicit variant for print_link. It does not name a sibling alternative (e.g., invite_device vs people_add) for the nearest overlapping cases, so it stops short of full 5-level when/when-not routing.

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=false, so the safety profile is fully covered. The description adds the 'locally registered' scope and the tri-state Funnel reporting (requested/active/reason), which is useful, but no output schema is needed to explain return values since one exists.

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, no filler, and the core capability is front-loaded before the usage guidance. Every clause earns its place by specifying scope, contents, and purpose.

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 listing tool with an output schema and full annotation coverage, the description supplies everything an agent needs: what is listed, what state fields appear, and why to call it. Nothing material 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 of 4 applies per the rubric. There is no parameter syntax the description could add meaningfully.

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

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

States a specific verb (list) and resource (locally registered TSLink services) and enumerates what the listing contains: exact runtime URLs and Funnel requested/active/reason state. This differentiates it reasonably well from siblings like status and url, though no sibling is named explicitly.

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

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

Provides clear usage context with two concrete triggers: discovering current shares and verifying whether public exposure actually activated. It does not state when NOT to use it or name an alternative sibling (e.g. status, url), which keeps it 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 readOnly/idempotent/non-destructive, and the description goes well beyond them: it discloses read-only file access, that the return is a bounded recent window rather than the full file, and that credentials, Tailscale login/invitation URLs, and email addresses are redacted before return. These are exactly the safety-relevant behaviors an agent needs and cannot get from structured 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?

Two sentences, purpose front-loaded, then usage and behavior. Every clause carries information (read-only, windowing, redaction categories) with no filler or repetition of the title.

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 still covers purpose, when-to-use, alternatives, and safety behavior. Nothing an agent needs in order to call this 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% and the schema is unusually rich (per-parameter guidance, defaults, enum meanings, the 'widen only after the default window came back empty' advice). The description adds no parameter-level detail, so the baseline of 3 applies even though the schema itself is excellent.

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 ('Read recent lines from the local TSLink daemon log') with a scope qualifier ('recent window rather than the whole file') that separates it from the many other diagnostic siblings. An agent can tell this apart from status, doctor, or access_log 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 names the escalation condition ('Use this when status and doctor did not explain a failure') and the two alternative tools to try first. This is a clear when-to-use plus alternatives, leaving nothing 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?

With readOnlyHint and idempotentHint already present, the description still adds meaningful behavioral context: owner-only authorization, stable results, exclusion of raw arguments, links, and tokens, and the important caveat that a started entry without completion means the outcome is unknown. This goes beyond the annotations without contradicting them.

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 compact clauses with no wasted words. The key properties are front-loaded, and the incomplete-entry caveat is stated directly and efficiently.

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 tool with annotations and an output schema, the description covers authorization, result stability, content exclusions, and how to interpret incomplete entries. It does not clarify routing relative to similar log-oriented siblings, but the structured fields otherwise make it sufficiently 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 tool takes zero parameters, so there are no parameter semantics to describe. Per the evaluation 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 identifies a specific resource and scope: an owner-only durable mutation journal. However, it phrases this as a noun fragment rather than an explicit verb, and it does not directly distinguish the tool from siblings like logs or access_log. The title supplies the missing verb, but the description alone is clear rather than fully self-contained.

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 'owner-only' constraint and 'mutation journal' resource imply the tool is for owners auditing mutations, but there is no explicit when-to-use guidance or named alternative among siblings such as access_log or logs. Usage is left to inference from the resource scope.

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, the description discloses important behavioral traits: new grants default to 24h, omitted deadlines are preserved, ack_never is not required for members and device-invited guests, failures retain local state and return incomplete, bearer links are hidden unless print_links is true, and unknown POST outcomes require reconciliation. These are exactly the kinds of operational details an agent needs for a destructive, non-idempotent, open-world mutation.

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 front-loaded with purpose and nearly every clause carries relevant information. However, it is a single dense paragraph with semicolon-heavy jargon and compressed operational rules, which makes it harder to scan than it needs to be.

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 values need not be explained. The description covers authorization, invitation behavior, failure semantics, lifetime defaults, destructive constraints, and reconciliation guidance; the main remaining gap is the format of the who parameter.

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 67%, and the description adds useful semantic detail beyond the schema for apps, lifetime defaults and omission behavior, ack_never exceptions, and bearer-link visibility. It does not explain the who identifier format or the QR/invite fields in depth, but those are partly covered by 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?

The description states a specific verb and resource: granting private HTTP/file apps to a person, with additive grant semantics. It is clear what the tool does, but it does not explicitly name sibling alternatives such as people_grant, people_update, or share, 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?

It provides meaningful usage context: explicit add can restore a revoked person, members need no invitation while outsiders accept one, owner authority is required, and TCP/public apps are refused. It stops short of explicitly naming when to use this over sibling tools like people_grant or share.

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 annotations, it discloses external Tailscale contact, device share creation, writer-lock checks, owner-authority requirements, and error behavior with retained data. The explanation is useful but somewhat jargon-heavy and leaves some mechanics opaque.

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 purpose is front-loaded, but the remaining text is dense and sometimes grammatically awkward. It is not bloated, yet several clauses are cryptic and could be tightened or restructured for clarity.

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 complex mutation with an output schema and rich annotations, it covers important behavioral context such as authority, external calls, lock behavior, and error handling. However, it leaves key parameter semantics unclear, so an agent still lacks complete guidance for invoking it correctly.

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 only 25%, and the description does not compensate: it never explains the format or meaning of who and app, and ack_never is mentioned cryptically without explaining when or why to set it. It adds only partial context for the for parameter, largely repeating schema constraints.

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 action and resource: granting one person's private HTTP/file app while preserving other grants and revocations. It is clear enough to distinguish from broad sharing tools, though the phrasing is awkward and it does not explicitly contrast with siblings like share or invite_device.

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 some usage context—new people, routes, and external sharing require owner authority, and globally revoked people are not restored—but it does not explicitly say when to use this tool instead of sibling tools such as share or invite_device. The guidance is implied rather than direct.

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, idempotentHint, destructiveHint=false, and openWorldHint=false. The description adds non-obvious behavior context beyond those flags: it reads from local files, requires no credential, and sends no invitations, which usefully clarifies auth and side effects.

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 exactly what data is read, followed by the operational constraints. There is no filler or redundancy, and every clause addresses what an agent needs to know.

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

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

For a zero-parameter read-only tool with an output schema and rich annotations, the description supplies the missing runtime context: local file source, no credential requirement, and no side effects. It is complete enough to call correctly, though it omits explicit routing guidance to sibling tools.

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 and 100% schema description coverage for an empty object, so there is no parameter meaning for the description to add. Baseline 4 for zero-parameter tools 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?

States a specific read verb and enumerates the resources returned (people, app grants, absolute deadlines, revocation tombstones) plus the data source (local files). The phrase 'writes nothing' implicitly distinguishes it from write siblings such as people_grant and people_revoke, so an agent can identify this as the read-only listing tool.

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 scopes the tool by stating no credential is needed and that it sends no invitations or writes, which implies a safe read-only use case. However, it never explicitly says when to choose this over siblings like list or people_grant, leaving usage 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 destructive/openWorld/idempotent, but the description goes well beyond them: a retained deny tombstone, no token needed for local denial vs. a user-owned API token for remote cleanup, deferred or partial work surfaced in complete/cleanup, retry resuming cleanup, accepted network shares possibly remaining, and TCP/Funnel and in-flight streams being outside enforcement. This is exactly the extra side-effect and partial-success disclosure that annotations cannot carry.

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?

It is front-loaded with the action and the confirmation warning, and nearly every sentence carries distinct information. The cost is heavy jargon ('deny tombstone', 'owner-verified reconcile_invites app=id') that makes the later sentences hard to parse on first read.

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 destructive, token-gated operation with an output schema present and safety annotations already supplied, the description covers the behavioral edge cases (partial work, retries, tombstones, unenforced transports) well. The main gap is that it does not position the tool against its near-identical sibling people_revoke.

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 0% for 2 parameters, so the description must compensate. It partly does for reconcile_invites (owner-verified, app=id or app=none, tied to unknown POSTs with remote listing) but leaves the shape and semantics of the nested object vague, and says nothing about 'who' beyond the obvious person reference.

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: it 'revokes a person locally across private HTTP/file services' and cleans up pending device invitations, so the core action is unambiguous. However, it never distinguishes itself from the very close sibling people_revoke (nor people_grant/guest_revoke), so an agent cannot tell from the text which removal tool to pick.

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 an operational directive ('confirm with the user before calling') and conditional triggers for retry and for reconcile_invites on unknown POSTs, which is useful context. But it names no alternatives and gives no explicit when-not guidance relative to people_revoke or the other revoke/remove siblings, leaving selection 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?

Goes well beyond the annotations (destructive/idempotent/not-readOnly). It discloses an important side effect (a previously unscoped app becomes people-scoped, denying ungranted callers), what is preserved (other grants and invitations), a limitation (cannot clear an owner revocation), and scope of change (local state only, no network invitation; accepted shares and in-flight streams survive). This is exactly the extra context a destructive mutation needs.

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

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

Front-loaded with the core action and return value, then routing, then edge cases. Dense but nearly every sentence carries operative information; only marginally overpacked.

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 destructive, side-effecting mutation, it covers routing, no-op conditions, scoping side effects, preserved state, and irreversibility. With an output schema already documenting the return, nothing material is missing 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 0%, so the description must carry the parameters. It maps 'who' to a person/login ('An unknown login is a no-op') and 'app' to a private HTTP/file app, which adds some meaning, but it gives no format or identifier specifics beyond that.

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 (deny/revoke), resource (one person's access to one private HTTP/file app), and scope (single person, single app), and explicitly distinguishes itself from people_remove (across apps) and people_grant (allows). An agent can select it correctly without opening any sibling 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?

Directly routes between alternatives: 'Use people_revoke for one app; people_remove revokes the person across apps, and people_grant allows one app.' It also states edge-case behavior (unknown login = no-op) so the caller knows when nothing happens.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true), the description adds substantial behavioral context: retained app services, grants, owner/admin identities, and local node state; the daemon closing portal and route listeners; the gateway-mode owner check in the registry transaction; and the access_request_owner_required error. This is exactly the kind of consequence-level detail annotations cannot convey.

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 front-loaded with the core action and packs several useful facts into compact sentences. It is dense but each sentence contributes a distinct fact (requirement, retained state, daemon behavior, exclusions), with only minor room for trimming.

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

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

Given zero parameters, an output schema, and annotations covering the safety profile, the description is complete enough for correct invocation. It covers preconditions, side effects, retained state, and the relevant error case, leaving no obvious operational 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 there is no parameter semantics to explain and the baseline is 4. The description does not need to compensate for schema gaps, and its explanation of the owner requirement is about access control rather than input arguments.

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 opens with a specific verb and resource ("Disable the home portal") that is immediately distinguishable from its sibling portal_enable. It also scopes the operation by naming what is preserved and what the daemon does, so the agent knows exactly what 'disable' means here.

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 through the gateway-mode owner requirement and the explicit error code, but it never states when to choose this tool over alternatives or any conditions under which it should not be used. A reader can infer the intent from the name and sibling set, but explicit routing guidance is 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?

Beyond annotations, it discloses important behavior: owner/admin identity preservation, first-enrollment owner caveat, HTTP MCP owner-required error, pending-result semantics, hot reloading, and unchanged grants/service registrations. These details materially improve safe invocation and are consistent with the 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 front-loaded with the core action and every sentence carries operational meaning. It is dense and somewhat semicolon-heavy, but justified by the complexity of the tool and the number of important caveats.

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 complex mutation with an output schema, it covers the major operational concerns: authorization, bootstrap/recovery, owner semantics, hot reload, pending status, outside-tailnet prerequisites, and explicit exclusions. Little needed for correct invocation 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 only 57%, but the description compensates by explaining owner/admin identity semantics, first-enrollment owner behavior, admin permissions, funnel refusal, and gateway defaults. It does not cover every parameter (e.g., hostname), so it is strong but not complete.

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 first sentence states a specific verb and resource: enabling an independent Tailnet-only home portal. It also names key scope/default behavior (gateway mode) and exclusions (Funnel refused), making the tool distinguishable from portal_disable and related portal 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?

The description gives clear usage context and several exclusions: local CLI/stdio is the bootstrap/recovery path, remote owner claiming is impossible, and the tool does not install/restart the daemon, send invites, or change tailnet ACLs. It stops short of explicitly routing the agent to sibling tools such as portal_disable or portal_route_add.

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 (idempotent, non-destructive, non-readonly), the description discloses key behavioral traits: it makes the app people-scoped, HTTP MCP requires the current portal owner checked in the write transaction, and the same-origin gate defaults on. It also clarifies what the tool does not do (invite people, restart the gateway node). It stops short of describing existing-route handling or error behavior, but annotations already cover idempotency and safety.

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 five tight sentences, front-loaded with the core purpose and followed by scoping, auth, default, and exclusion details. Every sentence adds useful information without 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 mutation tool with an output schema and annotations covering idempotency and safety, the description supplies the important prerequisites, defaults, side effects, and exclusions an agent needs. The main remaining gaps are explicit sibling routing (list/remove) and clearer parameter semantics for app and port.

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 only 33%, so the description should compensate. It gives meaning to the app and port concepts ('private HTTP or file app on a stable gateway port') and reinforces the allow_cross_origin default ('same-origin gate defaults on'), but it does not explain the expected format of the required app identifier or how port selection works, leaving meaningful gaps.

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 action and resource: routing a private HTTP or file app on a stable gateway port, and making the app people-scoped. It is clearly not a generic 'add' and its exclusions ('does not invite anyone or restart the gateway node') differentiate it from adjacent sibling actions, though it does not name specific sibling tools like portal_route_list or portal_route_remove.

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 by 'Route a private HTTP or file app on a stable gateway port' and strengthened by the exclusions ('Does not invite anyone or restart the gateway node'). However, it never explicitly names the alternative tools (portal_route_list, portal_route_remove) or states when to choose this tool versus other portal tools, leaving routing guidance 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 readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered; the description still adds real context beyond them — that it reads only local configuration and runtime evidence, performs no writes/enrollment/remote API calls, and only reports routes proven by current runtime evidence. That last clause usefully warns results may be incomplete/stale if runtime evidence is absent, which no annotation conveys.

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

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

Two sentences, front-loaded with the action and its output, followed by usage contrast and scope limits. Dense but every clause carries information; only the slightly convoluted 'only when current runtime evidence proves them' phrasing costs it a point.

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, rich annotations, and an output schema already present, the description covers everything an agent needs: what it reads, what it returns, what it does not touch, and which siblings to use for changes.

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 to disambiguate and the baseline of 4 applies. The description correctly avoids inventing filtering options that do not 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?

States a specific verb and resource ('Read the home portal and its configured gateway routes') plus the concrete return payload (app names, stable ports, route states, exact URLs). It also names the mutation siblings, so an agent can distinguish this read tool from portal_route_add/portal_route_remove 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 'Use portal_route_list to inspect existing routes' and contrasts it with the two mutating siblings that 'change routing'. That gives a clear selection rule, though there is no explicit when-not or precondition (e.g., portal must be enabled) to reach the top tier.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, so the description earns credit for adding what they don't: a refusal case for portal-only apps and an authorization requirement (current portal owner in the write transaction for HTTP MCP). These are exactly the operational constraints an agent needs before invoking a destructive 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?

Three short sentences, zero filler, and the core action is front-loaded ahead of the refusal rule and the auth note. Every sentence carries distinct 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?

Output schema exists so return values needn't be explained, and safety traits are annotation-covered. The description covers the refusal case and auth requirement; the only real hole is the unresolved identifier format for the app parameter.

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 0% for the single required parameter, and the description never clarifies what "app" accepts — a name, slug, numeric ID, or domain. With only minLength:1 in the schema, the agent has no way to construct a valid value from the definition alone.

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: "Remove an app's gateway route." That is clearly distinct from the add/list route siblings without needing to name them. It stops short of explicitly contrasting with portal_route_add or portal_route_list, so it lands at 4 rather than 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?

Gives an explicit exclusion plus the correct alternative: "Refuses portal-only apps; remove the app instead." That is real when-not guidance. What's missing is any positive precondition (e.g. when a route exists vs. when to use portal_disable), so it isn't a full 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?

Adds real behavioral context beyond annotations: the Funnel refusal policy for never-public apps unless force_unsafe_public and public_ack are accepted, that omission leaves existing names unchanged, and the explicit non-goal of configuring/installing/probing the app. Some of this (public_ack/force_unsafe_public coupling) is echoed in the schema, and permission/auth requirements are not stated, so it falls short of a 5.

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 action, followed by alternatives, return summary and safety boundary in compact sentences. Dense but nearly every clause carries weight; the return-value sentence is partly redundant given the output schema exists, which keeps it from a 5.

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 16-parameter, nested-object, mutation-style tool with an output schema and rich annotations, the description covers scope, routing, return shape and the key safety policy. It stops short of clarifying several untyped/undocumented parameters (ephemeral, no_auto_provision, control_url), leaving some gaps in an otherwise complete picture.

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 63%, so most parameters already carry their own defaults, ranges and semantics. The description speaks only generically of 'supplied overrides' and touches a few flags (no_daemon_install, funnel, force_unsafe_public), adding no syntax or meaning beyond schema text; undocumented params like ephemeral, no_auto_provision and control_url are left unexplained in both places.

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 ('Register one app-specific recipe with the supplied overrides, then ensure the background service') and draws hard boundaries: 'template_apply registers a fixed multi-service stack instead' and 'Does not configure, install or probe the third-party app.' An agent can distinguish it from template_apply and recipe_plan 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?

Explicitly sequences it after another tool ('Use recipe_apply after reviewing recipe_plan') and names the alternative plus the condition that selects it ('template_apply registers a fixed multi-service stack instead'). When/when-not routing is fully specified.

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=false, so the safety profile is covered structurally. The description adds genuine context beyond them: it reads the built-in catalog only and neither probes apps nor mutates the registry, which tells the agent results are static and cheap. It stops short of describing pagination or size limits, so it is not a full 5.

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 return content and followed by the routing guidance. The enumerated contents list is long but each item is substantive rather than filler; slight density is the only cost.

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, yet it still characterizes what the catalog contains and explicitly rules out side effects. For a zero-parameter, read-only catalog tool, nothing needed for correct invocation is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline for a no-parameter tool is 4. The description correctly avoids inventing filter arguments that do not 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?

States a specific verb and resource ('Return the versioned catalog of app-specific recipes') and enumerates the concrete contents (IDs, ports, WebSocket requirements, health paths, snippets, safety levels, docs). It explicitly distinguishes itself from recipe_plan and template_list, so an agent can route 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?

Gives an explicit ordering rule ('Use recipe_list to choose an app recipe before recipe_plan') and names the alternative for a different need ('template_list offers fixed multi-service stacks instead'). When-to-use and when-to-use-something-else are both present.

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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower; the description still adds real value by disclosing the return payload shape and the negative capability that it does not probe the app or prove authentication. It stops short of noting that the preview is purely advisory and that overriding fields like force_unsafe_public are honored only later at apply time.

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: purpose and payload first, routing/second-opinion second, boundary third. No restatement of the title or filler, and each sentence carries distinct 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 16-parameter preview tool with an output schema, the description covers purpose, sequencing, alternative, and negative capability, which is enough to call it correctly. It is slightly thin on how overrides interact with recipe defaults, but the output schema carries the return contract.

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-related statement is 'with the supplied overrides,' which does not explain any of the 16 parameters. With schema description coverage at 63% and several params (ephemeral, control_url, no_auto_provision, no_daemon_install) carrying no schema description at all, the description does not compensate for the gap, but the well-documented majority keeps this at 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?

States a specific verb (Preview) and resource (one app-specific recipe), then enumerates the returned artifacts: requested/effective service configurations, create-or-skip action, owner advice, safety warnings. It explicitly distinguishes itself from both recipe_apply and template_plan, so an agent can pick it without opening a 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?

'Use recipe_plan before recipe_apply to review without writes' gives the sequencing rule, and 'template_plan previews a fixed multi-service stack instead' names the alternative with the condition that selects it. The closing negative ('Does not probe the app or prove its authentication') tells the agent what this tool will not substitute for.

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 and idempotentHint, but the description adds substantial context beyond them: exact retries replay while stale or differing decisions conflict, other app grants are preserved, a revoked person is never revived, and persisted member/guest lifetime policy applies. The role-based privilege rules and the guest maximum retention rule are behavioral facts that exist nowhere in the structured 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?

The actor, action and scope are front-loaded, and the remaining clauses each carry distinct information (idempotency semantics, grant preservation, out-of-scope work). It is dense and clause-heavy rather than wasteful, though a few packed sentences could be split for scanability.

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 destructive, role-gated mutation this is nearly complete: authorization rules, scope ceiling, idempotency and conflict behavior, and explicit non-goals are all covered, and an output schema means return values need no prose. The remaining gap is operational plumbing — where the request id comes from and what ack_never actually signals.

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 only 33%, so the description has to compensate. It does help on the lifetime parameter ('within the scope maximum and binding expiry', 'select its duration in one action') and touches ack_never ('never requires ack_never for members and device-invited guests'), but the required 'id' parameter is never explained — the description gives no hint that it is a request identifier obtained elsewhere — and ack_never's actual effect remains unstated.

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 opens with a specific actor, verb and resource: 'Current portal owner ... approve one in-scope request', plus the scope and duration constraints that distinguish a grant decision from other mutations. It never names the directly competing siblings (requests_deny, requests_list), so the differentiation is implied by the verb rather than stated.

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 clearly sets preconditions for use: caller must be the portal owner or people-manager, the request must be in scope, and the role determines whether an unknown person can be created. However, it never routes the agent to requests_deny for refusals or requests_list for discovering the request id, and it states exclusions ('no invitations or remote tailnet calls') without saying which tool does handle those.

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?

Goes well beyond the annotations: it discloses retry semantics ('exact retries replay'), conflict behavior on divergent or stale decisions, the authorization role required, and that the reason is surfaced to the visitor. The annotations only assert idempotent/destructive hints; the description explains what those mean operationally and adds the visitor-visibility consequence.

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 dense sentence with the actor and action front-loaded, followed by retry/conflict semantics. Every clause adds distinct information; nothing is 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 an output schema present, return values need no explanation, and the description covers authorization, idempotency, conflict, and reason visibility. The main omission is any hint of what 'in-scope' means or what a conflict response requires the agent to do next, which leaves a small operational 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 0%, so the description carries the burden; it does clarify that 'reason' is optional, capped in spirit by 'short', and visible to the visitor, which is meaningful beyond the bare string/maxLength schema. However, 'id' is left entirely unexplained, so the description only partially compensates for the coverage gap.

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 ('deny an in-scope request') plus the acting role, which cleanly separates it from the sibling requests_approve and requests_list. An agent can pick this tool 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?

Gives a concrete precondition ('current portal owner, owner or people-manager role') and scope ('in-scope request'), which is real when-to-use guidance. It stops short of explicitly contrasting with requests_approve or stating when denial is inappropriate, so it is clear context rather than full routing.

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 description adds genuinely non-obvious behavior: 'Listing may persist expiry/retention,' which explains why the tool carries readOnlyHint=false despite being a list operation — exactly the kind of side effect annotations alone can't convey. It also surfaces the data-retention windows and a prompt-injection warning about visitor notes, though it omits failure/auth-error 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?

Four short sentences, each carrying distinct load: eligibility, injection warning, retention policy, side effect. The role constraint is front-loaded before the caveats.

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 shape needs no explanation, and the description covers the remaining gaps an agent needs: who may call, side effects, and retention windows. A note on whether results are paginated or filtered would close the last 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 there is nothing to disambiguate and the baseline of 4 applies. The description correctly spends no words restating an 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?

States a specific verb and resource ('list requests for permitted apps') scoped to a named audience (portal owner / people-manager). It is clearly separable from siblings requests_approve and requests_deny, though it never names those siblings explicitly to route between 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?

The role gate ('Current portal owner (owner or people-manager role)') tells the agent who may call it, which is real eligibility guidance. It does not say when to list versus escalate to requests_approve/requests_deny, and there are no explicit when-not conditions, so usage remains 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?

Beyond the annotations, the description discloses what an agent genuinely could not infer: funnel=true publishes to the open internet and needs user consent, funnel=false stays private, directories are browsable while file targets 404 for siblings, incomplete setup returns an error with saved progress, and needs_login requires opening auth_url and retrying. Expiry defaults (no expiry unless for/until, 24h fallback, never permanent) are also spelled out. This is substantive disclosure consistent with openWorldHint=true and destructiveHint=false.

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?

Every sentence carries real information, but the description leads with funnel policy rather than the tool's core action and strings together long semicolon-chained clauses about gateway mode and recipient expiry. It is dense to the point of being hard to scan, and the policy detail on allow/expiry partially duplicates the 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?

For a 15-parameter mutation tool with a nested request_limits object and an output schema, the description covers the decisions an agent must get right: target kind, public-exposure consent, recipient expiry, and the needs_login recovery path. The output schema carries return values, so the main remaining gap is a handful of undocumented booleans like print_links and ack_never.

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

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

With 80% schema coverage the baseline is 3, and the description earns above that by explaining cross-parameter behavior the schema states only piecemeal: allow interacts with `for`/`until`/`ack_never`, and funnel requires public_ack plus an HTTP port target with no allow entries. It does not cover `print_links` or `ack_never`, which remain undocumented in both places.

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 title and opening sentences make clear this exposes a local target (directory, single file, or HTTP port) on the tailnet or, with funnel, publicly. The verb+resource is unambiguous and an agent can tell it apart from `unshare` or `url` by implication. It stops short of explicitly naming the sibling it is not, so it lands at 4 rather than 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?

"Use this after creating a local page or report that the user wants to open on another tailnet device" gives a concrete triggering scenario, and "ask the user before" setting funnel true is an explicit precondition. It never names an alternative tool (e.g., `url`, `list`, `unshare`) or states a when-not, so it is clear context without exclusions.

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