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

Annotations already establish readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context by stating that the response includes the full match criteria and action, which tells the agent this is not just a summary fetch. 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?

A single compact sentence leads with the verb and resource, with the clarifying parenthetical adding value without redundancy. Every part 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 get-by-ID tool, the description, 100% schema coverage, read-only annotations, and existing output schema provide everything needed for correct invocation. No significant contextual gaps remain.

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

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

Schema coverage is 100% and both parameters have descriptive names plus 'Site ID' and 'ACL rule ID' descriptions. The description's 'by ID' maps to aclRuleId but adds no format, constraints, or relationship 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 states a specific verb and resource: 'Get a specific ACL rule by ID', making the tool's purpose immediately clear. The parenthetical '(full match criteria and action)' signals that this returns detailed rule content, distinguishing it from sibling tools like unifi_list_acl_rules and unifi_get_acl_rule_ordering.

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 'specific ACL rule by ID' clearly implies this tool is for retrieving one known rule, not listing or reordering. It does not explicitly name alternatives or exclusion conditions, but the context is clear enough for an agent to select it appropriately.

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

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

Annotations already declare readOnlyHint=true, and the description confirms a read operation. It adds useful behavioral context by noting that 'Rules higher in the list win', which explains evaluation order. 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 sentences, front-loaded with action, and no unnecessary words. Every sentence adds value: verb, resource, return format, and ordering semantics.

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 (as indicated by context signals), the description sufficiently covers the operation. It mentions the return format and ordering rule. Could be more complete by noting that the site must have ACL rules, but overall adequate for a read-only tool with one parameter.

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

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

Schema coverage is 100% with the parameter 'siteId' described as 'Site ID'. The description does not add further semantics beyond what the schema provides, 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?

Description clearly states 'Get the evaluation order of user-defined ACL rules' with a specific verb and resource. It also mentions the return format. However, it does not explicitly differentiate from sibling tools like unifi_get_acl_rule or unifi_list_acl_rules, though context implies differentiation.

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

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

No guidance on when to use this tool versus alternatives such as unifi_list_acl_rules or unifi_get_firewall_policy_ordering. The description does not mention prerequisites or conditions, leaving the agent to infer 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 indicate read-only and non-destructive behavior. The description adds that the output shape mirrors that of 'unifi_list_clients', providing valuable behavioral context about return consistency. 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 a single sentence that conveys all essential information without any redundancy. It is appropriately sized 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?

The description, combined with annotations and schema, provides sufficient context for a simple get-by-ID tool. The mention of 'connected client' adds slight ambiguity (vs. all clients), but overall it is complete enough given the tool's simplicity and existing structured data.

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 'siteId' and 'clientId' described. The description does not add additional meaning beyond the schema, so it effectively meets the baseline for parameter semantics.

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

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

The description clearly states the verb 'Get', the resource 'specific connected client', and the identifier 'by ID'. It also distinguishes from the sibling tool 'unifi_list_clients' by noting the same shape, 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?

The description implies usage when a single client's details are needed by ID, and the mention of 'same shape as unifi_list_clients entries' indirectly contrasts with listing. However, it lacks explicit when-not-to-use or alternative scenarios, which would elevate clarity.

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 mark the operation as readOnlyHint=true and destructiveHint=false. The description adds behavioral context by enumerating the deep configuration fields returned and warning that the LIST endpoint returns capability-tag arrays instead of structured objects, which affects how the agent should interpret responses.

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

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

The description is dense but front-loaded with the core purpose before enumerating fields. Every sentence adds distinguishing value (return fields, list-endpoint difference, use cases, alternative), though the return-field list is somewhat long and may be covered by the output schema.

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

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

For a parameter-light read tool with an output schema present, the description covers the main selection context: what the endpoint is for, how it differs from the list endpoint, and when to use the statistics tool instead. No crucial call-time information appears missing.

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

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

Both schema parameters have descriptions ('Site ID', 'Device ID') and schema description coverage is 100%, so the description is not required to elaborate. It adds no further semantics about ID formats or how to resolve them, but the schema already covers the meaning. 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 opens with 'Get full configuration for a device', which names the verb and resource precisely. It distinguishes itself from unifi_list_devices by specifying fields only available in the detail endpoint and from unifi_get_device_statistics by contrasting live stats. This removes ambiguity among the get/list siblings.

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

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

The description explicitly states 'Use for: switch port layout/PoE state, AP radio config, uplink topology' and directs 'For live throughput/CPU/memory, use unifi_get_device_statistics.' This gives concrete conditions and names the alternative tool, leaving no inference needed.

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 the operation read-only and non-destructive. The description adds meaningful context by documenting API version verification, the absence of per-switch-port counters, and the limitation on port-level live stats—valuable 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 dense but organized: it leads with the core purpose, lists representative return fields compactly, and then covers limitations and routing to the sibling tool. Every sentence earns its place with no filler.

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

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

With an output schema present, the description need not fully detail return values; it already covers the tool's use cases, its API-level limitation, and its relationship to unifi_get_device. An agent has everything needed to invoke it correctly and avoid misapplications.

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

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

The input schema already describes both required parameters (siteId, deviceId) at 100% coverage, and the description adds no extra parameter-level guidance. However, the parameter names and schema descriptions are sufficiently self-explanatory for this simple case.

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

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

States a specific verb ('Get') and resource ('latest live statistics for a device'), and enumerates the returned metrics, making the tool's scope obvious. It also distinguishes itself from unifi_get_device by noting that config operations belong to that sibling.

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 this tool for device health and AP radio metrics, and names the alternative unifi_get_device for configuration tasks. It also warns that per-port switch byte/error/PoE-power counters are not available, preventing misuse.

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 destructiveHint=false. The description adds that the return fields match the list entry, which is useful but limited. 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?

Extremely concise single sentence, front-loaded with the key 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?

