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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered without the description. The parenthetical 'full match criteria and action' adds a small hint about the richness of the returned entity, but with an output schema present this is largely redundant context rather than new behavioral disclosure.

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 short sentence that is front-loaded with the verb and resource; every clause earns its place. It is arguably under-specified rather than over-long, so not a full 5.

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

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

For a simple two-parameter read tool with full schema coverage, complete annotations, and an output schema that carries the return shape, the description covers the essentials. Only the absence of sibling routing (vs. unifi_list_acl_rules / unifi_get_acl_rule_ordering) leaves a minor gap.

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

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

Schema description coverage is 100% and both parameters (siteId, aclRuleId) are documented in the schema, so the baseline is 3. The description confirms the ID is the lookup key but adds no format, pattern, or scoping 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 (Get) and resource (a specific ACL rule) with the lookup key (by ID), which distinguishes it from unifi_list_acl_rules. It does not explicitly name the sibling it is not, so the differentiation is implicit rather than stated.

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

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

There is no when-to-use guidance, no prerequisite statement, and no mention of the alternative (unifi_list_acl_rules) for discovering an ID. The 'by ID' phrasing only weakly implies you must already have the identifier.

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 this as a safe read operation (readOnlyHint, non-destructive, non-openWorld). The description adds useful domain semantics — that rules are evaluated in list order — but says nothing about permissions, aliasing with unifi_get_firewall_policy_ordering, or any other behavioral trait.

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

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

Two short sentences, front-loaded with purpose and then the return semantics. Zero filler; every clause carries information.

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

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

For a one-parameter read-only getter with an output schema, the description is largely sufficient. Restating the return field borders on redundant given the output schema, but the ordering semantics are a genuine addition.

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

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

There is a single parameter (siteId) whose schema description coverage is 100%, so the schema already documents it fully. The description adds no parameter-level 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 ('Get the evaluation order of user-defined ACL rules'), which is clearly distinct from unifi_list_acl_rules and unifi_get_acl_rule. It doesn't explicitly name those siblings, so an agent must infer the distinction from the name alone.

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

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

There is no explicit when-to-use guidance and no mention of alternatives such as unifi_list_acl_rules or unifi_get_acl_rule. The intended use (determining rule precedence) is only implied by the description.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The only added behavior is that the result matches unifi_list_clients entry shape, which is largely restated by the output schema. No auth, error, or not-found behavior is disclosed, so a 3 is appropriate given the annotation coverage.

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

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

Two short sentences, front-loaded with the core action and followed by the one useful contract detail. No filler or repetition of the title.

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

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

An output schema exists, so return values need not be re-explained, and the two required params are fully documented. Annotations cover the read-only nature. The definition is nearly complete for a simple getter, with only the not-found/permission behavior left unstated.

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

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

Schema description coverage is 100% for both parameters, so siteId and clientId are already documented by the schema. The description's 'by ID' adds no format, constraint, or scope detail beyond what the schema supplies, 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 ('Get a specific connected client') and pins the access key ('by ID'), which separates it from the list-style siblings. It also names unifi_list_clients to anchor the return shape. It stops short of a crisp sibling-vs-sibling routing statement, so 4 rather than 5.

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

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

Usage is only implied: 'specific ... by ID' versus the list tool makes the single-record lookup case inferable, but there is no explicit 'use this when you already have a clientId' or a 'for all clients use unifi_list_clients' exclusion. Adequate but leaves the agent to infer the choice.

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

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

Annotations already establish read-only, non-destructive, closed-world semantics, and the description adds genuine behavioral caveats: uplink.deviceId is absent on the ISP modem, speedMbps may be omitted on DOWN ports, and some devices (5G modems) return empty features/interfaces. Much of the remaining text describes return content that the output schema already covers, so it lands just short of a 5.

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

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

The purpose and usage routing are correctly front-loaded, but the middle is a dense single block of nested parenthetical field enumerations that is hard to parse and largely duplicates the declared output schema. It is information-rich yet not efficiently structured.

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

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

An output schema exists, so return values need not be re-explained, and the description still covers purpose, usage routing, sibling alternative, and cross-endpoint caveats. Nothing an agent needs to select or invoke 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?

Only two parameters, both required and at 100% schema description coverage ("Site ID", "Device ID"), so the baseline is 3. The description adds no format, ID-source, or lookup guidance beyond what the schema states.

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 ("Get full configuration for a device") and immediately distinguishes the detail endpoint from the list endpoint's capability-tag arrays. An agent can tell it apart from unifi_list_devices and unifi_get_device_statistics without opening any schema.

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

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

Explicitly enumerates use cases ("switch port layout/PoE state, AP radio config, uplink topology") and names the alternative for the excluded case ("For live throughput/CPU/memory, use unifi_get_device_statistics"). This is a textbook when-to-use / when-not-to-use split.

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

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

Annotations already declare readOnly/openWorld=false/destructive=false, so safety is covered; the description nonetheless adds real behavioral value by flagging version-verified limitations ('does NOT expose per-switch-port byte/error/PoE-power counters') and conditional field absence (uplink missing on the ISP modem, interfaces empty for non-APs). Some of the 'Returns:' enumeration overlaps the output schema, which slightly dilutes the addition.

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

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

Front-loads purpose, then use cases, then the alternative — a good ordering. The long 'Returns:' field enumeration is denser than needed given an output schema exists, but it is not padded or vague.

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

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

For a two-param read tool with annotations and an output schema, the description covers purpose, routing to the sibling, conditional field behavior, and version-specific data gaps. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100% for both parameters (siteId, deviceId), so the schema already carries the semantics; the description adds no format, constraint, or lookup guidance beyond it. 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 ('Get latest live statistics for a device') and explicitly contrasts itself with the sibling unifi_get_device by scope (live stats vs. config). An agent can route between the two without opening either schema.

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

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

