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

Annotations already signal destructiveHint=true and idempotentHint=false, indicating this tool modifies state and is not idempotent. The description reinforces this by specifying 'grants' and 'revokes', which are mutating actions. However, it does not add behavioral details beyond what annotations already convey, such as potential side effects or required permissions.

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

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

The description is two concise sentences with no unnecessary information. It front-loads the purpose and then details the actions. Every sentence adds value.

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

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

Given the simple action-oriented nature (2 params, no output schema, annotations present), the description covers the core functionality. It could briefly mention that the client must be connected or that the actions are specific to hotspot guests, but overall it is sufficient for an agent to understand 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% with both parameters well-described: clientId as a UUID from list_clients, and action as an enum with descriptions. The tool description does not add extra meaning to the parameters beyond what the schema already provides, so the baseline score of 3 applies.

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

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

The description clearly states it executes hotspot guest access actions on a connected client. It explicitly names the two enum values (AUTHORIZE_GUEST_ACCESS and UNAUTHORIZE_GUEST_ACCESS) and explains their effects ('grants guest WiFi access', 'revokes it'). This distinguishes it from sibling tools like 'manage_client' which likely handle broader client management.

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

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

The description implies usage context (hotspot guest access) but provides no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites (e.g., client must be connected). Sibling tools like 'manage_client' are not contrasted.

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 goes beyond annotations by explicitly warning that a restart will 'briefly disconnect all clients on that device.' This adds valuable behavioral context about the destructive nature of the action, which is not fully captured by the annotations alone (destructiveHint: true).

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

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

The description is extremely concise: two sentences and a warning. It front-loads the purpose and gives critical behavioral information immediately. 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 (2 parameters, no output schema, full annotations), the description provides all necessary context: what the tool does, its current capability, and its side effects. No additional information is needed for an AI agent to use 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?

The schema already provides 100% coverage for parameters with descriptions. The description adds value by reinforcing the effect of the 'action' parameter (e.g., 'RESTART reboots the device') and providing a practical warning. This goes beyond the baseline of 3 for high schema coverage.

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

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

The description clearly states the tool's purpose: 'Execute an action on an adopted device.' It specifies the currently supported action (RESTART/reboot), providing a specific verb and resource. This distinguishes it from sibling tools like 'client_action' or 'execute_action' by focusing on device-level 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 gives clear context for when to use the tool (to restart a device) and includes a warning about the consequences (briefly disconnecting clients). However, it does not explicitly state when not to use this tool or mention alternatives, such as using 'client_action' for client-level actions.

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 indicate destructiveHint=true and idempotentHint=false. The description adds context about the generic params object and the two-tool interface but does not elaborate on side effects, permissions, or rate limits. With annotations covering safety, a score of 3 is appropriate.

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 waste. Front-loaded with the core action, followed by usage context. Every sentence earns its place.

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

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

The description covers the main purpose and usage pattern but omits what the tool returns (no output schema). Given destructiveHint=true, some guidance on side effects would be helpful. Still adequate for a generic tool in a two-tool setup.

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 conveys that params keys depend on actionId, adding dynamic context beyond the schema's 'action arguments object'. This helps an AI understand that params are action-specific.

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 'Execute a UniFi action by actionId using a generic params object', specifying the verb, resource, and mechanism. It distinguishes itself from siblings by mentioning the stable two-tool interface pattern (search_actions + execute_action).

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 indicates usefulness for agents preferring a two-tool interface, implying usage when an actionId is obtained from search_actions. However, it does not explicitly exclude alternatives like client_action or device_action, which could be more specific for certain use cases.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. Description adds useful output context (what data is shown) beyond 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?

Two sentences, zero wasted words. Front-loaded with purpose, followed by usage context. Exemplary 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 tool's simplicity (1 param, no output schema), the description fully covers purpose, usage, and key output details. 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 description coverage is 100% for the single parameter clientId. The description does not add extra meaning beyond the schema's description. Baseline score of 3 is appropriate.

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

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

