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

With no annotations provided, the description carries the full burden. It indicates the tool is read-only ('shows'), but it does not disclose other behavioral traits such as authentication needs, rate limits, or behavior when no ACL exists. It provides basic transparency but lacks depth.

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

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

The description is a single, efficient sentence with no wasted words. It front-loads the key information and is easily parseable.

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

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

Given the tool requires no parameters and has an output schema (not shown but indicated), the description is complete enough. It covers the purpose and scope without needing elaboration.

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

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

The input schema has zero parameters with 100% coverage, so the description does not need to explain any parameters. It correctly implies no additional input is required.

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

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

The description clearly states the tool's purpose as summarizing ACL policy including groups, rules, SSH rules, and tag owners. It uses a specific verb ('shows') and resource ('ACL policy summary'), and it distinguishes itself from sibling tools like ts_acl_set and ts_acl_validate by indicating it is read-only for viewing.

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

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

The description implies usage for viewing ACL policy summaries, and the context of sibling tools (e.g., ts_acl_set for modifying) provides implicit guidance. However, it lacks explicit when-to-use or when-not-to-use instructions.

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?

No annotations provided, so description fully covers behavioral traits: write operation requiring WritesEnabled=true, validation before apply, ETag-based concurrency, bypass option, auth scope, and audit envelope emission.

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 purpose and prerequisites, no wasted words, efficient structure.

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 output schema present, description doesn't need to detail returns. Covers all critical aspects: prerequisites, concurrency, validation, auth, and audit. Complete for a complex mutation tool.

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

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

Schema coverage is 100%, but description adds value: clarifies policy_json replaces entire policy, explains if_match auto-fetch, and labels allow_overwrite_concurrent as dangerous.

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

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

Description states 'Apply (POST) a full ACL policy to the tailnet' with specific verb and resource, and distinguishes from siblings like ts_acl and ts_acl_validate.

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?

Explicit requirements (TAILSCALE_WRITE_ENABLED=true, token scope), optimistic concurrency behavior, and allow_overwrite_concurrent guard are detailed. Does not explicitly advise when to use ts_acl_validate first, but implies validation occurs.

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 no annotations, the description carries full burden. It discloses that the tool validates without applying and returns errors or 'passed', but lacks details on auth needs, rate limits, or what constitutes a valid policy. Adequate but not rich.

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

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

The description is two sentences: 'Validate an ACL policy without applying it. Returns errors or 'passed'.' It is perfectly concise, front-loaded, and contains no wasted words.

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

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

Given the tool has one parameter with full schema coverage and an output schema (existence known), the description is sufficient: it states purpose, behavior, and return value. No additional context needed for a simple validation tool.

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

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

The schema covers 100% of parameters with a description: 'ACL policy as JSON string to validate'. The description does not add further meaning beyond what the schema provides, so baseline 3 is appropriate.

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

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

The description clearly states the verb 'Validate', the resource 'an ACL policy', and the behavior 'without applying it' and 'Returns errors or 'passed''. It distinguishes itself from siblings like ts_acl and ts_acl_set by emphasizing validation vs. application.

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 applying it' implies a dry-run or validation step before using ts_acl or ts_acl_set, but it does not explicitly state when to use this tool vs. alternatives or provide conditions for use. This is clear but lacks explicit 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?

No annotations provided, but description fully discloses additive vs replace semantics, the destructive nature of replace=true, and the required env var. No contradictions.

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?

Well-structured: summary line, env requirement, then two modes. Slightly verbose but all content is relevant and earns its place.

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

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

Complete for a mutation tool with two modes. Output schema exists to cover return format. Covers prerequisite, behavior, and warning. No gaps.

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 has 100% coverage with good descriptions. Description adds value by explaining default behavior of 'replace' parameter and warning about its impact.

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?

Clear verb 'Approve' and resource 'subnet routes on a device'. Distinguishes from sibling tool 'ts_device_routes' which is for listing. Also notes environment requirement.

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 contrasts default additive behavior with replace=true, warns of severity. Mentions prerequisite env var. Could be improved by stating when to use alternatives like ts_device_routes for viewing.

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?

Discloses ordering (recent first), scope filtering behavior (client-side with secondary fetch), exclusion of non-device targets, and timeout risk for wide lookbacks. No annotations provided, so description carries burden effectively.

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

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

Two short paragraphs, no wasted words. First sentence captures tool purpose, second paragraph explains scope in detail. Efficient and 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?

Covers behavior, constraints, filter details, and risks. Output schema exists so return values not needed. Complete for a read-only audit log tool.

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

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

Schema has 100% coverage, but description adds context: explains scope's client-side filtering and secondary fetch, days timeout risk, and count default/max. Adds value beyond 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?