Gives explicit use cases ('device health and AP radio metrics') and an explicit exclusion with the named alternative ('For config (channel, power, port assignment), use unifi_get_device'). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds only that fields match the list entry, which is a minor return-shape note already implied by the existing output schema; no auth, error, or rate-limit context is 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?

A single short sentence with the key action front-loaded and no filler. The parenthetical about list-entry fields is the only marginally wasteful element given an output schema 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 two-parameter read tool with a full output schema and complete annotations, the minimum viable information is present. It stops short of stating the relationship to the list tool or any failure conditions, leaving clear but minor gaps.

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

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

Schema description coverage is 100%, so the schema already documents siteId and dnsPolicyId. The description's 'by ID' hints at the dnsPolicyId parameter but adds no syntactic or format detail beyond the schema; 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: retrieving one DNS policy by ID. The name plus description clearly distinguish it from the sibling unifi_list_dns_policies. The trailing parenthetical adds little but doesn't obscure the purpose.

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

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

There is no statement of when to use this versus unifi_list_dns_policies or any other sibling, and no prerequisites mentioned (e.g., needing a siteId and an ID obtained from the list call). Usage is only inferable from the tool name.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds meaningful context by specifying that the return matches a list-policies entry and naming fields like loggingEnabled and reportFlowEnabled, but since an output schema exists this is largely confirmatory rather than new behavioral disclosure.

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 zero waste; the core action is front-loaded and the return-shape note follows. Every clause 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 two-parameter read with complete annotations and an output schema, the description is nearly sufficient. The only gap is the absence of routing guidance relative to the list sibling, which is minor given the tool's simplicity.

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

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

Schema description coverage is 100% for both parameters (siteId and firewallPolicyId), so the schema already carries the meaning. The description adds nothing about parameter format or constraints beyond what the schema provides, making the baseline 3 appropriate.

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

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

The description opens with a specific verb and resource ('Get a firewall policy by ID') and scopes it further with 'full match criteria and action'. It also anchors the return shape to a named sibling (unifi_list_firewall_policies), letting an agent distinguish the single-item getter from the lister.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The phrase 'by ID' implies a single-item lookup, but the description never tells the agent to use unifi_list_firewall_policies first to obtain the ID, nor when to prefer one over the other.

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, destructiveHint=false and closed-world, so the safety profile is covered. The description adds the semantic that system-defined rules sit between the two returned arrays, which is useful context, but it discloses nothing about auth needs, rate limits, or edge cases.

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

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

Three tight sentences, purpose front-loaded, then return structure. No filler and every sentence carries information.

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

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

With an output schema present, the return-format sentence is somewhat redundant, but annotations and schema together mean the agent has what it needs to call this correctly. Only the when-to-use routing against siblings 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 all three IDs are documented in the schema; the description only reinforces that the zone parameters form a pair. Baseline 3 is appropriate when the schema does the heavy lifting, and no extra format or constraint detail is added.

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 (firewall policy ordering) and narrows the scope to a (source zone, destination zone) pair. An agent can distinguish it from siblings like unifi_list_firewall_policies and unifi_get_acl_rule_ordering without opening a schema.

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

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

The description implies when this is useful (to learn evaluation order for a zone pair) but never states when to use it versus alternatives like unifi_list_firewall_policies or how it relates to a sibling ordering endpoint. Usage is inferable but not explicit.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and a closed-world scope, so the safety profile is fully covered. The description's only added behavioral note is that the returned fields match the list entry, which is mild value and partly redundant given the output schema exists.

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

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

A single short sentence with the operation front-loaded and the parenthetical qualification trailing it. Nothing is wasted, though the extreme brevity leaves little room for routing or caveats.

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

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

For a read-only single-resource getter with full schema coverage, an output schema, and annotations covering safety, the description supplies what an agent needs to invoke it. A note about behavior when the ID is not found would make it complete.

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

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

Schema description coverage is 100% with both required params documented, so the baseline is 3. The description only reiterates that lookup is by ID, adding no format, constraint, or error-handling 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 ('Get a firewall zone by ID') and clarifies scope with '(same fields as the list entry)'. It implicitly separates itself from unifi_list_firewall_zones by its by-ID retrieval, though it never names the sibling explicitly.

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

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

The 'by ID' phrasing implies you call this when you already have a zone ID rather than enumerating, but there is no explicit when-to-use statement, no mention of when to prefer unifi_list_firewall_zones, and no note on what happens if the ID is unknown.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=false), so the bar is low. The description adds genuine behavioral context by disclosing that the Integration API returns no isUniFiOSConsole or other field — a real caveat that prevents an agent from assuming richer output. It doesn't discuss auth or rate limits.

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

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

Two sentences, zero waste, front-loaded with the action and the return payload before the usage note. Nothing redundant and nothing 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?

For a zero-param, read-only app-info tool with an output schema and full annotation coverage, the description supplies what is needed: what it returns, what it does not return, and when to reach for it. The 'Use for' clause is slightly narrow and referential, but nothing an agent needs in order to call it correctly is missing.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly avoids inventing parameter guidance and its note that only applicationVersion is returned prevents mistaking this for a parameterized query.

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 ('Get UniFi Network application info') and then names the exact payload ('applicationVersion only'), which cleanly separates it from every sibling that lists or retrieves site/device/client entities. An agent can identify it without opening any schema.

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

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

Explicitly gives a use case: 'checking the Network version when a tool's description notes version-specific behaviour.' This is clear context with a triggering condition. It stops short of a 5 because it names no alternatives or when-not-to-use condition, though no sibling meaningfully overlaps.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description's help. The description adds only the enum values and member ports, which is output content already carried by the existing output schema, so it contributes almost nothing behavioral beyond the structured fields.

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

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