Clearly states verb and resource ('Get detailed info for a single connected client') and lists specific data fields (AP/switch, signal strength, connection type, network membership). Distinguishes from siblings like list_clients and manage_client.

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 this to troubleshoot a specific device's connectivity,' providing clear context. Could be more explicit about when not to use or mention alternatives, but the sibling tool list implies alternatives.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds valuable behavioral context by disclosing the response includes interfaces.radios (for APs) and interfaces.ports (for switches), which is beyond the annotations. However, it does not mention any potential side effects or limitations, but given the safety profile from annotations, a 4 is appropriate.

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 (two sentences), front-loaded with the purpose, and every sentence provides essential information. No wasted words or redundancy.

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

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

For a simple read tool with one parameter and no output schema, the description is complete. It explains the response content (uplink topology, radio interfaces, port configuration, features, provisioning info) and the context of use. Combined with annotations, the agent has sufficient information to correctly invoke the 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 single parameter (deviceId) has 100% schema coverage with a description: 'Device ID (UUID from list_devices).' The description reiterates this context but adds no new semantic meaning beyond the schema. With full schema coverage, baseline is 3, and the description does not elevate it further.

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: 'Get full details for a single adopted device' and lists specific content (uplink topology, radio interfaces, port configuration, features, provisioning info). It distinguishes from sibling 'list_devices' by specifying it is used after list_devices identifies a device of interest.

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 states when to use the tool: 'Use this to inspect a specific device after list_devices identifies one of interest.' This provides clear context and implies the correct sequence of tools, effectively differentiating from list_devices and guiding the agent.

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

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

Annotations declare readOnly, idempotent, and openWorld hints. Description adds behavioral context about real-time nature and specific statistics returned, going beyond annotations to detail what the tool does and how to interpret results.

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 are efficient and front-loaded with purpose. Every sentence adds value with 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 annotations and schema, the description fully covers the tool's purpose, usage, and output. No output schema is needed as description lists what stats are returned.

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 description for deviceId parameter. Description does not add further parameter semantics, so 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?

Description clearly states 'Get real-time performance statistics for a device' and enumerates specific metrics (CPU, memory, load averages, etc.), distinguishing it from sibling tools like get_device which likely returns broader device info.

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 explicit use case for diagnosing performance issues and high CPU/memory explaining client disconnects, plus suggests comparing load averages across devices. Lacks explicit 'when not to use' but context makes it clear.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds that it returns app version and basic info, and serves as a connectivity check, which aligns with and supplements the annotations. 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?

Two concise sentences: first states purpose, second gives usage guidelines. No redundant information. Every word earns its place.

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

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

For a simple parameterless tool with no output schema, the description is complete. It covers purpose, usage context, and error recovery, which is sufficient for an agent to select 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?

The tool has zero parameters, so baseline is 4. The description does not need to add parameter info because there are none. The description adequately explains the tool's purpose.

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

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

The description clearly states 'Get UniFi Network application version and basic info', which is a specific verb and resource. It distinguishes from siblings by focusing on system info rather than clients, devices, or 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 'Use this first to verify the connection is working and check the controller version', and provides a fallback instruction ('If this fails, check UNIFI_API_URL and UNIFI_API_KEY'). This gives clear when-to-use and troubleshooting 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint. The description adds behavioral detail: 'Shows each WAN port's connection state and current bandwidth,' which provides value beyond annotations.

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

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

Two concise sentences. The first sentence front-loads the purpose and output, the second adds usage context. 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?

No output schema, but the description sufficiently describes the return elements (status, IP, throughput, connection state, bandwidth). For a 0-param read-only list tool, this is complete.

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

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

No parameters exist (schema coverage 100%). Baseline for 0-param tools is 4. Description does not need to add parameter info.

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 it lists WAN interfaces with status, IP, and throughput, and is used for diagnosing internet connectivity or checking multi-WAN setups. This clearly distinguishes it from sibling tools like list_vpn or list_wifi.

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

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

The description provides explicit usage context ('diagnose internet connectivity issues or check multi-WAN setups'). It does not mention when not to use or alternatives, but given the tool's specificity, this is sufficient.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral details: it shows client type, MAC, IP, connection time, and authorization status. It also discloses that the tool can be used to detect roaming issues and unauthorized guests, which is useful beyond the annotations. There is no contradiction.

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

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

The description is front-loaded with the main purpose but then includes a lengthy guide on identifying unknown clients. While informative, this section could be condensed or placed in documentation. The length reduces quick readability for an AI agent.

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?