For a simple get-by-ID tool with annotations and output schema, the description is fully adequate. It mentions that fields match the list entry, which is helpful context.

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 descriptions for both parameters. The description adds no extra semantics beyond 'by ID', 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 'Get a specific DNS policy by ID', which is a specific verb+resource. It distinguishes from sibling list endpoints like unifi_list_dns_policies by targeting a single record.

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 implicitly indicates use when a specific ID is known, but lacks explicit when-not or alternative guidance. Given the name and context, an agent can infer the appropriate usage.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds that the response includes 'full match criteria and action,' which provides some insight into the output but does not disclose other behavioral traits like authorization needs or performance characteristics. This adds moderate value.

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

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

The description is a single, well-structured sentence that efficiently conveys the tool's purpose and a key aspect of its output. It is front-loaded and contains no unnecessary words. However, it is very brief and could benefit from slightly more 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?

Given the low complexity (2 simple parameters), the presence of an output schema, and annotations covering safety, the description is minimally adequate. However, it lacks usage guidance and does not elaborate on the 'full match criteria and action' phrase, so it is not fully self-sufficient.

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

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

Schema coverage is 100% with descriptions for both parameters (siteId, firewallPolicyId). The description does not add any additional meaning or format details beyond the schema, so the baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Get') and resource ('firewall policy by ID'), and adds specificity with 'full match criteria and action.' This differentiates it from list tools and other get tools by resource type, though it does not explicitly contrast with sibling tools.

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

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

No guidance on when to use this tool versus alternatives (e.g., listing policies with unifi_list_firewall_policies). The description simply states what it does without contextualizing its usage, leaving the agent to infer.

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 readOnlyHint=true and destructiveHint=false. The description adds that the tool returns 'beforeSystemDefined[] and afterSystemDefined[] arrays', which is behavioral context. However, it does not disclose any additional traits like authentication needs, rate limits, or what happens if the pair doesn't exist.

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-loads the purpose, and includes return structure. 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 the tool's simplicity (3 required params, read-only, output schema exists), the description adequately explains what the tool returns and the ordering. It could mention that it only applies to user-defined policies, but it does. Minor omission: no description of what happens when no policies exist.

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

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

The input schema has 100% coverage with brief descriptions for all three parameters. The description does not add any extra meaning, such as format, constraints, or examples. Since schema coverage is high, 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 states a specific verb ('Get') and resource ('evaluation order of user-defined firewall policies') with a clear scope ('for a specific (source zone, destination zone) pair'). This differentiates it from sibling tools like unifi_list_firewall_policies which list all policies, and unifi_get_firewall_policy which gets a single policy.

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 by stating what the tool does, but it does not explicitly say when to use this tool versus alternatives like unifi_list_firewall_policies or unifi_get_firewall_policy. There is no guidance on prerequisites or exclusions.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful context by stating 'same fields as the list entry', informing the agent about output consistency. No additional behavioral details needed for a simple read operation.

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

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

The description is a single sentence, front-loaded with the action, and contains no superfluous information. It is optimally concise.

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 presence of an output schema, the description is nearly complete. It could briefly mention that the output matches list entries, which it does. No major 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 coverage is 100% with clear descriptions for both parameters (Site ID, Firewall zone ID). The description adds no new meaning beyond what the schema provides, which is adequate for a simple get-by-ID tool.

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

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

The description clearly states the action (Get), resource (firewall zone), and method (by ID). It also differentiates from list tools by noting 'same fields as the list entry', 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?

Usage is implied: use when you need a single zone by ID, while list tools for all zones. However, no explicit when-not or alternative guidance is provided, 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it is 'verified against 10.6.106' and that the API 'returns ONLY applicationVersion' with 'no isUniFiOSConsole or other field', which helps an agent avoid expecting extra fields.

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

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

Three short sentences each carry distinct information: what it does, what it returns, and when to use it. The important 'returns ONLY applicationVersion' caveat is front-loaded, and there is no filler.

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

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

For a zero-parameter, read-only tool with an output schema, the description covers purpose, return value, behavioral limitation, and intended usage context. Nothing critical is missing for an agent to select and invoke 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 tool has zero parameters, so the baseline is 4. There are no parameter details to explain, and the description does not introduce any confusing parameter references.

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

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

The description states a specific verb and resource, 'Get UniFi Network application info', and immediately names the concrete return value, 'applicationVersion'. This cleanly distinguishes it from the many sibling unifi_get_* tools by identifying it as the version/info endpoint.

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 tells the agent when to use it: 'Use for: version checks before calling version-gated tools.' This is direct usage guidance even though no alternative tool is named, because the tool's purpose is unique among siblings.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety profile is covered. Description adds value by specifying that the tool returns the LAG type (with possible values LOCAL/SWITCH_STACK/MULTI_CHASSIS) and member ports. This is additional behavioral context beyond the schema, but no further operational details (e.g., error handling, consistency guarantees) are provided.

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

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

Single sentence of 17 words, no unnecessary information. Every word serves a purpose: verb, resource, output details. Extremely concise while being informative.

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

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

For a simple read-only tool with two straightforward parameters, full annotations, and an output schema, the description is complete. It tells the agent what the tool does and what information it returns. No critical gaps for correct invocation.

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

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

Schema coverage is 100% with descriptions for both parameters ('LAG ID' and 'Site ID'). The description does not add extra semantic meaning to the parameters beyond what is in the schema. Baseline score of 3 applies since schema is complete.

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

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

Description clearly states the action ('Get full details of a LAG') and specifies the resource ('a LAG'). It includes specific details about the output (type with enum values and member ports), which distinguishes it from sibling list tools like unifi_list_lags. The singular 'a LAG' implies it operates on a specific LAG, making 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?

Description provides no guidance on when to use this tool versus alternatives. It does not mention the need for a siteId or lagId, nor contrasts with unifi_list_lags (which lists LAGs) or other get tools. No context on prerequisites, typical use cases, or when not to 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known as a safe read operation. The description adds context about the content of the details (peer switches and member LAGs), which goes beyond the annotations and informs the agent of what to expect.

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, clear sentence with no unnecessary words. It is front-loaded with the verb and resource, and every word 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 that an output schema exists to document return values, the description is adequate. It specifies what the tool returns (full details, peer switches, member LAGs), which is complete enough for an agent to understand its purpose. Minor omission: no mention of prerequisites like the domain existing, but that is implicit.

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

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