A single front-loaded sentence that states the operation first and the returned detail second, with no filler or redundancy.

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

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

For a two-parameter read-by-ID tool with full annotations and an output schema, the description covers what the caller needs; the only gap is the absence of any note distinguishing a LAG from an MC-LAG domain or pointing at unifi_list_lags for ID discovery.

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

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

Schema description coverage is 100% for both parameters (lagId and siteId), so the schema already documents them fully. The description adds no format, sourcing, or lookup guidance for the IDs, making the baseline 3 appropriate.

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

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

States a specific verb (Get) and resource (LAG) plus the scope of the response (type LOCAL/SWITCH_STACK/MULTI_CHASSIS and member ports), so an agent knows exactly what comes back. It does not, however, differentiate itself from the closely related unifi_list_lags or unifi_get_mc_lag_domain siblings, which an agent could plausibly confuse with this 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 single-resource-by-ID shape and the required lagId/siteId imply the standard drill-down pattern after unifi_list_lags, but the description never states when to use this versus list or mc-lag-domain tools, and gives no prerequisites or exclusions. Usage is inferable rather than stated.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile needs no restating. The description adds genuine scope context by naming what the 'full details' comprise (peer switches, member LAGs), but says nothing about errors when an ID is not found or any size/rate considerations. Adding the return-content scope earns it above baseline without reaching rich behavioral disclosure.

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

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

A single front-loaded sentence with no filler. The resource is named first and the clarifying parenthetical is placed where it helps most.

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

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

An output schema exists, so return values need not be explained, and 100% schema coverage documents both IDs. The only real gap is the absence of when-to-use guidance relative to the list/get siblings, which for a small read tool is a minor omission.

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 are fully documented in the schema (100% coverage) with type, pattern and description, so the schema does the heavy lifting. The description adds no syntax, format or sourcing guidance for siteId or mcLagDomainId beyond what the schema already provides; 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 gives a specific verb ('Get') plus resource ('MC-LAG Domain') and clarifies the payload contents (peer switches and member LAGs). It is clearly distinguishable from unifi_list_mc_lag_domains and unifi_get_lag, though it never explicitly names those 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?

There is no statement of when to use this tool versus unifi_list_mc_lag_domains or unifi_get_lag, and no prerequisite guidance (e.g., that a domain ID must first come from the list tool). Usage is only implied by the word 'Get'.

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 a safe read (readOnlyHint=true, destructiveHint=false), and the description adds real behavioral context: 'live-verified' field reliability, the empty-string caveat in ntpServerIpAddresses, and the conditional presence of ipv6Configuration. It does not disclose auth needs or rate limits, keeping it below a 5.

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

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

The purpose is correctly front-loaded in the first four words, but the rest is a long comma-chained enumeration of return fields that the output schema already covers. It is information-dense rather than padded with filler, yet the field lists strain readability.

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, enumerating return fields is largely redundant, so the description's real contribution is the list-vs-get sparseness distinction and the empty-string caveat, both genuinely useful. For a 2-param read tool with full annotations and an output schema, 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 both parameters (siteId, networkId) are already documented in the schema. The description adds only 'by ID', which maps to networkId but contributes no new syntax or format meaning beyond the existing pattern constraint.

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 ('Get a network/VLAN by ID') and explicitly names the sibling it differs from (unifi_list_networks), so an agent can distinguish it 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 NOTE establishes a clear selection rule: this tool carries subnet/DHCP detail that the sparse list view lacks. It effectively tells the agent when to prefer this over unifi_list_networks, though it stops short of an explicit 'use this when you need full detail' phrasing or any prerequisites.

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

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

Annotations already establish readOnlyHint/destructiveHint=false, but the description adds substantial unstated behavior: the precise return structure and a documented controller bug (HTTP 500 api.unexpected-error on 11.0.83) with a working fallback procedure. That is exactly the kind of environment-specific behavior an agent cannot get from 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 every sentence carries weight (purpose, return shape, usage, failure fallback). It is slightly long, and since an output schema exists, enumerating the return shape in the description is mildly redundant, keeping it just under a 5.

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

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

With an output schema and safety annotations already present, the description still covers everything else an agent needs: dependency-finding intent and a fully specified recovery path for the known 500 error. Nothing required to invoke it correctly is missing.

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

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

Schema description coverage is 100% and both required params (siteId, networkId) are fully documented in the schema with patterns. The description adds no syntax or semantic detail for the parameters, so the baseline of 3 is appropriate.

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

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

The description states a specific verb (Get) and resource (objects that reference this network) and immediately clarifies the returned relationship shape. It is clearly distinguishable from siblings like unifi_get_network or unifi_list_networks, which return the network itself rather than its dependents.

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 trigger ("Use before deleting a network to find dependencies that need to be re-pointed or removed") and, on failure, names concrete alternatives (unifi_list_wifi + unifi_get_wifi, unifi_list_firewall_zones) with the exact field paths to inspect. This is model when-to-use/fallback guidance.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuine value beyond that: the exact returned fields, plus the version caveat that `units` was named `members` before 10.6.106, which an agent would otherwise misread as a different field.

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

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

Two sentences, front-loaded with the purpose and then the return contract. The field enumeration is dense but earns its place because of the `members`/`units` version caveat; without that caveat it would be redundant with 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 two-required-param read-only detail endpoint with 100% schema coverage and an output schema, nothing essential is missing. The description even goes beyond the minimum by flagging the historical field-name change, so an agent parsing results across controller versions is not surprised.

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 required params (siteId, switchStackId) are documented in the schema with patterns, so the schema does the heavy lifting. The description adds nothing about parameter syntax or sourcing, which is the expected baseline when coverage 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?