There is no output schema, but the description explicitly lists what is shown (client type, MAC, IP, connection time, authorization status). It also provides practical context like AP distribution checks and unauthorized guest detection, making it complete 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% and the schema already provides descriptions for both parameters (filter and limit). The description does not add any additional meaning or examples for these parameters, so it meets the baseline of 3.

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 currently connected clients with their type, MAC, IP, connection time, and authorization status. It distinguishes from sibling tools like list_known_clients (which lists known clients) by specifying 'all currently connected clients' and focusing on live client distribution.

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 explicit context for when to use this tool: checking client distribution across APs to detect roaming or placement issues, and checking for unauthorized guests. It also provides a step-by-step guide for identifying unknown clients. However, it does not explicitly mention when not to use it or suggest alternatives, though the detailed guidance implies its primary use.

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 complements annotations by explaining the output fields, filtering support, and the fact that it lists all adopted devices. Annotations already denote read-only and idempotent behavior, so the description adds meaningful context without contradiction.

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

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

Three concise sentences, front-loaded with core functionality. Every sentence adds value with 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?

Covers purpose, use cases, output fields, filter examples, and role determination. Given the simple parameters and no output schema, the description is complete and sufficient for effective tool selection.

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

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

Schema coverage is 100% with good param descriptions. The description adds a concrete filter example but doesn't significantly augment the schema. 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 it lists adopted UniFi devices with specific fields (state, firmware, model, IP, MAC) and enumerates device types. It doesn't explicitly distinguish from sibling tools like list_clients, but the resource focus is unambiguous.

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

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

Explicit use cases are provided (assess fleet health, find OFFLINE devices, check firmware updates) along with guidance on determining device roles from features. Lacks explicit when-not-to-use instructions, but the context is sufficient.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds behavioral context by explaining return content (categories and applications) and purpose, without contradicting 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?

Two sentences, front-loaded with action and resource, no filler. Each sentence adds necessary information.

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

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

For a simple parameterless tool with good annotations, the description fully covers what the tool does and why to use it, despite lacking an 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?

No parameters in schema (100% coverage trivially). Description adds value by explaining what the tool returns, which is the relevant semantic context for a parameterless tool.

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

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

Description clearly states verb (list) and resource (DPI applications and categories), provides examples of returned data, and distinguishes from sibling tools which are about other network management functions.

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 when to use: to understand traffic classification for creating rules or analyzing bandwidth. No need for alternatives as no similar sibling tools exist.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds behavioral context beyond annotations: first-match-wins evaluation and common security checks, which is valuable but not contradictory.

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 sentences, no wasted words. First sentence states purpose, second gives behavioral rule, third lists common checks, fourth references sibling tool. Well-structured.

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 lack of parameters and output schema, the description adequately covers what the tool does and its behavioral implications. Could optionally add output format, but sufficient for selection and 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?

With zero parameters, the description does not need to add parameter meaning. Baseline is 4 per guidelines.

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 firewall policies with source/destination zones, actions, and ordering. It distinguishes from the sibling manage_firewall_policy which handles 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?

Explicitly mentions that policies are evaluated in order (first match wins) and provides specific checks (overly permissive rules, missing inter-zone rules, disabled policies). Directs to manage_firewall_policy for modifications.

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

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

Annotations already provide readOnlyHint, idempotentHint, openWorldHint. Description adds conceptual context (zone purpose) but no behavioral traits beyond what annotations cover. No contradiction.

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

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

Three sentences, front-loaded with purpose. No wasted words. Every sentence adds value: first says what it does, second and third provide essential context.

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

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

For a simple list with no output schema, the description provides domain context (zones, policy enforcement). However, it does not hint at typical return fields (e.g., zone name, members). Minor gap.

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

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

No parameters (0 param count, 100% schema coverage). Description adds meaning by explaining the role of zones in network segmentation, which helps understand the output. Baseline for 0 params is 4.

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

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

Description clearly states 'List all firewall zones' and explains zones group interfaces for policy enforcement. It distinguishes from siblings like list_firewall_policies by focusing on zone objects, but does not explicitly differentiate from manage_firewall_zone.

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

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

No explicit guidance on when to use this tool vs. alternatives. It does not mention when to list vs. manage zones or policies. Usage is implied only from the name.

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

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