Clearly states it's a configuration audit log showing who changed what and when, with recent entries first. Distinguishes from sibling tools that deal with devices, users, etc.

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 context on when to use optional scope filter and warns about secondary fetch and timeout risks. Lacks explicit comparison to alternatives, but siblings are distinct enough.

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

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

No annotations are provided, so the description must carry the full burden. It discloses the mutation nature but lacks details on idempotency, error states, or 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 with no wasted words, directly conveying the purpose and a key requirement.

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

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

Given the tool has only two parameters and an output schema exists, the description is adequate but could benefit from more context on success/failure behavior and idempotency.

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 description adds no extra meaning beyond what the schema already provides. Baseline of 3 is appropriate.

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

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

The description clearly states the action (authorize or deauthorize) and the resource (device), distinguishing it from sibling tools like ts_delete_device or ts_expire_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 mentions a prerequisite (TAILSCALE_WRITE_ENABLED=true) but does not provide guidance on when to use this tool versus alternatives or when not to use it.

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

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

No annotations are provided, so the description carries full burden. It only mentions the environment requirement but fails to disclose side effects, success/failure behavior, or output format beyond what the output schema provides.

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

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

The description is two sentences with no unnecessary words, front-loading the verb and resource 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?

For a simple creation tool with a complete schema and output schema, the description is minimally adequate but lacks details on error conditions or usage nuances.

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

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

Schema description coverage is 100%, so the input schema already documents all 6 parameters. The description adds no additional meaning beyond what the schema provides, meeting the baseline.

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

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

The description clearly states 'Create a new auth key.' This is a specific verb and resource, distinguishing it from sibling tools like ts_delete_key (delete) and ts_keys (list).

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 includes a prerequisite (TAILSCALE_WRITE_ENABLED=true) but provides no guidance on when to use this tool versus alternatives like ts_keys or ts_delete_key.

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

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

With no annotations, the description carries the full burden. It discloses the env var requirement and confirm Boolean, but lacks details on irreversibility, side effects, or error scenarios. Adds basic transparency but could be richer.

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 efficient sentence that front-loads the action and includes key requirements. No unnecessary words, but could be expanded slightly without sacrificing conciseness.

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

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

Given the presence of an output schema and 2 parameters, the description covers core aspects (action, prerequisites) but lacks mention of permanence of deletion, error handling, or recovery options. Adequate but not comprehensive.

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%, but the description adds value by specifying the TAILSCALE_WRITE_ENABLED requirement, which is not in the schema. It reinforces the confirm parameter's necessity, though device_id meaning is adequately covered by 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?

Clearly states the action: 'Delete a device from the tailnet.' Verb and resource are specific, and it differentiates from sibling tools like ts_authorize_device and ts_expire_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?

Explicitly states prerequisites: 'Requires TAILSCALE_WRITE_ENABLED=true and confirm=true.' This guides the agent on when and how to invoke the tool. However, it does not mention alternatives or exclusions, like the permanent nature compared to expiration.

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?

No annotations provided, but the description discloses that this is a destructive write operation requiring confirmation and a write-enabled flag. The confirm parameter's schema description adds clarity about permanent revocation.

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?

Single sentence with no wasted words. The key action and all requirements are front-loaded and clearly stated.

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

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

For a simple tool with an output schema, the description covers purpose, prerequisites, and parameter semantics adequately. No missing elements needed for correct usage.

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

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

Schema coverage is 100%, and the main description adds context by requiring confirm=true, which is not enforced by the schema (only a default of false). This extra guidance helps the agent understand the parameter's 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?

The description clearly states the action 'Revoke an auth key' with a specific verb and resource. It distinguishes from sibling tools like ts_create_key and ts_keys which perform opposite or related actions.

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 states prerequisites (TAILSCALE_WRITE_ENABLED=true and confirm=true) but does not specify when not to use or list alternatives. Context is clear enough for a simple destructive operation.

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 no annotations, the description carries full burden. It discloses the return of a _meta envelope for audit uniformity and clarifies that scope filtering is not supported. It doesn't mention auth or error conditions, but for a simple fetch this is adequate.

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 efficient sentences plus a clarifying note. It starts with the core purpose ('Full detail for a single device') and then provides behavioral constraints. No wasted words.

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

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

Given the tool's simplicity, high schema coverage, and existence of an output schema, the description is complete. It explains the return details, filter behavior, and scope exclusion, leaving no major gaps for a single-record fetch tool.

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

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

Schema coverage is 100% and the description adds value by clarifying that the device_id parameter is 'device nodeId (from ts_devices)' and that it's 'server-side filter ... not tag-shaped'. It also warns about scope not being accepted, enhancing schema 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?

The description clearly states it returns 'Full detail for a single device' listing specific fields (addresses, OS, client version, etc.). It distinguishes from sibling tools by emphasizing it's a single-record fetch using device_id, contrasting with tag-based or list operations.

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

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