States a specific verb and resource ('Get full details of a Switch Stack') plus scope ('including all units and stacking topology'), which cleanly separates it from unifi_list_switch_stacks and the get_lag / get_mc_lag_domain 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 mention that it 'Returns the same fields as the list response but for a single stack' implies the list-vs-get relationship, but there is no explicit when-to-use guidance, no prerequisite (e.g. siteId/switchStackId must come from a listing call), and no stated 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, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The parenthetical '(full items array)' adds useful context about response shape distinguish it from the list endpoint's summaries, but no other behavioral traits are disclosed; with annotations carrying the load, a 3 is appropriate.

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

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

A single tight sentence with no filler, and the retrieval key is front-loaded. Efficient and appropriately sized.

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

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

An output schema exists so return values need not be explained, annotations cover safety, and both required parameters are documented. The definition is nearly complete, only lacking explicit routing guidance versus the list sibling.

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% - both siteId and trafficMatchingListId are documented in the schema with patterns. The description only repeats that retrieval is by ID and adds no format or constraint detail beyond what the schema already provides.

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

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

States a specific verb ('Get'), resource ('traffic matching list'), and retrieval key ('by ID'), which cleanly separates it from unifi_list_traffic_matching_lists. It does not explicitly name that sibling, so differentiation is implicit rather than stated.

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

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

Usage is implied by 'by ID' - fetch one list when you have its identifier versus enumerating via the list sibling. No explicit when-to-use or when-not-to-use guidance is given.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that the response has the same fields as the list entry, which is modest but useful behavioral context; it does not mention permissions, rate limits, or error behavior, so a 3 is appropriate given the annotation coverage.

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

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

It is a single, front-loaded sentence with no wasted words. The key identifying information (specific voucher by ID) comes first.

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

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

An output schema exists, annotations cover the safety profile, and both required parameters are fully documented in the schema. For a simple get-by-ID tool, the description is nearly complete; only explicit usage guidance relative to the list sibling is missing.

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

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

Schema description coverage is 100%, with 'Site ID' and 'Voucher ID' documented in the schema itself. The description implies lookup by ID but adds no syntax, format, or constraints beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description states a specific verb (Get), resource (hotspot voucher), and scope (a specific voucher identified by ID). This clearly distinguishes it from the sibling unifi_list_vouchers, which lists rather than retrieves 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?

No explicit when-to-use guidance, prerequisites, or alternative recommendations are given. The clause 'same fields as the list entry' hints at redundancy with unifi_list_vouchers but does not tell the agent when to prefer this tool over the 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?

Beyond the readOnlyHint/destructiveHint=false annotations, it discloses meaningful behavior: which optional config blocks are omitted when unconfigured, and that passphrases come back as '[REDACTED]' unless includeSecrets is true. That redaction detail is a genuine security-behavior disclosure an agent needs. It stops short of describing error or auth behavior.

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

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

The purpose is front-loaded in the first clause, which is good. However, the remainder is a single run-on sentence enumerating a long list of field names that largely duplicates what the output schema already provides, so much of the text does not earn 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?

An output schema exists, so return values need not be detailed, and annotations already cover the read-only safety profile. What the description must supply — the conditional redaction and the omission of unconfigured optional blocks — is present, leaving only sibling routing and error context unaddressed.

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 siteId, wifiBroadcastId and includeSecrets are all documented in the schema itself. The description restates the includeSecrets redaction semantics but adds no new syntax, format, or defaulting detail beyond that. Baseline 3 applies when the schema carries the parameter burden.

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

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

States a specific verb and resource: 'Get full configuration for a WiFi broadcast (SSID)'. An agent can immediately tell this retrieves a single SSID's config, distinct from the sibling unifi_list_wifi. It does not, however, explicitly name the list sibling to route between them.

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

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

Usage is implied (a point-lookup for a specific broadcast), and the description notes the includeSecrets condition for returning plaintext passphrases. But it never states when to use this versus unifi_list_wifi, nor any prerequisites such as needing the broadcast ID from a prior list call.

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

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

Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower, yet the description still adds real behavior: index is read-only evaluation order and must be changed via unifi_reorder_acl_rules, plus the domain note that ACLs apply earlier in the path than firewall policies. It doesn't mention pagination limits or filter syntax, which is a minor remaining gap.

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

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

Front-loaded with the purpose and sibling distinction, then the field list. The enumerated 'Returns:' fields partly duplicate the output schema that already exists, making some of the text redundant, but overall it is dense and free of 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 list tool with a read-only annotation set and an output schema, the description covers identity, scope, ordering semantics, and the reorder path. The only shortfall is that the return-field enumeration overlaps the output schema rather than adding new information.

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% (siteId, limit, offset, filter all documented in-schema), so the schema carries parameter meaning. The description only implies site scoping with 'at a site' and adds nothing about limit/offset/filter semantics, which is the expected baseline when the schema does the heavy lifting.

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

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

Names a specific verb and resource ('List ACL rules') and immediately scopes it: 'switch/AP-level access control lists, distinct from zone-based firewall policies'. An agent can separate this from unifi_list_firewall_policies 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 'distinct from zone-based firewall policies' clause effectively routes the agent to the firewall-policy siblings when that is what's wanted, and the index note explicitly points to unifi_reorder_acl_rules for changing order. It stops short of stating prerequisites or when-not-to-use conditions, so it is clear context without full 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 only cover the safety profile (readOnlyHint, destructiveHint, openWorldHint), and the description goes well beyond them: API-key dependency, error semantics, controller-dependent retention, result ordering, totalCount and truncated behavior, and the limit-vs-withinHours trade-off. These are exactly the traits an agent needs and none are in 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?