Annotations declare readOnly/ idempotent/ openWorld. Description adds context: data from classic REST API, works across VLANs, no firewall limitations, and lists specific fields returned. No contradictions with 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?

Each sentence adds value. Front-loaded with main purpose, then lists key fields, then usage advice. No fluff; efficiently structured.

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 no parameters and no output schema, the description thoroughly covers what the tool returns, its data source, and its advantages. Complete enough for an agent to understand usage and output.

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; schema coverage 100%. Description adds value by listing the return fields (oui, hostname, etc.) even though not strictly parameter-related. With 0 params, it compensates well for missing output 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 lists all historically known clients with rich metadata, distinguishes from siblings like list_clients and get_client by specifying scope and unique fields (oui, hostname, etc.). Verb 'list' + resource 'historically known clients' is specific and unambiguous.

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

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

Explicitly recommends using this as the 'FIRST identification tool for unknown clients' and explains why (oui identifies manufacturer without scanning). Also notes advantages over alternatives like nmap/dns-sd (no firewall limitations).

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

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

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds behavioral details about the data returned, specifically that the 'default' network (VLAN 1) is the untagged LAN and additional networks use VLAN IDs >= 2. 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 only three sentences, each serving a distinct purpose: stating the function, giving a usage example, and providing a key detail about VLAN ID conventions. No unnecessary words or repetition.

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

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

The description is complete for a read-only list tool. It mentions the key fields returned (VLAN IDs, DHCP, status) and an important note about the default network. Given the annotations cover safety and idempotency, no further information is needed.

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 the single parameter 'filter' with a description ('UniFi filter expression'), so schema coverage is 100%. The description adds no additional meaning to this parameter, which is acceptable since the schema already explains 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 clearly states the tool's purpose: 'List all network configurations including VLAN IDs, DHCP settings, and status.' The verb 'list' and resource 'network configurations' are specific, and the tool is distinct from sibling tools like list_clients or list_devices.

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

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

The description provides explicit usage guidance: 'Check for proper network segmentation — IoT devices should be on a separate VLAN from your main network.' This tells the user when to use this tool (for segmentation audits). It does not explicitly list alternatives or when not to use, but 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?

Annotations already declare readOnlyHint and idempotentHint, so the description doesn't need to repeat that. It adds context about new or factory-reset devices waiting for adoption, which is useful beyond annotations.

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

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

The description is a short, front-loaded paragraph with two sentences. Every sentence adds value, 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 no parameters and no output schema, the description adequately explains what the tool returns and provides follow-up action guidance. Complete for its simplicity.

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

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

No parameters exist, so schema coverage is 100%. The description does not need to explain parameters, earning baseline 4.

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

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

The description clearly states the tool lists devices discovered but not adopted, distinguishing it from 'list_devices'. It uses specific verb 'List' and resource 'pending devices'.

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

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

The description explains when to use the tool (for unadopted devices) and provides a hint to use 'device_action' for adoption. However, it lacks explicit exclusions or comparisons to similar sibling tools like 'list_devices'.

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 context beyond annotations: it mentions that most controllers have a single 'default' site but multi-site setups exist. This helps the agent understand cardinality. Annotations already indicate read-only and idempotent 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?

Three short, front-loaded sentences with zero wasted words. Every sentence adds value: main action, typical scenario, and environment variable integration.

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 no output schema, the description fully explains what the tool does and how it fits into the broader system. Annotations cover safety. No gaps for this simple 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 no parameters, so the description correctly avoids param details. The schema coverage is 100% (empty schema), so the baseline is 4.

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

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

The description clearly states 'List all UniFi sites on this controller' with a specific verb and resource. It distinguishes itself from siblings by noting that site ID is required for nearly all other tools, implying this tool provides that ID.

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 advises to call this tool first if the site ID is needed, and notes that the env var UNIFI_SITE_ID can automate selection. While it doesn't explicitly exclude scenarios, it provides clear usage 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?

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint true. The description adds valuable behavioral context by specifying that the tool returns both site-to-site tunnels and VPN servers, and that it provides status/uptime for connectivity monitoring, going beyond what annotations offer.

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 filler. It front-loads the purpose and then adds a practical use case. Every word earns its place.

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

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

For a parameterless list tool with no output schema, the description covers purpose and a use case. It could detail the exact fields returned (e.g., tunnel names, status, uptime values), but is still fairly 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 input schema has zero parameters, and schema description coverage is 100%. Per guidelines, baseline is 3. The description adds no parameter information, which is acceptable since none exist.

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

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