The description explicitly says 'Single-record fetch' and notes that 'scope= is intentionally NOT accepted' due to semantic incoherence, providing clear when-not guidelines. However, it does not explicitly name alternative sibling tools like ts_devices for listing.

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 no annotations, the description must disclose behavior. It mentions emitting a _meta envelope with device_id and cardinality, which provides transparency about output metadata. However, it does not mention any prerequisites, side effects, or error conditions.

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

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

The description is two sentences long, front-loading the core purpose and then adding a technical detail about the output envelope. No unnecessary words.

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

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

Given the output schema exists, the description doesn't need to explain return values. It covers the purpose and metadata format. Missing details like pagination or error handling, but for a simple lookup tool this is adequate.

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 (device_id) has a description in the schema: 'Device nodeId (from ts_devices).' The description in the text does not add further details, but the schema coverage is 100%, so the baseline of 3 is appropriate, with slight extra context from 'from ts_devices'.

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

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

The description clearly states the tool's purpose: 'Routes for a device: advertised subnets, approved/unapproved status.' This distinguishes it from sibling tools like ts_approve_routes (which modifies routes) and ts_device (which retrieves device details).

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 explains what the tool returns but does not provide explicit guidance on when to use it versus alternatives like ts_approve_routes or ts_device. Some context is implied but not 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?

The description discloses a critical behavioral trait: the scope filter is applied client-side because the API lacks server-side filtering. It also notes the output includes a _meta envelope. With no annotations provided, this covers the main behavioral expectations, though pagination or rate limits are not mentioned.

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

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

The description is two sentences: first gives a clear, bullet-like list of output fields; second explains the optional parameter and output format. Every word adds value with no redundancy.

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

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

Given one optional parameter and an output schema (existence known but not shown), the description covers purpose, parameter behavior, and output format well. It does not mention pagination or limits, but for a list tool with a single optional param, this is minor.

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

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

The schema describes scope as a DD-278 filter with enumerated values, but the description adds extra context: it explains the mapping is configurable via environment variables and that filtering is client-side, with 'public' unsupported. This significantly enriches parameter understanding beyond the schema.

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

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

The description clearly states the tool lists all devices and enumerates the fields included (hostname, OS, IP, etc.). The name 'ts_devices' contrasts with singular sibling 'ts_device', and no ambiguity exists about what the tool does.

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 and sibling context imply this is the primary list-all tool, distinct from ts_device (single device) and mutation tools. However, no explicit guidance on when not to use it or alternatives is given. Still, the context is clear enough.

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

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

No annotations provided, and the description does not clarify if the tool is read-only, modifies state, or requires specific permissions. The term 'configuration' is ambiguous.

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

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

A single sentence conveys the purpose, but could be more structured. Lacks front-loading of key behavioral details.

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?

Despite having an output schema, the description doesn't mention return values or behavior. With no annotations, it leaves too many questions for a tool with no parameters.

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?

No parameters exist, so schema coverage is 100%. The description adds no parameter-specific meaning, but none is needed.

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

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

The description clearly states it covers DNS configuration, listing key areas (nameservers, MagicDNS, search paths, split DNS rules). It is distinct from sibling tools dealing with ACLs, devices, keys, etc.

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

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

No guidance on when to use this tool vs alternatives, such as whether it reads or writes configuration. No exclusions or prerequisites mentioned.

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?

No annotations are provided, so the description must carry full burden. It states 'Force key expiry' implying a destructive mutation, but does not disclose side effects, required permissions beyond the env var, or whether the action is reversible. Minimal behavioral context.

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

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

Two sentences, no wasted words. The first sentence states the purpose, the second adds a critical requirement. Front-loaded and efficient.

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

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

Given the tool's simplicity (one required param, output schema exists), the description covers purpose, prerequisite, and parameter. It is sufficiently complete for an agent to understand and invoke the tool 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 100% (device_id is described as 'Device nodeId (from ts_devices)'), so baseline is 3. The tool description does not add extra meaning beyond the schema for the parameter; it only restates the prerequisite.

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

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

The description clearly states the verb 'Force key expiry' and the resource 'device', and the clarification 'it must re-authenticate' adds specificity. This differentiates it from sibling tools like ts_delete_device (deletion) or ts_authorize_device (authorization).

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 mentions a prerequisite (TAILSCALE_WRITE_ENABLED=true) but does not provide explicit guidance on when to use this tool versus alternatives like ts_delete_device or ts_authorize_device. No exclusions or alternative recommendations are given.

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

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