Dense but front-loaded: purpose, expclusions, and sibling routing come first, then operational caveats. The final sentence enumerating row fields ('mac, hostname, display_name...') partially duplicates the output schema, which is minor waste, but the rest of the text is high-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?

For a filtered list tool with an output schema already present, the description covers everything else an agent needs: scope, exclusions, ordering, truncation, error interpretation, retention limits, and API-key prerequisites. Nothing consequential is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuinely useful semantics the schema lacks: result ordering is 'most recently seen first up to limit', and narrowing withinHours drops the same clients excluded by truncation. That interaction between limit/truncated/withinHours is real added value over the per-parameter docs.

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

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

States a specific verb+resource ('List historical/offline client inventory') and immediately scopes it: 'Returns OFFLINE clients only — currently connected clients are excluded.' It names the two siblings that could be confused with it, unifi_list_clients and unifi_list_client_sessions, so an agent can route correctly without opening any schema.

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

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

Explicit when-to-use and when-not-to-use guidance: merge with unifi_list_clients for a full inventory, and use unifi_list_client_sessions for past connections rather than this tool. It also states the precondition ('requires controller history API-key support') and the failure interpretation ('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?

Annotations already cover safety (readOnly, non-destructive, closed-world), but the description adds substantial context: version-verification status, which client types are live-verified vs not, and what the API schema deliberately omits (signal strength, channel, per-port binding). This is rich disclosure beyond the annotations.

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

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

Front-loads the core purpose and return fields, then packs caveats and routing into the tail. Dense but every clause carries information; only the field enumeration is arguably slightly over-detailed given an output schema 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 read-only list tool with full schema coverage, an output schema, and safety annotations, the description covers scope, alternatives, verification caveats, and API limitations. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so limit/offset/filter/siteId are already fully documented in the schema, including filterable fields. The description adds no parameter syntax or format detail beyond that, 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 with explicit scope ('List currently connected clients at a site'), and enumerates the returned fields. It clearly distinguishes itself from unifi_list_client_history and unifi_list_client_sessions by emphasizing 'currently connected' vs historical records.

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

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

Explicitly says 'Use for: who's online right now' and states that disconnected/historical clients are NOT available here, naming the two sibling tools to use instead. The when-to-use and when-not-to-use conditions are fully specified.

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

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

Annotations already declare readOnlyHint and destructiveHint=false, and the description adds real value on top: it explains that a POST here only reads statistics (pre-empting the false impression that POST implies mutation), that results are bounded by controller retention and may omit ongoing sessions, that mayBeTruncated signals truncation, and that Wi-Fi association/bytes do not prove end-to-end Internet success. These are substantive behavioral caveats not present in the structured fields.

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

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

Front-loaded with purpose, then constraints, then failure-mode handling, then caveats; no filler sentences. It is dense and slightly long, with some row-field enumeration that overlaps the output schema, but each clause carries actionable information.

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

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

For a filtered read tool with 100% schema coverage, an output schema, and explicit read-only annotations, the definition covers everything an agent needs: window construction, retention limits, truncation handling, pagination behavior, and interpretation caveats for the byte/association 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?

Schema description coverage is 100%, so the schema already documents start, end, mac, limit, and siteReference, and the description adds little beyond restating the UTC epoch-second window and 31-day cap. Marginal added meaning (MAC filtering as a truncation workaround) keeps it at the baseline rather than below it.

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

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

States a specific verb and resource ('Read retained past client connections... from the controller stat/session query endpoint') and clarifies that disconnected clients are included, which is more than the name conveys. However it never distinguishes itself from the very similar sibling unifi_list_client_history, so an agent must guess which session/history tool to pick.

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

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

Gives concrete operational guidance: use an explicit UTC epoch-second window with a 31-day maximum, and if mayBeTruncated is true, split the window (overlapping boundaries and deduplicating IDs) or filter by MAC. It also warns that offset pagination is ignored. It stops short of naming when to prefer this over unifi_list_client_history or unifi_list_clients.

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 this is a safe read (readOnlyHint=true, destructiveHint=false, openWorldHint=false), lowering the bar. The description adds that this is a global reference list (not tenant/site scoped) and enumerates the returned fields, which is useful behavioral context beyond the safety profile.

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 tight sentences, front-loaded with the purpose and scoping, followed by the practical usage tip. No filler or redundancy.

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

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

An output schema exists so return values need not be re-explained, and annotations cover the safety profile. For a simple global reference-list tool, the description supplies everything needed 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?

Schema description coverage is 100%, so limit, filter, and offset are already documented in the schema with examples. The description adds no parameter-level meaning, making the baseline 3 the correct score.

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

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

States a specific verb (List) plus resource (countries/regions) and scope qualifier (global, for geo-IP firewall rules), which cleanly separates it from site-scoped list siblings like unifi_list_firewall_zones or unifi_list_networks. An agent can tell what it returns (code/name) without opening the schema.

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

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

Explicitly tells the agent to use the returned code when building firewall policies matching by source/destination country, which gives clear context for when the tool applies. It stops short of naming alternatives or exclusions, but for a static reference-list lookup the intended usage is fully conveyed.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: that features/interfaces are returned as string arrays here while unifi_get_device expands them into objects, which prevents misinterpretation of the payload.

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

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

Front-loaded with purpose, then return fields, then the array caveat, then usage routing. It is dense but every sentence serves a purpose; the enumerated return-field list is slightly redundant given an output schema exists, which keeps it short of a 5.

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

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

With an output schema present, the description needn't explain return values, yet it still flags the array-vs-object distinction that the schema alone wouldn't convey. Usage, scope, and sibling routing are all covered for a simple filtered-list tool.

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

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

Schema description coverage is 100%, so all four parameters (including the filter grammar and limit/offset) are already documented in the schema. The description adds no parameter-level detail beyond that, which is the correct baseline when the schema does the heavy lifting.

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

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

Starts with a specific verb+resource ('List all adopted devices (gateways, switches, APs) at a site'), which is more precise than the sibling unifi_list_pending_devices by scoping to adopted devices, and clearly distinct from unifi_get_device. An agent can identify this as the inventory-list tool without opening the schema.

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

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

Provides explicit routing: 'Use for: device inventory; pair with unifi_get_device for full config (port table, radios) and unifi_get_device_statistics for live metrics.' It names both alternatives and the condition that selects each, leaving nothing to inference.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine behavioral context beyond that: it explains the semantic role of tags and how they connect to WiFi broadcast filtering. It stops short of mentioning pagination behavior, but that is a minor gap against annotated read-only safety.

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

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

Three short clauses, front-loaded with the core purpose and then the domain context and return shape. Every sentence carries information; no padding.

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

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

With a full input schema and an existing output schema, the description need not explain returns, though it lists them redundantly. Combined with the annotations, an agent has enough to call it correctly; only the absence of explicit sibling routing keeps it short of full marks.

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 (siteId, limit, offset, filter) are documented in the schema itself. The description adds no syntax or format detail beyond that, 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 real domain meaning by explaining what tags are (grouping APs/switches for selective WiFi broadcast). However it does not explicitly differentiate itself from the surrounding list_*/get_* siblings, so an agent must infer the distinction from naming conventions.

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 contextualizes tags via broadcastingDeviceFilter on a WiFi network, which implicitly signals why an agent would look them up. But there is no explicit when-to-use, when-not-to-use, or named alternative, leaving the routing decision to inference.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered without the description. The description adds the full field shape and the type enum values returned, which is useful behavioral context, but it says nothing about pagination behavior, default page size, or filter syntax beyond echoing 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?

Purpose and scope are front-loaded in the first clause before the field inventory. The long return-field enumeration is dense but each item earns its place by mapping record types to their fields; it is verbose 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?

A read-only list tool with an output schema, complete parameter descriptions and full annotations needs little more than a clear purpose statement, which this supplies. Its only real omission is routing guidance to unifi_get_dns_policy and any note on paging through large result sets.

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 limit, offset, filter and siteId are already documented in the schema, and the description adds no parameter meaning on top of that. Baseline 3 is appropriate when structured fields carry the parameter 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?

The description gives a specific verb+resource ('List DNS policies') and adds a clarifying gloss that these are local DNS records and forward rules served by the gateway. It never names its sibling unifi_get_dns_policy or states it returns a collection rather than one policy, so differentiation is left to the name alone.

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

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

There is no when-to-use guidance, no prerequisite (e.g. a valid siteId), and no mention of the alternative unifi_get_dns_policy for fetching a single rule. An agent must infer that this is the enumeration tool from the name only.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds the '(global)' scope and the id/name return shape, but says nothing about pagination behavior or the filter-totalCount caveat that lives only in 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?

Two tight sentences plus a return fragment, with the scope and sibling differentiation front-loaded. Every clause carries information 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?

An output schema exists, so return values need not be spelled out, and annotations carry the safety profile; the description still names the id/name fields for quick orientation. Complete enough for a zero-required-param list tool, though the filter/pagination interplay could have been surfaced here.

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

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

Schema description coverage is 100% and all three parameters (limit, filter, offset) are documented in the schema, including the important note that totalCount ignores the filter. The description adds no further 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 DPI applications) and pins down the scope as global with concrete examples ('Netflix', 'Zoom', 'Steam'). It explicitly contrasts itself with the sibling unifi_list_dpi_categories, so the agent can pick correctly 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?