The description clearly states the tool lists VPN tunnels and servers, including both site-to-site tunnels and VPN servers. It distinguishes itself from sibling tools like list_clients or list_networks by focusing specifically on VPN resources.

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 indicates using the tool for connectivity monitoring by checking tunnel status and uptime. While it doesn't provide exclusions or alternatives, the simple list operation's context is obvious, making this adequate.

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

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

Annotations already declare readOnlyHint, idempotentHint, and openWorldHint. The description adds value by detailing the specific config fields returned and optimization checks, going beyond annotation metadata.

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 main purpose and uses bullet points for key checks; it is informative but slightly verbose, each sentence earns its place.

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

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

Given the tool is read-only with no output schema, the description covers the returned fields and optimization context comprehensively, making it fully informative for an agent.

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 'filter' has a generic schema description ('UniFi filter expression') with 100% coverage; the description does not add further semantic detail to the parameter, meeting 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 'List all WiFi SSIDs (broadcasts)' with specific configuration details, effectively distinguishing it from sibling tools like list_clients or list_devices.

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

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

The description provides optimization guidance (e.g., prefer WPA3, enable client isolation for guests) implying when to use the tool for network optimization, but does not explicitly state when not to use or list alternatives.

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 reveals that reorder passes an ordered list and 'first match wins', adding behavioral context beyond the destructiveHint annotation. However, it does not detail other mutation behaviors like update/delete 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?

The description is concise and front-loaded with the main verb list, but uses a bullet-like layout that could be more structured. Every sentence adds value.

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 11 parameters and nested objects with no output schema. The description covers list, create, and reorder but lacks details on update/delete and return value format, leaving gaps for a complex 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?

With 100% schema coverage, the description adds value by explaining the action enum and providing concrete examples for list and reorder parameters (e.g., ruleIds format), going beyond the schema's descriptions.

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, creates, updates, deletes, or reorders ACL rules, and distinguishes it from firewall policies by mentioning 'fine-grained network access control beyond firewall policies'.

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 when to use the tool (for ACL rules beyond firewall policies) and provides specifics for list, create, and reorder actions, but does not explicitly exclude alternative tools like manage_firewall_policy.

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

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

Annotations already provide destructiveHint, idempotentHint, and openWorldHint. The description adds context about the API version and naming convention but does not elaborate on exact mutations, permissions, or side effects 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?

The description is three concise sentences, front-loaded with the main purpose, followed by additional context. No extraneous 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 simple update tool with no output schema, the description covers how to use, prerequisites, and naming convention. It could mention confirmation of success, but overall complete.

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

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

Schema coverage is 100% with parameter descriptions, and the description adds value by explaining the naming convention and the need to get the MAC from list_clients, going 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 verb ('Set or update') and resource ('friendly name for a network client'), distinguishes from siblings by mentioning the API version and requiring MAC from list_clients, and gives a specific naming convention.

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 when to use (replace generic hostnames), provides a naming convention, and instructs to get the MAC from list_clients first. It does not explicitly state when not to use or list alternatives, but the context is sufficient.

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, idempotentHint=false, openWorldHint=true. The description adds context by specifying the naming convention, API version, and prerequisite calls. It does not contradict annotations and provides additional behavioral context beyond 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?

Front-loaded with the core purpose, then efficiently provides naming conventions, role determination, and prerequisite steps. Every sentence adds value without 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?

Covers purpose, naming convention, role determination, prerequisite calls, and API choice. Given no output schema, it adequately informs the agent about how to use the tool, though it could mention possible failure scenarios.

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 descriptions for all three parameters. The description enhances the name parameter by explaining the naming convention and how to determine role from features, adding value beyond the schema's description.

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

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