Schema description coverage is 100%, with each parameter having a basic description (Site ID, MC-LAG Domain ID). The tool description does not add any additional meaning or nuance beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description clearly states the tool retrieves full details of an MC-LAG Domain, including peer switches and member LAGs. It distinguishes from sibling tool unifi_list_mc_lag_domains, which lists domains rather than retrieving 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 implies usage when full details of a specific domain are needed, but it does not explicitly mention when not to use it or suggest alternatives like unifi_list_mc_lag_domains for listing domains first. Usage context is only implied.

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

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

The annotations already cover read-only and non-destructive behavior, so the description need not repeat that. It adds value beyond the schema by summarizing the exact fields returned (e.g., 'live-verified' flags, ipv4Configuration, ipv6Configuration) and the contrast with the list view. This gives the agent concrete expectations about the response richness, which is useful context beyond what the output schema alone conveys.

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

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

The description is a single dense paragraph, but every sentence carries important information: the core purpose, the full list of returned fields, and the critical distinction from the list tool. It is front-loaded with the primary action and then details, with no redundant fluff. The length is justified by the richness of the response it describes.

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 the tool has only two parameters, an output schema exists, and annotations cover safety, the description is complete. It tells the agent what the tool does, what it returns, and when to choose it over a sibling. There is nothing an agent would need to know to call this tool correctly that is missing.

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

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

Both parameters (siteId, networkId) have minimal schema descriptions ('Site ID', 'Network ID') with 100% coverage. The tool description does not add any additional meaning or usage context for these parameters, so it does not improve on 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 states a specific verb+resource ('Get a network/VLAN by ID') and immediately distinguishes it from the sibling list tool by noting the extra fields returned. This makes the tool's purpose unmistakable and clearly differentiates it from unifi_list_networks.

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 tells the agent when to use this tool over the list variant: 'subnet/DHCP detail appears here at get-by-id but NOT in unifi_list_networks (sparse list view).' This provides a clear decision rule for selecting the appropriate tool based on the need for detailed network configuration.

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 readOnly and non-destructive. Description adds that the return is referenceResources, providing useful behavioral context beyond annotations.

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

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

Two efficient sentences that front-load the purpose, include examples, and explain the return format. No wasted words.

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

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

With good annotations, full schema coverage, and output schema mentioned, the description is complete for a reference-listing 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 parameters are well-documented. Description does not add extra meaning to siteId or networkId beyond what schema provides.

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

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

The description clearly states the tool gets all objects referencing a network, with examples (WiFi broadcasts, firewall zones), and distinguishes it from siblings like unifi_get_network and unifi_list_networks.

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 before deleting a network to find dependencies. Does not mention when not to use or alternatives, but context is clear given 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses the response shape (id, deviceId, name, units[], lags[], metadata.origin) and a version-dependent naming caveat — 'units[] (named `members` before 10.6.106)' — which is valuable context not present in the schema or annotations. No contradiction with the annotations.

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

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

The description is two sentences with the core purpose front-loaded and the return-shape detail following. The field list is slightly dense, but every item (including the version caveat) earns its place by clarifying what the caller receives.

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 a 100%-covered two-parameter schema, readOnly annotations, and an output schema present, the description covers what the tool does, what it returns, and a version nuance. The only omission is not-found/error behavior for an invalid switchStackId, which is minor and rarely documented.

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 both parameters (siteId, switchStackId) are self-descriptive in the schema. The description itself adds no parameter-level detail, but none is needed since the schema already carries the meaning; baseline 3 applies.

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

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

The description opens with a specific verb and resource — 'Get full details of a Switch Stack' — and immediately scopes the tool's behavior with 'including all units and stacking topology.' It distinguishes itself from the sibling list tool by explicitly stating it returns the same fields as the list response but for a single stack, so an agent can tell it apart from unifi_list_switch_stacks without opening either schema.

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

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

The phrase 'Returns the same fields as the list response but for a single stack' clearly implies this tool is for fetching one stack's full details while the sibling list tool returns multiple stacks. However, it never names the alternative tool explicitly or provides an exclusion statement, leaving the when-to-use decision implied rather than direct.

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

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

Annotations already mark the tool as readOnlyHint=true and destructiveHint=false, so the description adds only minor context by noting that the response contains the 'full items array'. No mention of rate limits, permissions, or other behavioral traits beyond what is implied by 'Get'.

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, front-loaded sentence with no extraneous words. It efficiently conveys the essential action and scope, though it could be slightly expanded to include usage hints 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 tool's simplicity, two required parameters, and presence of an output schema, the description is adequate but lacks context about when to use this vs. other list tools. It does not explain what a traffic matching list is or how the ID relates to other operations, leaving gaps for a new 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 input schema covers 100% of parameters with clear descriptions for `siteId` and `trafficMatchingListId`. The description does not add any additional semantic value beyond what the schema already provides, so it meets the baseline without improvement.

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 ('Get') and the resource ('a specific traffic matching list by ID'), distinguishing it from sibling tools like `unifi_list_traffic_matching_lists`, which retrieves all lists. The mention of '(full items array)' further clarifies the scope of the returned data.

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

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

The description implies usage when you have a specific ID, but it does not explicitly contrast with list tools or explain when not to use it. No context is provided for prerequisites or alternatives, making it minimally 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 provide readOnlyHint=true and destructiveHint=false, indicating safe read behavior. The description adds minor value by clarifying return structure consistency with list entries, but no additional 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?

One sentence conveying essential purpose and a key behavioral note. No wasted words; perfectly concise.

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, presence of output schema, and comprehensive annotations, the description provides all necessary context alongside structured fields.

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, with each parameter already described ('Site ID', 'Voucher ID'). The description adds no new meaning beyond the schema, so 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?

Description states 'Get a specific hotspot voucher by ID' – a clear verb+resource pair. Also notes 'same fields as the list entry' to distinguish from listing endpoints, effectively differentiating from unifi_list_vouchers.

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?