'More granular than unifi_list_dpi_categories' gives a clear comparative cue about when to prefer this tool over its sibling. It stops short of explicit when-not-to-use conditions, but the granularity framing is enough for correct routing.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, openWorldHint=false, so safety is covered. The description adds genuinely useful context beyond that: the global (non-site-scoped) nature of the resource and the returned id/name shape. It does not mention pagination behavior, though the schema does.

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 tight sentences with zero filler, front-loading the resource identity and scope before the return shape and usage hint. Every clause 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?

With an output schema present and annotations covering the safety profile, the description only needs to add scope and usage context, which it does. Nothing an agent needs to call 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?

Schema description coverage is 100%, with limit, filter, and offset fully documented including the totalCount/ filter caveat. The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List DPI categories'), defines what DPI categories are with concrete examples ('Streaming', 'Social Networks', 'Gaming'), and distinguishes scope from siblings by noting it is 'global, not site-scoped'. An agent can tell it apart from unifi_list_dpi_applications without opening either schema.

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

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

Gives a clear downstream use case: 'Use the category id when building firewall policies that match by category.' This tells the agent why it would call this tool. It does not, however, explicitly contrast with the closely related sibling unifi_list_dpi_applications, leaving the category-vs-application choice to inference.

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

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

With annotations already covering read-only safety, the description adds substantial behavioral context: return field structure, action shape, where protocol and ports live, that trafficFilter is omitted for whole-zone matches, that unset optional fields are omitted rather than null, and that reportFlowEnabled is false on predefined policies.

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 purpose and then spends most of its length on return-shape details. It is dense but mostly earns its place by clarifying nested and omission semantics, though some of that may duplicate 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 list tool with full schema coverage, annotations, and an output schema, the definition is largely complete. The main gap is explicit usage guidance relative to unifi_get_firewall_policy and pagination behavior, though those are partly covered by the schema.

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

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