Description clearly states 'Update properties of an adopted device — primarily for renaming' with a specific verb and resource. It distinguishes from siblings by focusing on device renaming and naming conventions, and mentions using the classic API vs integration API.

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 guides usage: when to rename, naming convention {role}-{location}, how to derive role from features, and prerequisite to call list_devices or get_device first. Also identifies that this tool uses the classic Network Application REST API, not the integration API.

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 indicate destructiveHint=true and idempotentHint=false. The description adds context that policies control domain resolution but lacks specifics on side effects (e.g., propagation time, impact on existing policies) or operational details like required permissions. It does not contradict 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 three sentences, front-loaded with the main purpose, and contains no extraneous information. Every sentence adds value.

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 description covers the main actions and use cases, but for a tool with 6 parameters and no output schema, it lacks details on return values (e.g., list output format), delete behavior (e.g., cascading effects), and update semantics (partial vs full replacement). It is adequate but not fully 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 valuable context beyond the schema: the naming convention for 'name' ('dns-{purpose}') and clarifies that 'filter' is for list only. This helps the agent use parameters correctly.

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

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

The description clearly states the tool's function: 'List, create, update, or delete DNS filtering policies.' It explicitly names the resource (DNS filtering policies) and provides use cases (content filtering, ad blocking, security). This distinguishes it from sibling tools like manage_firewall_policy or manage_acl_rule.

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 suggests when to use (content filtering, ad blocking, security) but does not provide explicit when-not-to-use guidance or mention alternatives. While the use cases are implied, there is no comparative context with sibling tools that might serve similar purposes.

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 significant context beyond annotations: highlights that policy order matters (first match wins), specifies required fields for CREATE, and details the reorder action format. No contradiction with annotations (destructiveHint=true, etc.).

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: overview, action-specific details, critical warning. Every sentence is informative and earns its place. Front-loaded with the most important 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?

Covers key complexities (order sensitivity, required fields for CREATE, reorder format). Lacks specifics on update/delete requirements, but schema provides those. No output schema, so return values are not explained; acceptable.

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 91% (high), so baseline is 3. The description adds value by summarizing CREATE requirements and providing a naming convention for the 'name' parameter (e.g., 'allow-trusted-to-iot'). This exceeds 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?

Description starts with 'Create, update, delete, or reorder firewall policies,' clearly stating the verb and resource. It distinguishes itself from sibling tools like list_firewall_policies and manage_firewall_zone by specifying the operations and context.

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 explicit guidance for CREATE (required fields) and REORDER (expected data format) and a critical warning about policy order. However, it does not compare to sibling tools or specify when to use this tool versus alternatives.

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 indicate destructiveHint=true and idempotentHint=false. The description adds value by explaining the lifecycle (create, then assign networks, then create policies) and the restriction on deleting default zones, which goes 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?

The description is concise (four sentences) and front-loaded with the primary purpose. Every sentence contributes meaningful information without redundancy.

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

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

For a CRUD tool with no output schema, the description adequately explains the concept and workflow. It could mention that zoneId is required for update/delete (implied by schema) or specify return behavior, but overall it is 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?

Schema coverage is 100%, with each parameter having a description. The description adds some context (e.g., naming convention 'zone-{purpose}') but does not significantly enhance understanding beyond the schema. 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 explicitly states the tool creates, updates, or deletes custom firewall zones, with concrete examples ('IoT', 'Guest', 'Cameras'). This clearly distinguishes it from sibling tools like list_firewall_zones (read-only) and manage_firewall_policy (policy management).

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

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

The description provides context on when to use the tool (per security boundary) and mentions default zones cannot be deleted. However, it does not explicitly guide when not to use it or compare with alternative tools like list_firewall_zones for inspection or manage_firewall_policy for policies.

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

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

Annotations declare destructiveHint=true, and the description adds a clear warning about client disconnection on delete. Discloses behavioral traits beyond annotations.

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

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

Four sentences, front-loaded with main purpose, structured by action. 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?

Covers all three actions, necessary parameters, warnings, and cross-references sibling tools. Adequate for a 6-param, no-output-schema 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?

Input schema has 100% description coverage. Description adds value with naming convention (lowercase-with-dashes), common VLAN IDs, and management type clarification.

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 creates, updates, or deletes networks, and distinguishes from siblings like list_networks (read) and manage_wifi (WiFi assignment). Verb+resource is specific for each action.

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 guidance for when to use each action, prerequisites (use list_networks before modifying), and a concrete use case for VLAN segmentation. Also warns about disconnecting clients on delete.

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 indicate destructiveHint=true; description confirms delete operation but adds no new behavioral details like authorization or side effects. Adequate but not enhanced.

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 concise sentences with front-loaded action list, clear purpose explanation, and per-action details. Every sentence 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?