With no annotations, the description carries full burden. It transparently lists the types of information returned (device counts, online/offline, etc.), indicating it's a read-only health check. It does not mention side effects, auth needs, or error cases, but for a zero-parameter tool this is acceptable.

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 concise at one line, but the use of a comma-separated list could be more readable. It is front-loaded with 'Health check' which immediately conveys purpose. Minor improvements in structure would earn 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 tool with no parameters and an output schema (not shown), the description covers the main expected outputs. However, it does not mention that it provides a high-level summary vs. detailed data, and error conditions are omitted. Still, it is largely complete for a health check tool.

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

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

There are zero parameters, so the description adds value by explaining what the tool does and what information it returns. Since the input schema provides no detail, the description is essential and sufficiently informative.

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

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

The description clearly states it's a 'Health check' and lists specific returned information (device counts, online/offline, key expiry warnings, updates, tailnet settings, write gate). This distinguishes it from sibling tools that focus on specific aspects like ts_devices or ts_acl, but a more explicit statement of its scope would improve clarity.

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

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

The description implies usage for general health monitoring, but lacks explicit guidance on when to use this tool vs siblings. No when-not-to-use or alternative recommendations are provided, which is a gap given the number of sibling tools.

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

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

The description notes that scope filtering is client-side after fetch and that output includes a Track 3 _meta envelope, providing useful behavioral details beyond a simple 'list' action. No annotations exist, so the description carries the full burden, and it does well.

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

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

The description is two sentences, front-loaded with the main action and output fields, and contains no unnecessary words.

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

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

Given that an output schema exists, the description appropriately summarizes the output fields and mentions the _meta envelope. It covers all essential aspects for a list tool.

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

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

Schema coverage is 100%, so the description adds minimal value for the 'scope' parameter beyond what the schema already states. The description includes the parameter but does not provide new semantics.

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

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

The description clearly states it lists auth keys with specific fields (ID, description, flags, tags, expiry), distinguishing it from related siblings like ts_create_key and ts_delete_key.

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

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

The description explains the optional scope parameter and its function, but lacks explicit guidance on when to use this tool versus alternatives like ts_acl or ts_devices. However, the purpose is clear enough for basic usage.

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

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

With no annotations provided, the description discloses the destructive behavior (replacing existing tags) and a critical prerequisite. This adds value beyond a basic read/write classification, but does not cover other aspects like rate limits or error 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?

The description is concise with two sentences, front-loading the purpose and adding a key requirement. No unnecessary words.

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

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

The tool has two parameters, an output schema (not shown), and the description covers the main behavior and prerequisite. It is adequate for a simple tool, though it could mention error scenarios or idempotency.

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 description does not add parameter-level details beyond the schema. It provides context about replacement and requirements, but the schema already handles parameter semantics adequately.

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

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

The description clearly states the verb 'Set' and resource 'ACL tags on a device', and mentions replacement of existing tags. It is specific and informative but does not differentiate from siblings like ts_acl_set.

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

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

The description mentions the prerequisite 'Requires TAILSCALE_WRITE_ENABLED=true', but lacks guidance on when to use this tool versus alternatives such as ts_acl_set. Usage context is implied rather than explicit.

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?

No annotations provided, but the description clearly indicates this is a read-only listing tool with sorting details. It does not mention any side effects, which is acceptable for a simple retrieval tool.

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

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

Two succinct sentences with maximum information: first states purpose and output fields, second adds sorting behavior. No wasted words.

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

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

For a parameterless tool with an output schema, the description covers essential output fields and sorting. Sibling tools are diverse, so confusion is unlikely. Fully adequate.

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?

No parameters exist, so baseline is 4. The description does not need to add parameter information.

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 explicitly states 'List users' and enumerates the output fields (name, login, role, status, device count, online/last seen), clearly distinguishing it from sibling tools like ts_devices or ts_acl.

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

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

The description implies usage for listing all users, but lacks explicit guidance on when to use this tool versus alternatives or any prerequisites, leaving some ambiguity.

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?

No annotations are provided, so the description carries the full burden. It correctly implies a read-only list operation and mentions sorting by endpointId ascending, but lacks details on authentication, pagination, or any side effects, which are minimal for a list operation.

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

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

Two short sentences with no redundant information. Every word adds value, specifying the action, returned fields, and sorting order.

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

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

Given the tool has an output schema, the description does not need to cover return values. It adequately specifies what is listed and how it is sorted, which is complete for a simple list tool with zero parameters.

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

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

There are no parameters, so schema description coverage is 100%. The description adds nothing beyond what the schema provides, which is appropriate given no parameters exist. Baseline 4 applies.

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

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

The description clearly states 'List configured webhooks' with specific fields (endpoint URL, event subscriptions, created date), which is a specific verb+resource. It distinguishes from sibling tools like ts_devices or ts_acl, which are unrelated.

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

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

The description implies usage for listing webhooks but provides no explicit when-to-use or alternatives. It does not mention when not to use it or if there are other tools for webhook management.

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