Schema description coverage is 100%, so the four parameters are already documented in the schema. The description does not add parameter-level meaning beyond what the schema provides, which is the baseline-3 case when structured data does the heavy lifting.

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

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

States a specific verb, resource, and scope: 'List firewall policies (zone-based rules) at a site.' It also distinguishes itself from the ordering sibling by noting that evaluation order comes from unifi_get_firewall_policy_ordering, so an agent can route between list, get, and ordering 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 implies usage through 'List firewall policies ... at a site,' but never explicitly says when to use this versus unifi_get_firewall_policy or unifi_get_firewall_policy_ordering. It references the ordering tool only for a related concern, not as a direct usage alternative.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds which fields are returned and the meaning of metadata.origin (system vs user-defined), but says nothing about permissions, pagination limits, or the filter/count quirk noted in 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?

Compact and front-loaded, using a clear 'Returns:' / 'Use for:' structure. Every clause earns its place with no filler.

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

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

Given an output schema exists, the return-value detail is optional but reinforces completeness, and the pairing hint aids correct usage. It remains slightly thin on operational constraints, but adequate for a read-only list tool.

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

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

Schema description coverage is 100%, so the schema already documents siteId, limit, offset, and the filter/count caveat. The description adds no parameter-level meaning beyond that, making the baseline 3 appropriate.

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

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

States a specific verb (List) and resource (firewall zones) and defines the concept inline as 'groupings of networks for zone-based firewalling at a site.' This cleanly separates it from the singular sibling unifi_get_firewall_zone and from 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?

Provides explicit usage context: 'Use for: zone inventory' and names the complementary sibling to pair with (unifi_list_firewall_policies). No when-not guidance or prerequisites are given, but the routing context is clear.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds domain context on LAG types (LOCAL/SWITCH_STACK/MULTI_CHASSIS) and their associated identifiers, which is helpful, but it discloses nothing about pagination behavior or rate limits.

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 tight sentences, front-loaded with the purpose and acronym expansion. The return-field enumeration is largely wasted effort given that an output schema exists, which is the only real structural inefficiency.

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 schema coverage and a dedicated output schema, the definition is essentially complete. The main shortfall is the absence of guidance on when to prefer this over unifi_get_lag or when to use filter versus limit/offset paging.

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 limit, offset, filter, and siteId are all documented in the schema, including a concrete filter expression example. The description adds no parameter-level detail beyond that, so the baseline of 3 applies.

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

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

States a specific verb and resource ('List LAGs') and disambiguates the acronym ('Link Aggregation Groups — bonded switch ports'), plus scopes it to a site. An agent can distinguish this from unifi_get_lag and unifi_list_switch_stacks immediately.

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 site scoping implies a siteId is required and the plural 'List' implies a collection read, but there is no explicit when-to-use guidance, no mention of the unifi_get_lag alternative for a single LAG, and no stated prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already establish readOnlyHint=true and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing the response shape and, more valuably, flagging a reliability caveat ('per the older 10.4.57 spec... not live-verified') that no structured field 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?

Front-loads the verb and resource, then the concept, then the return detail in one dense sentence. It is efficient overall, though the parenthetical is heavy and the enumerated return fields partly duplicate the output schema that already 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?

With an output schema present, return values need not be spelled out, and annotations cover the safety profile, so the description's remaining burden is light. It meets that burden and adds a useful spec-version caveat, missing only usage routing.

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 siteId, limit, filter, and offset are fully documented in the schema. The description adds no syntax, format, or default information beyond it, 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 MC-LAG Domains') and then defines the concept — 'pairs of switches presenting as one for LAG redundancy' — which distinguishes it from the adjacent unifi_list_lags and unifi_get_mc_lag_domain siblings. An agent can tell what this returns without opening a schema.

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

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

There is no when-to-use, when-not-to-use, or alternative routing guidance. Nothing tells the agent to prefer unifi_get_mc_lag_domain for a single domain or unifi_list_lags for individual LAGs, leaving selection to inference from the name alone.

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 genuine behavioral context beyond that: the list view is explicitly 'sparse', dhcpGuarding is 'only present when enabled', and metadata.configurable appears only on the system-defined default network. It does not mention pagination behavior (limit/offset interplay), which keeps it from a 5.

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

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

Front-loaded with the core action and scoping, then enumerates the return fields in a compact clause-run. It is information-dense rather than padded, though the long comma-separated field list and the trailing NOTE make it slightly dense 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?

Even though an output schema exists, the description usefully documents the actual returned fields and their conditional presence, and it routes the agent to unifi_get_network for detail the list omits. For a 4-parameter read tool with no destructive behavior, 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% — limit, filter, offset and siteId are all documented in the schema itself, including the API default of 25 and a filter expression example. The description adds no parameter detail, 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 all networks (VLANs/LAN segments) at a site') and immediately distinguishes itself from the sibling unifi_get_network by scoping itself to the sparse list view. An agent can tell what this returns and how it differs from the get-by-id tool 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?

Explicit routing: 'for subnet/DHCP/NTP detail ... call unifi_get_network on a specific id' names the alternative and the condition that selects it, and 'pair with unifi_get_network_references to find what consumes a network' gives a second concrete use. The 'Use for: VLAN inventory' clause adds a positive trigger.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, so safety is covered. The description adds real value beyond them by disclosing the global (non-site-scoped) endpoint behavior and by flagging that the exact per-row schema is undocumented in the 11.0.83 docs — an honest uncertainty disclosure.

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

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

Front-loads purpose, then returns, then usage in a tight structure with no filler sentences. The doc-version parenthetical is slightly noisy but earns its place as a transparency caveat rather than padding.

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

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