Covers main CRUD purpose and per-action behavior. Could mention return values (e.g., list returns all matching lists) since no output schema, but schema descriptions fill gaps. Adequate for 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?

Schemas have 100% coverage, baseline 3. Description adds naming convention (traffic-{category}) and differentiates action behaviors, improving parameter understanding.

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 CRUD operations on 'traffic matching lists' with specific examples (gaming, video streaming). Distinguishes from sibling tools like manage_firewall_policy by focusing on pattern definitions.

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

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

Explains that traffic rules are used by firewall policies and QoS, giving context. Lists per-action behavior but doesn't explicitly compare with alternatives or provide when-not-to-use 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 indicate destructiveHint=true; the description warns about 'delete_all (use with caution)'. It also explains that CREATE generates unique codes. No contradictions with 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 well-structured with sections for each action, uses bullet points for CREATE params, and every sentence adds value. 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 tool with 10 parameters and 4 actions, the description covers all actions, explains key parameters, and provides enough context for correct invocation. No output schema needed.

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 baseline is 3. The description adds value by providing common usage examples (e.g., '60=1h, 1440=1day') and clarifying optional vs required fields.

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 specific verbs (list, create, delete) and clearly identifies the resource (hotspot vouchers). It distinguishes from siblings by being the only voucher-related tool among many network management 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 explicitly states when to use each action (list, create, delete, delete_all) and gives parameter guidance. However, it does not compare to alternatives or mention when not to use this tool.

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 indicate destructiveHint=true and idempotentHint=false; the description adds context like caution against hideName (probe overhead) and recommendations for specific use cases. No contradiction with 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 purpose and required fields, followed by bullet-pointed optimization tips. Structured and readable, though slightly lengthy. Could be trimmed without losing value.

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 the three actions, required parameters for create, and key configuration advice. Missing explicit return value or error handling, but for a management tool that's typical. References list_wifi for pre-checks.

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 92% schema description coverage, baseline is 3. The description adds meaningful guidance beyond schema, e.g., optimal data rates, guest network isolation, and power-saving settings. Some parameters (e.g., enabled) lack extra detail.

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

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

The description clearly states the tool performs create, update, or delete operations on WiFi SSIDs (broadcasts). It distinguishes from sibling tools like list_wifi by explicitly referencing it for viewing existing configs.

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 specific requirements for CREATE (listing mandatory parameters) and optimization tips for key fields. Suggests using list_wifi before modifying. Lacks explicit alternatives or when-not-to-use beyond that.

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=false, so the description adds context about persisting to a file but does not detail overwrite behavior or that previous profiles are replaced. No contradictions with 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?

Two sentences, front-loaded with the core action. Every sentence is informative without waste. No unnecessary 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?

Given the tool's simplicity (one parameter with full schema) and the description covering purpose and prerequisite, it is complete. No output schema, but the description implies the persistence effect. Could mention overwrite behavior.

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

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

Schema description coverage is 100%, so the schema already documents the 'profile' parameter fully. The description adds no additional semantic meaning beyond the schema, meeting the baseline of 3.

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 'save', the resource 'network profile', and specifies that it persists to a specific file path. It distinguishes from sibling tools, none of which perform saving of profiles.

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 states 'Only call this after completing the init discovery flow', which is a clear when-to-use guideline. However, it does not mention alternatives or when not to use this tool, so it's slightly 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?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds context that the returned IDs are for execute_action and that the tool is a discovery mechanism, which is helpful beyond annotations.

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

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

Two concise sentences: first states purpose, second gives usage guidance. No unnecessary words or redundancy.

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

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

Description explains what the tool returns (action IDs) and how to use them (execute_action). However, no output schema exists, so more detail on return format or pagination would be beneficial, but it's adequate for an agent.

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 descriptions cover all 4 parameters (query, category, readOnly, limit) with clear details. The description does not add extra meaning beyond what the schema already provides.

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

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

The description clearly states it searches the UniFi action catalog and returns action IDs for execute_action. It distinguishes from the direct tool list and mentions category-focused discovery, making the purpose unambiguous.

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

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

Explicitly says to use when the direct tool list is too large or for category-focused discovery. This provides solid guidance, though it could name specific alternative tools (e.g., list_* tools) for clarity.

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