Implicitly guides using this when a specific voucher ID is known, contrasting with list tools. However, no explicit 'when not to use' or direct mention of sibling 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=true and destructiveHint=false, so the description adds value by detailing that the tool returns additional optional fields like clientFilteringPolicy and blackoutScheduleConfiguration. This goes beyond the annotations, providing useful behavioral 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?

The description is a single, well-formed sentence that front-loads the primary action and then lists specific fields. Every word adds value; there is no redundancy or filler. It is maximally concise while conveying essential information.

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

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

Given the low complexity (2 required parameters, 100% schema coverage, and an output schema present), the description is complete in explaining what extra fields are provided relative to the list tool. It could mention error handling, but the presence of an output schema reduces the need for that. Overall, it adequately covers the tool's context.

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

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

The input schema has 100% coverage, with both parameters (siteId, wifiBroadcastId) having clear descriptions. The description does not add new semantic information about the parameters themselves; it focuses on the output scope. Hence, baseline score of 3 is appropriate.

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

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

The description clearly specifies the verb 'Get', the resource 'full configuration for a WiFi broadcast (SSID)', and distinguishes itself from list tools by emphasizing it includes optional fields not returned by unifi_list_wifi. It also lists specific fields, leaving no ambiguity 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 explicitly states that this tool returns optional fields not always returned by the list counterpart, guiding the agent to use this when full configuration is needed. Although it doesn't explicitly mention when not to use it, the context is clear enough to differentiate from the sibling list 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 declare readOnlyHint=true and destructiveHint=false, and the description adds substantial context beyond them: the exact return fields, the read-only nature of 'index' with a pointer to the mutation tool, and the architectural fact that ACLs apply earlier in the path than firewall policies. 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?

The purpose is front-loaded in the first sentence, and the field enumeration in sentence two is dense but each item carries semantic value (IPV4/MAC types, ALLOW/BLOCK actions, read-only index). Slightly long, and the return enumeration partially overlaps with the existing output schema, but no sentence is wasted.

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

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

For a read-only list tool with full annotation coverage, 100% parameter documentation, and an output schema, the description supplies everything an agent needs: scope, sibling differentiation, return field semantics, mutation routing, and path-ordering context. Nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters (siteId, limit, filter, offset). The description adds no parameter-specific meaning beyond the schema; 'at a site' only redundantly maps to siteId. The baseline of 3 applies since the schema carries the full weight.

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

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

States a specific verb ('List'), resource ('ACL rules'), and scope ('at a site'), and immediately distinguishes itself from zone-based firewall policies with the parenthetical 'switch/AP-level access control lists, distinct from zone-based firewall policies'. This cleanly differentiates it from siblings like unifi_list_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 provides clear when-not guidance ('distinct from zone-based firewall policies') and names unifi_reorder_acl_rules as the correct tool for changing the index. It does not explicitly name unifi_list_firewall_policies as the alternative for zone-based policies, but the exclusion is unambiguous enough that an agent can route correctly.

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 destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context beyond annotations: it clarifies the data is inventory rather than session history, warns that errors never mean zero activity, and notes retention depends on the controller. It doesn't describe pagination or exact response shape, but the output schema exists and the added context is meaningful.

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 with zero waste. The core purpose is front-loaded, the sibling distinction is immediate, and the caveats are compact. 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?

For a read-only list tool with an output schema, annotations, and 100% schema coverage, the description is nearly complete. It covers purpose, scope, prerequisites, error interpretation, and retention. The only minor gap is not describing pagination or result limits, but that is not critical given the output schema and the tool's read-only nature.

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 both parameters (withinHours and siteReference) with descriptions, defaults, and constraints. The description adds context about retention ('does not extend controller retention') and clarifies siteReference is the internalReference, not the Integration API UUID, which is useful. Baseline 3 is appropriate because the schema does the heavy lifting and the description adds only marginal semantic value.

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

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

The description states a specific verb ('List'), a specific resource ('historical/offline client inventory'), and the API used ('controller v2 API'). It explicitly distinguishes itself from the sibling tool unifi_list_client_sessions, so an agent can tell them apart without opening schemas.

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

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

The description explicitly says when to use this tool ('inventory, not session history') and names the alternative (unifi_list_client_sessions) for past connections. It also gives a prerequisite ('Requires controller history API-key support') and a caveat about interpreting errors ('errors never mean zero activity').

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

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

Beyond the readOnlyHint annotation, the description discloses important behavioral caveats: ipAddress is frequently absent, the client schema is minimal and identical across types, and signal strength, channel, and per-port binding are not exposed. It also notes the version against which behavior was verified. This is meaningful, non-obvious 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?