An output schema exists, so explaining return values is optional, yet the description still summarizes the key fields and notes the schema-uncertainty. Combined with annotations covering safety, an agent has enough to call it correctly; only explicit pagination/filter behavior notes are absent.

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

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

Schema description coverage is 100% (limit, filter, offset all documented with examples and defaults), so the baseline is 3. The description adds no parameter-level detail beyond the schema, which is acceptable given the schema does the work.

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

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

States a specific verb (List) and resource (devices pending adoption), and adds the crucial scope qualifier 'across all sites (global endpoint, not site-scoped)'. This distinguishes it from siblings like unifi_list_devices and site-scoped list tools without needing to open the schema.

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

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

Provides an explicit workflow trigger: 'Use for: discovering new devices on the network before calling unifi_adopt_device', naming the follow-up tool. It lacks an explicit when-not/exclusion clause, but the adoption-discovery context is clear enough for correct selection.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds domain context but no additional behavioral traits such as pagination, rate limits, or permission requirements; the listed return fields are already provided by the output 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 two tight sentences with the core purpose front-loaded and no redundant phrasing. Every clause earns its place by naming the tool's function and domain 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?

With a full input schema, an output schema, and annotations covering the safety profile, the description needs only to clarify the resource's purpose. It does so adequately, leaving no critical gap for an agent to call 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 all four parameters are fully documented in the schema. The description adds no parameter-level meaning, which is the baseline expectation when the schema does the heavy lifting.

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

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

The description states a specific verb and resource ('List RADIUS profiles') and clarifies what RADIUS profiles are with concrete examples (WiFi WPA-Enterprise, switch 802.1X port auth, VPN). It does not explicitly contrast with any sibling tool, so it falls short of the 5 bar for sibling differentiation.

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

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

The description implies when the tool is useful by explaining what RADIUS profiles are referenced by, but it never states when to choose this tool over alternatives or any prerequisites. Usage is left to inference from the domain 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, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value beyond that: it scopes results to what the API key can access and flags that the returned id is the siteId required by other tools, which is genuine cross-tool behavioral context. It does not discuss pagination defaults, but the schema does.

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

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

Two short sentences, zero filler, with the purpose and the return contract front-loaded before the usage directive. Every clause earns its place.

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

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

For a zero-required-param list tool with an output schema, annotations, and a fully documented input schema, the description supplies the one thing structured fields cannot: that this is the entry point that yields the siteId for the rest of the toolset. Nothing needed to call it correctly is missing.

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

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

Schema description coverage is 100% and all three params (limit, filter, offset) are fully documented in the schema, including filter operators and examples. The description adds nothing about parameters, 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+resource ('List all sites') plus the access scope ('the API key has access to') and enumerates the return fields. It is unambiguously distinguishable from the many sibling list_* tools, which target devices, clients, networks, and so on.

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

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

Explicitly says 'Use for: first call in any workflow' and gives the reason — 'almost every other tool needs a siteId'. That is a concrete when-to-use condition with the dependency explained, leaving little to inference.

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

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

Annotations only cover the safety profile (readOnly, non-destructive). The description adds substantive behavior the annotations cannot: version-specific return naming (units[] vs `members` on consoles older than 10.6.106), a documentation gap in 11.0.83 for the per-unit schema, and a filter restriction (device filters rejected on 11.0.83).

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

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

Front-loaded with purpose, then returns, then usage — good ordering with no filler sentences. It is dense with parenthetical asides (concept definition, version caveat, doc gap), which slightly slows scanning but each aside carries real 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?

An output schema exists, yet the description still adds the version-drift caveat that the output schema cannot express. Together with the sibling routing and filter restriction, 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 limit/offset/filter/siteId meaning is already fully documented in the schema. The description adds essentially nothing about parameter syntax or semantics beyond what the schema states (the device-filter rejection note is duplicated in the schema's filter description). 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+resource ('List Switch Stacks') and immediately defines the domain concept (multiple physical switches managed as one logical unit) scoped to a site. It also distinguishes itself from siblings unifi_get_switch_stack and unifi_get_device, so an agent can select it without opening any schema.

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

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

Explicit 'Use for: identifying stacked switches' plus an exclusion — member configs/stats come from unifi_get_device, and per-unit schema requires unifi_get_switch_stack. This names the alternatives and the conditions that select them.

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

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

Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds the type enum values (PORTS/IPV4_ADDRESSES/IPV6_ADDRESSES) and item shapes, which is useful, but much of that is duplicated by the existing output 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?

Front-loaded with purpose, then returns, then the use-case. Three compact clauses with no filler. The 'Returns:' enumeration is somewhat redundant given an output schema is present, slightly costing 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?

For a read-only list tool with a full output schema and complete annotation coverage, the description provides enough to select and call it correctly. Nothing critical is missing, though it could have pointed at the sibling get tool for single-item retrieval.

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 siteId, limit, offset, and filter (including the filter caveat). The description adds no parameter-level detail, so 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+resource (list traffic matching lists) and then defines the resource domain-specifically ('named collections of ports or IPs reused in firewall/ACL rules'). This clearly distinguishes it from the singular sibling unifi_get_traffic_matching_list.

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

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

'Use for: finding the matching-list ID to reference from a firewall policy' gives a concrete selection context tied to a workflow. It lacks an explicit when-not-to-use or a named alternative, but the intent is clear.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds genuinely new context by enumerating the returned fields and clarifying field meaning (activatedAt = when first guest used it, expired flag), aiding interpretation beyond the annotations.

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

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

Front-loads the verb and resource, then the return list, then the filter tip. Slightly long on the return-field enumeration, but each item is information-bearing 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?

Given an output schema exists, the description needn't detail return values, yet it does, so nothing is missing. Combined with full schema coverage and annotations, an agent has everything needed to call it correctly.

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

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