The description is compact and information-dense, front-loading the purpose and return fields followed by caveats and alternatives. A slight redundancy exists between 'currently connected' and 'who's online right now,' but every other sentence carries unique 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 output schema covers return structure and the input schema covers parameters, the description fills all remaining gaps: absent fields, schema limitations, and the distinction from history/session tools. An agent has everything needed to call this tool correctly and interpret risks.

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 limit, filter, offset, and siteId. The description does not add parameter-level detail beyond what the schema provides, placing it at the baseline for fully covered schemas.

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 opens with a precise verb and resource: 'List currently connected clients at a site.' It is immediately distinguishable from related siblings by explicitly stating that disconnected/historical clients are not in the Integration API and directing to unifi_list_client_history and unifi_list_client_sessions.

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 clearly states when to use this tool ('who's online right now') and when not to use it ('Disconnected/historical clients are NOT in the Integration API'), naming specific alternative tools. This is explicit and leaves no 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?

Beyond the readOnlyHint/destructiveHint annotations, the description discloses that the endpoint is a POST that 'only reads statistics', explains truncation semantics, retention-dependent row availability, and warns against over-interpreting Wi-Fi association bytes and is_guest. This is substantial behavioral transparency that protects the agent from common misuse.

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 compact yet dense; every sentence delivers a distinct operational or interpretive fact. The primary purpose is front-loaded, and there is no filler or repetition of schema details, making the length justified.

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

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

With an output schema available and full parameter documentation, the description still covers remaining decision-critical areas: pagination behavior, truncation handling, retention caveats, ongoing-session omission, and data interpretation guardrails. Nothing an agent needs to invoke or filter this tool correctly is missing.

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

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

Even with 100% schema coverage, the description adds meaning: it reinforces that start/end form a UTC epoch-second window capped at 31 days, frames 'mac' as a truncation workaround, and links 'limit' to the need for a narrower window or MAC filter for full results. This goes well beyond the schema's property 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 opens with 'Read retained past client connections, including disconnected clients, from the controller stat/session query endpoint', giving a specific verb, resource, and scope. It clearly signals historical/session data rather than live client state, and the 'may omit ongoing sessions' caveat further distinguishes it from listing or current-client 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 provides clear operational context: 'Use an explicit UTC epoch-second window (max 31 days)', 'The controller ignores offset pagination', and a concrete remediation when mayBeTruncated is true ('split the time window... or filter by MAC'). It does not name an alternative sibling tool or give an explicit when-not-to-use, but the retention and ongoing-session caveats imply when a different tool is needed.

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 communicate readOnlyHint=true and destructiveHint=false. The description adds useful behavioral details beyond that: it is a global list, returns ISO alpha-2 codes and names, and clarifies the downstream usage. This adds meaningful context without contradicting 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?

Two concise sentences deliver the global scope, return shape, and usage guidance with no filler. The key purpose is front-loaded and 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?

For a simple read-only list operation, the description plus the complete input schema, annotations, and output schema provide everything an agent needs to select and invoke the tool. It states what is returned, why the result matters, and how to use it.

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

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

All three parameters (limit, filter, offset) are already fully documented in the input schema with descriptions and defaults. The tool description adds value mainly for the returned code field rather than the parameters, so the schema carries the burden and the description does not need to compensate.

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

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

The description uses the specific verb 'List' with a clear resource, 'countries/regions (global)', and ties it to a concrete use case: geo-IP firewall rules. The scope and purpose clearly distinguish it from the many sibling list/get 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?

It clearly states when to use the tool: when listing countries for geo-IP firewall rules, and explains the returned code should be used when building firewall policies matching by country. It does not explicitly mention when not to use it or name alternatives, so it misses the top tier.

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

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

The description goes well beyond the readOnlyHint/destructiveHint annotations by disclosing the exact returned fields, the meaning of state values, and a key behavioral nuance: features/interfaces are string arrays here while unifi_get_device expands them into objects. It also clarifies the scope to 'adopted devices'.

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 information-dense but well organized: scope, returned fields, an important caveat, and usage guidance are all present in a compact, readable form. No filler or redundant restatement of the name exists.

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 list operation with read-only annotations, a complete input schema, an output schema, and a large sibling family, the description provides everything needed: return shape, scope, and explicit routing to the complementary tools. The pagination defaults are already covered by the schema, so nothing critical is missing.

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

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

Schema coverage is 100%, and every parameter (siteId, limit, offset, filter) already has a description naming its purpose and defaults. The tool description adds no new parameter-level meaning beyond the schema, so the baseline of 3 is appropriate.

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

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

The description uses a specific verb ('List') with a clear resource ('all adopted devices at a site') and names device types (gateways, switches, APs). It also distinguishes itself from unifi_get_device and unifi_list_pending_devices by clarifying scope and representation.

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 usage guidance is provided: 'Use for: device inventory' and pairing with unifi_get_device for full config and unifi_get_device_statistics for live metrics. This clearly tells an agent when to select this tool and which siblings to use for deeper detail.

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 destructiveHint=false, so the safety profile is covered. The description adds the site-scoped nature and the return shape (id, name, deviceIds[]), complementing the annotations with useful result and scope context. 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?

Three short sentences, front-loaded with the action, then domain context, then return shape. Every sentence earns its place; neither schema data nor annotation flags are repeated.

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 read-only listing tool: annotations cover safety, the schema documents all parameters including pagination defaults, an output schema exists, and the description explains the domain purpose and return fields. Nothing an agent needs to call it correctly is missing.

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

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

Schema description coverage is 100% — all four parameters (siteId, limit, offset, filter) are documented in the schema. The description adds only the site-scope context and domain purpose of tags, not per-parameter meaning, so the baseline 3 applies.

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

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

States a specific verb and resource — 'List device tags at a site' — and adds domain grounding by explaining that tags group APs/switches for selective WiFi broadcast via broadcastingDeviceFilter. The Returns clause names exact fields (id, name, deviceIds[]), and no sibling tool covers device tags, so there is no ambiguity.

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

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

Provides clear context about when the data matters: tags are referenced via broadcastingDeviceFilter on WiFi networks, so an agent configuring selective WiFi broadcast needs this list. It names no explicit alternatives or exclusions, but since no sibling tool exists for device tags, differentiation is a minor concern.

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 destructiveHint: false, so the safety profile is clear. The description adds context about what is returned (local DNS records and forward rules) and the return fields, which is useful beyond the annotations. 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 concise, front-loaded with the purpose, and every sentence adds value. It lists return fields without extra fluff, making it efficient for an agent to parse.

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 moderate complexity, the description covers the purpose, scope, and return fields. Since an output schema exists, return types are already structured. The only minor gap is not explaining the filter parameter's syntax, but the schema covers that.

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 parameters like limit, offset, and filter are well documented. The description does not add extra meaning beyond what the schema provides, but it is not needed. Baseline 3 is appropriate.

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

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

The description clearly states the tool lists DNS policies (local DNS records and forward rules) at a site, with a verb (List) and resource (DNS policies). It distinguishes from the sibling unifi_get_dns_policy by implying a list operation versus a single-item retrieval. The enumerated types add specificity.

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 'at a site' and the required siteId parameter implies the usage context, but it does not explicitly state when to use this over alternatives like unifi_get_dns_policy. However, the list nature is clear, and for a list tool, that is adequate 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=true and destructiveHint=false, so safety is covered. The description adds meaningful behavior context by noting the 'global' scope and the exact return fields ('id (numeric), name'), which helps the agent understand output shape and data source beyond what annotations provide.

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 main action and resource, provides examples, states the return value, and gives sibling differentiation in a compact, scannable format.

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

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

For a simple read-only list tool, the description covers the key contextual needs: global scope, granularity relative to a sibling, and return fields. The output schema exists and the input schema is complete, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so the schema fully documents all three parameters (limit, filter, offset). The description does not add any parameter-specific guidance, but with complete schema coverage the baseline of 3 is appropriate.

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

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

The description states a clear verb ('List') and resource ('individual DPI applications (global)'), gives concrete examples ('Netflix', 'Zoom', 'Steam'), and explicitly differentiates from a sibling tool ('More granular than unifi_list_dpi_categories'). This makes the tool's scope unmistakable.

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 names the alternative unifi_list_dpi_categories and positions this tool as more granular, which gives the agent a clear reason to select it over that sibling. However, it does not state an explicit when-not-to-use condition or mention other potential alternatives, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds useful context about the return shape ('id (numeric), name') and the global scope, which is beyond what annotations provide. However, it doesn't disclose pagination behavior, default limits, or what happens when no categories exist, so it adds some but not rich 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?

The description is two sentences with zero waste. The core purpose and scope are front-loaded, followed by the return shape and a practical usage note. 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 is complete for a simple list tool: it states the resource, scope, return fields, and a practical use case. The output schema exists, so return values are already documented. The only minor gap is that it doesn't mention pagination defaults, but the schema covers the parameters and the annotations cover safety, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (limit, filter, offset). The description does not add any parameter-specific meaning beyond what the schema provides. Baseline 3 is appropriate since the schema does the heavy lifting.

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

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

The description states a specific verb ('List'), a specific resource ('DPI categories'), and a key scoping constraint ('global, not site-scoped'). It also gives concrete examples of what the categories look like ('Streaming', 'Social Networks', 'Gaming'), which makes the tool's purpose immediately clear. This distinguishes it from sibling tools like unifi_list_dpi_applications, which likely lists applications rather than high-level categories.

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 this tool: when building firewall policies that match by category. It also clarifies the global scope, which implies it is not for site-scoped filtering. However, it does not explicitly name an alternative tool or state when NOT to use it, so it falls just short of a 5.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context by enumerating the returned fields and warning that protocols/ports are encoded inside source/destination.trafficFilter, not as top-level fields. This helps prevent mistaken assumptions about the response shape.

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

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

The description is dense and efficient: it front-loads the core purpose, then lists key return fields, highlights an important encoding caveat, and points to the ordering tool. Every sentence contributes useful 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?

Given the annotated read-only behavior, an output schema, and full parameter schema coverage, the description is complete for an agent to select and invoke the tool. It even clarifies where nested data (trafficFilter) lives and directs the agent to a separate tool for evaluation order, which is the main adjacent context.

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

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

Schema description coverage is 100%, with parameter descriptions for siteId, limit, filter, and offset. The tool description adds no additional parameter-specific guidance, so the baseline 3 is appropriate. The 'at a site' phrasing reinforces siteId's role but doesn't go 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 states a specific verb and resource: 'List firewall policies (zone-based rules) at a site.' This clearly distinguishes it from related tools like unifi_get_firewall_policy (singular) and unifi_get_firewall_policy_ordering (ordering).

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

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

The description provides clear context: this tool lists multiple firewall policies at a site. It also explicitly routes evaluation-order needs to unifi_get_firewall_policy_ordering, which is a useful alternative. It does not state exclusions for when to use the singular getter, but the listing vs. getting distinction is sufficiently implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' verb is consistent. The description adds useful interpretive context by noting that metadata.origin distinguishes system-defined vs user-defined zones, but it does not disclose pagination behavior, default limits, or other runtime behavior beyond what the schema already 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?

Three compact sentences front-load the action, then define the return fields and the primary use case. Every sentence contributes useful information, and there is no filler or redundant restatement of schema 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?

For a list operation with 100% schema parameter coverage and an output schema, the description is nearly complete: it gives purpose, scope, return-field semantics, and a related tool. The only moderate gap is not describing pagination/default behavior in prose, though the parameter descriptions already cover limit and offset.

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

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

Schema description coverage is 100%, with limit, filter, offset, and siteId each already described. The description only reinforces the site-level scope and return fields; it adds no new parameter-level meaning, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource ('List firewall zones') with a clear scope ('at a site') and defines what firewall zones are ('groupings of networks for zone-based firewalling'). The summary of returned fields (id, name, networkIds[], metadata.origin) makes the list/inventory nature unmistakable and distinguishes it from the singular unifi_get_firewall_zone sibling.

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

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

It gives an explicit intended use ('Use for: zone inventory') and points to a complementary tool ('pair with unifi_list_firewall_policies to see rules between zones'). It does not explicitly state when NOT to use this tool or when to prefer the singular getter, so it stops short of full when/when-not guidance.

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

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

Annotations already indicate readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by enumerating the return shape, including the type enum values and metadata.origin, which helps the agent understand what the operation exposes beyond a simple list.

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 filler: the first states the operation and context, the second summarizes the return fields. The key information is front-loaded and 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?

For a simple, read-only list operation with full schema coverage, a safe annotation profile, and an output schema present, the description is complete. It identifies the required scope, the resource, and the return shape without needing to repeat pagination or auth details that are already structured elsewhere.

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

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

The input schema fully describes all four parameters with meaningful descriptions, including defaults and max for limit and offset, so the baseline is 3. The description's 'at a site' aligns with the required siteId but adds no new parameter-level semantic detail beyond the schema.

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

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

States a specific verb and resource: 'List LAGs (Link Aggregation Groups — bonded switch ports) at a site.' The description defines the domain term and scope, and the return fields clarify what is being listed. The verb 'List' plus the LAG resource clearly differentiates it from sibling get/list 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 makes the tool's purpose clear and implies it is for listing LAGs at a site, but it does not explicitly state when to prefer this over alternatives like unifi_get_lag or unifi_list_mc_lag_domains. No exclusions or alternative routing are provided, leaving usage inference to the agent.

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

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

Annotations already mark it read-only and non-destructive, and the description adds the domain concept and returned fields. It does not go beyond the schema to disclose behaviors such as pagination implications, rate limits, or site-scoping caveats, so it only modestly supplements 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?

One concise sentence establishes the resource and concept, followed by a short return-field list. No filler, repeated schema information, or redundant phrasing.

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 a fully documented input schema, an output schema, and read-only annotations, the description is sufficient for safe invocation. The only missing guidance is explicit sibling differentiation, which is a usage-guideline concern handled elsewhere.

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

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

Schema description coverage is 100%, with limit, filter, offset, and siteId all documented in the input schema. The description adds no additional parameter guidance, so it stays at the baseline for high-coverage schemas.

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 opens with the verb 'List' and the exact resource 'MC-LAG Domains', then defines the concept. It clearly contrasts with sibling unifi_get_mc_lag_domain via list vs get and with unifi_list_lags by specifying MC-LAG domains.

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

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

No explicit when-to-use or alternative routing is stated. The list-vs-get distinction is implied by the name, and the conceptual definition makes the use case reasonably clear, but the description does not tell the agent when to choose this over similar list/get tools.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered. The description adds genuine behavioral context beyond annotations: the list view omits ipv4Configuration/ipv6Configuration and the semantic meanings of fields like default, zoneId, and metadata.origin. 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?

Purpose is front-loaded and the note about sparse views precedes usage guidance, which is the right priority order. The field enumeration slightly overlaps with the output schema, but it adds semantic gloss (e.g., 'default (true for the default network)') that justifies its place. Dense but not padded.

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

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

With an output schema present and read-only annotations, the description covers what remains: purpose, return shape, the sparse-view caveat, and routing to sibling tools. The only thin area is filter-expression semantics, which belongs to the schema anyway. Nothing an agent needs to invoke it safely and correctly is missing.

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

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

Schema coverage is 100%, with descriptions and default/max values for limit and offset already in the input schema. The description ties siteId to site scope ('at a site') but adds no parameter syntax or filter-format details; baseline 3 is appropriate since the schema carries the burden.

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

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

Begins with a specific verb-resource pair: 'List all networks (VLANs/LAN segments) at a site', defining the ambiguous term 'network' as VLANs/LAN segments. It distinguishes itself from siblings by explicitly contrasting the sparse list view with unifi_get_network for detail.

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

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

Gives explicit when-to-use ('Use for: VLAN inventory'), explicit when-not-to-use ('the list view is sparse — for subnet/DHCP/NTP detail... call unifi_get_network on a specific id'), and a pairing strategy with unifi_get_network_references. No inference is required from the agent.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context beyond annotations: it specifies the global scope, notes that it returns basic device info per pending device, and transparently caveats that the exact per-row schema is not rendered in the 10.6.106 docs. This is useful behavioral context 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?

The description is compact and front-loaded: the core purpose and global scope appear first, followed by return-value details and a specific use case. Every sentence earns its place, including the documentation caveat about the schema.

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

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

Given the annotations, output schema, and 100% schema parameter coverage, the description is largely complete. It covers scope, use case, and return-value shape. The only minor gap is that filter expression syntax is not explained, but this is partially mitigated by the schema's own description.

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

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

Schema description coverage is 100%, with limit, filter, and offset all described in the schema. The tool description adds no additional parameter-level semantics, so the baseline of 3 is appropriate.

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

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

The description names a specific verb and resource: 'List devices pending adoption across all sites'. It also differentiates from siblings by stating it is a global endpoint, not site-scoped, which clearly separates it from unifi_list_devices and unifi_get_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?

The description explicitly states when to use the tool: 'Use for: discovering new devices on the network before calling unifi_adopt_device'. It lacks an explicit when-not-to-use or alternative routing, but the given use case is clear and actionable.

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 destructiveHint=false, covering the safety profile. The description adds useful domain context about what RADIUS profiles are referenced by, but does not disclose additional behavioral traits such as pagination limits or authentication requirements. This is 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 a single, focused sentence followed by a brief return-value note. It front-loads the core action and uses no filler words, making it easy for an agent to parse quickly.

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 operation with a required siteId, four well-documented parameters, read-only annotations, and an output schema, the description adds enough domain context to be complete. It explains the resource's role while the structured fields handle the remaining details.

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

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

Schema description coverage is 100%, so all four parameters are already documented with meaningful descriptions. The tool description does not add parameter-specific details, but the schema carries the full burden. A baseline of 3 is appropriate here.

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

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

The description states a specific verb and resource ('List RADIUS profiles') and clarifies the domain by explaining these are auth/accounting server configurations referenced by WiFi WPA-Enterprise, switch 802.1X port auth, and VPN. This clearly distinguishes it from the many sibling list/get tools, which target different UniFi 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 parenthetical explanation gives clear context for when this tool is relevant: managing RADIUS profiles used in enterprise WiFi, 802.1X switch authentication, and VPN. It does not explicitly name exclusions or alternatives, but no obvious sibling tool duplicates this resource, so the guidance 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=true and destructiveHint=false, so the safety profile is covered. The description adds useful context beyond those annotations: the tool is scoped to sites the API key can access, and its returned id is required by other tools. It does not mention pagination or rate limits, but this is a simple read-only listing.

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 tightly packed sentences: one states the action and return value, the other states workflow placement. No filler, and the most important fact—that siteId is needed elsewhere—is front and center.

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

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

With an output schema present and fully described optional parameters, the description is largely complete for a simple read-only list tool. It could have briefly noted pagination/default-limit behavior, but the schema already provides limit/offset defaults.

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?

All three parameters already have schema descriptions with defaults and an example filter expression, so the schema carries the load. The description adds no parameter-level meaning, so the baseline score of 3 applies.

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

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

The description uses a specific verb and resource ('List all sites') and adds a scope qualifier ('the API key has access to'), immediately distinguishing this tool from the many get/list siblings. It also states what is returned and why the returned id matters.

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

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

It explicitly says 'Use for: first call in any workflow — almost every other tool needs a siteId,' which gives clear workflow context and sequencing. It does not name explicit when-not conditions or alternatives, but as a bootstrap list tool that exclusion is less critical.

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 destructiveHint=false, so safety is covered. The description adds value by documenting the returned fields, the version-dependent naming difference (units vs members), and the caveat that per-unit schema is not rendered in 10.6.106 docs.

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

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

The description is front-loaded with the core definition and scope, then efficiently covers return fields, a version-specific caveat, and sibling tool routing. No sentence is filler, and the structure is easy to scan.

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 provides return-field expectations, version-specific naming behavior, a schema-rendering caveat, and explicit routing to related tools. Combined with the annotations and output schema, it gives an agent everything needed to select and invoke this 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%, so all four parameters are documented in the input schema. The description adds no parameter-specific meaning beyond the schema, which is acceptable and matches the baseline for fully covered schema parameters.

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

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

The description uses a specific verb and resource ('List Switch Stacks') with an explicit scope ('at a site') and a parenthetical definition of what a switch stack is. It also distinguishes this list operation from unifi_get_switch_stack by noting that per-unit inspection requires that sibling tool.

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

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

The description gives a clear 'Use for' statement and explicitly routes to alternatives: unifi_get_switch_stack for per-unit schema inspection and unifi_get_device for individual member configs/stats. This provides actionable selection guidance without 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?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds useful context about the resource being named collections of ports/IPs reused in firewall/ACL rules, but it does not disclose any additional behavior beyond listing, such as pagination behavior or filter syntax, which would go beyond the schema.

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

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

The description is three short sentences: the main action is stated first, followed by a compact return-shape summary and an explicit use case. There is no redundant or wasted text, while still covering purpose, output, and usage intent.

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 and annotations cover the read-only/destructive profile, the tool is mostly complete with the description adding the domain purpose. The only minor gap is that it does not clarify when to choose this list endpoint over the singular unifi_get_traffic_matching_list, or explain the filter expression format, but these are not critical for a simple list operation.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema: it only mentions 'at a site', which maps to the existing siteId parameter description. No additional syntax or defaults are explained in the 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?

The description names a specific verb and resource ('List traffic matching lists at a site') and adds a clarifying definition of what those lists are. It does not explicitly differentiate itself from the sibling unifi_get_traffic_matching_list, though the plural 'List' and returned array shape imply the distinction.

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 'Use for:' statement that tells an agent this tool is meant for finding the matching-list ID to reference from a firewall policy, which is actionable usage guidance. It does not provide exclusions or mention alternatives such as unifi_get_traffic_matching_list for fetching a single list.

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 destructiveHint=false, covering safety. The description adds value by documenting return fields and clarifying that activatedAt means when first guest used it, plus a concrete stale-voucher filter use case. It does not contradict 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?

Two focused sentences with no filler. The core purpose is front-loaded, followed by a concise field list and a practical filter example. 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?

Given a complete input schema, an output schema, and safety annotations, the description is fully sufficient for an agent to call this tool correctly. It explains the resource scope, key return fields, and a common filtering use case, so nothing critical is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters and the filter example. The description reiterates the filter usage but adds minimal parameter meaning beyond the schema, so the 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 states a specific verb ('List') and resource ('hotspot/guest-portal vouchers at a site'), and the detailed return-field list makes it easy to distinguish from sibling tools like unifi_get_voucher or unifi_list_sites. It is unambiguous and informative.

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 this tool: to list vouchers at a site and to bulk-find stale vouchers via filtering. It does not explicitly exclude alternatives like unifi_get_voucher for single-voucher lookups, but the list-vs-get distinction is strongly implied.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds value by disclosing the return shape ('id, type, name, enabled, metadata.origin') and example enum values ('WIREGUARD, UID'), which helps the agent anticipate output beyond what annotations provide. 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 concise sentences deliver the resource scope and return shape with zero filler. The verb and resource are front-loaded, and every element (protocols, site scope, return fields) 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 read-only list tool with a required siteId, a well-documented schema, and an output schema present, the description is fully adequate. It explains what is listed, where, and the salient output characteristics. No missing detail would prevent an agent from selecting and invoking 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%, so the baseline is 3. The description does not add parameter-level details beyond the schema; 'at a site' merely restates the siteId purpose already present in the schema. It does not clarify the filter expression format or pagination subtleties, but those are already documented.

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

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

The description opens with the verb 'List' and identifies the resource 'VPN servers' with clarifying qualifiers ('roaming/client-access VPNs: WireGuard, OpenVPN, L2TP, Teleport'), which precisely distinguishes this from site-to-site VPN tunnel tools. It further enumerates the returned fields, leaving no doubt 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 phrase 'roaming/client-access VPNs' gives clear context about the intended scope (client-access, not site-to-site), and 'at a site' ties directly to the required siteId parameter. However, it does not explicitly name an alternative tool (e.g., unifi_list_vpn_tunnels) for site-to-site VPNs, so the guidance is clear on scope but lacks explicit exclusions.

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

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

Annotations already indicate a safe read-only operation (readOnlyHint=true, destructiveHint=false). The description adds useful behavior beyond that: it discloses that results are tunnel definitions per row and flags that the per-row schema is not rendered in the current docs, advising an inspection call. This is valuable context even though pagination behavior is left implicit.

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 compact and front-loaded, leading with the verb and resource. Every sentence earns its place: the first defines the scope, the second explains the return shape and docs caveat, and the third routes to the appropriate sibling tool.

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

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

For a simple list tool with full schema coverage, a safe read-only annotation profile, and a declared output schema, the description is complete. It covers what the tool returns, the scope, and the relevant alternative.

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 input schema already documents all four parameters. The description adds only the contextual notion of 'at a site,' which maps to the required siteId parameter, but does not meaningfully extend parameter semantics 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 uses a specific verb ('List') and resource ('site-to-site VPN tunnels'), further specifying the tunnel types (IPsec, WireGuard, OpenVPN site-to-site) and scope ('at a site'). It also explicitly distinguishes itself from unifi_list_vpn_servers, making its 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?

The description clearly states this tool is for site-to-site tunnels and explicitly points to unifi_list_vpn_servers for roaming client VPN servers. This gives an agent a direct decision rule for choosing between the two related tools.

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