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

Annotations provide readOnlyHint=true and description reinforces this with 'Read-only operation'. It also discloses aggregation behavior and output nature ('AI-friendly summary of what may be wrong'), adding useful context beyond the annotation. No contradictions or hidden side effects.

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

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

The description is well-structured and front-loaded with the core purpose, followed by alternatives and parameter details. The Args section partially duplicates schema documentation, but overall it remains concise and scannable.

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 no output schema, the description compensates by stating the output is a structured report/summary of potential issues. It also documents both optional parameters and gives enough context to invoke the tool correctly. Minor omissions like exact response fields are acceptable given the 'AI-friendly summary' characterization.

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 site and device are already fully described in the input schema. The description repeats this information without adding deeper semantics like format, constraints, or interactions between the parameters, so baseline 3 is appropriate.

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

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

Description states a specific verb ('Analyze'), resource ('a site'), and output ('structured report of potential issues'). It enumerates the aggregated data sources and explicitly distinguishes itself from sibling tools like get_alarms, get_device_health_summary, and get_optimization_recommendations, leaving no ambiguity about what it does.

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

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

Description explicitly names when to use alternatives: get_alarms for raw alarms, get_device_health_summary for device-only status, and get_optimization_recommendations for improvements rather than fault reports. This gives clear routing guidance and 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?

While annotations only mark destructiveHint=true, the description adds that in the current release no controller mutation is performed, mutation_attempted=false, the call records the attempt, and success=false unless confirm=true. This goes well beyond the structured annotation and prevents an agent from expecting a real activation.

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

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

The description is compact and front-loaded with the core purpose and confirmation requirement, then expands on behavior and parameters. Minor redundancy exists between 'Requires confirmation' and the confirm parameter rationale, but nothing is excessive.

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

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

For a mutation tool with no output schema, the description covers the critical behavioral caveats, the prerequisite workflow, and the parameter semantics. It could specify the full response contract, but it already gives the key success/mutation flags and current-release behavior.

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

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

Schema description coverage is 100%, and the description's Args entries simply restate the schema text for plan_token and confirm without adding extra semantics. The schema already carries the parameter meanings, so the description adds no value beyond a baseline.

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

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

The description states a specific verb ('Apply'), resource ('validated QoS preview'), and a clear condition ('when a supported adapter exists'). It also names the prerequisite sibling tool plan_client_qos_policy, which distinguishes it from the planning step.

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

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

It explicitly instructs agents to call plan_client_qos_policy first to obtain a plan_token and requires confirmation before any effect. It does not enumerate all when-not-to-use cases, but the no-op behavior without confirm=true and the current no-adapter caveat provide clear 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?

The description clearly discloses the behavioral effect beyond the idempotentHint annotation: it marks open alarms as archived, changes no device configuration, and affects what get_alarms returns. This gives the agent a precise mental model of the side effects.

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

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

The main explanation is compact and front-loaded, with the action, behavior, and usage guidance in the first sentences. The Args section is redundant with the schema, but it is short and does not meaningfully hurt clarity.

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

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

For a simple tool with two optional parameters and no output schema, the description covers purpose, behavior, side effects, and alternative tools. Nothing critical is missing for an agent to decide when and how to invoke it.

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

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

Schema description coverage is 100%, and the description's Args section merely repeats the schema's field descriptions verbatim. It adds no new semantic meaning beyond what the input 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 names a specific action and resource: 'Acknowledge and archive every active alarm on a site.' It also differentiates itself from get_alarms and analyze_network_issues, so an agent can tell exactly what this tool does and what it is not.

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

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

The description gives explicit when-to-use guidance: 'Use get_alarms first to review what will be cleared' and 'prefer analyze_network_issues when you want findings without clearing alarm state.' This clearly routes the agent to the right tool for adjacent tasks.

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 idempotentHint annotation, the description discloses that this is a mutating operation, that it replaces the client's single local group membership, that a null group clears membership, and that the controller is not mutated. It also reveals the success=false-until-confirm behavior, adding significant context that annotations do not provide.

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

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

The description is well-structured with an upfront summary, behavioral notes, and an Args block. It is somewhat repetitive with the schema descriptions, but every included sentence contributes functional guidance or clarifies important caveats like confirm behavior and non-mutation of the controller.

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 mutating tool with no output schema, the description covers the required confirmation flag, exact membership semantics, null-group unassignment, identity resolution, site/device targeting, and relevant sibling tools. The success=false caveat partially addresses return behavior, making the tool safe to invoke without further assumptions.

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

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

Schema description coverage is 100%, so the baseline is 3 even though the description mostly mirrors the parameter descriptions. It does add context like 'resolve to a known client' for identity and reinforces the no-op behavior of confirm, but it does not materially extend beyond the schema.

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

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

The description opens with a specific verb and resource: 'Assign or unassign one local client group.' It clearly distinguishes itself from related siblings by pointing to set_client_tags for tags and list_clients_by_organization for finding clients in a group. Scope and semantic intent are unambiguous.

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

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

The description explicitly states when to use the tool, that confirm=true is required for the operation to take effect, and that without it the call is a no-op. It also provides alternative tools for tags and client-group listing, giving clear exclusions and alternatives.

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

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

The description discloses that this is a mutating operation, applies immediately, and persists in the controller's firewall/blocklist. This goes beyond the idempotentHint annotation by explaining the real-world effect and durability of the action, though it does not cover failure modes or permissions.

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

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

The description is compact and well-structured: a one-sentence purpose, a short behavioral note, explicit alternative guidance, and a clean Args list. Every sentence provides useful information, and the most important facts are front-loaded.

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

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

For a state-changing tool with no output schema and minimal annotations, the description covers the core behavioral context: immediate effect, persistence, and reversal path. It could additionally clarify success/failure response behavior, but the essential information an agent needs to select and invoke the tool correctly is present.

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

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

Schema description coverage is 100%, and the Args section in the description essentially repeats the schema descriptions without adding new semantic detail. Because the schema already fully documents mac, site, and device, the description adds no meaningful parameter meaning beyond what is already structured.

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 action, target, and mechanism: 'Block a client from accessing the network by MAC address.' It clearly identifies the resource and differentiates the tool from related siblings by naming unblock_client and kick_client as alternatives.

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

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

The description explicitly explains when to use this tool versus alternatives: use unblock_client to restore access, and kick_client to drop a connection without a persistent block. This gives an agent clear decision criteria without needing to inspect other tool definitions.

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

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

The description openly labels the operation as 'Mutating', explains that it persists observations and refreshes cached metrics, and discloses return values. This adds meaningful behavioral context beyond the idempotentHint annotation, which alone would not reveal the persistence side effect.

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

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

The description is compact and well-structured: a one-line summary, a clear side-effect warning, and a usage directive. Every sentence earns its place, and the most important 'Mutating operation' label is front-loaded.

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

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

For a zero-parameter action with no output schema, the description fully covers what the tool does, its side effects, what it returns, and when to use it. Nothing essential is missing for an agent to 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?

There are zero parameters and schema coverage is 100%, so there is no parameter burden for the description to carry. The description adds relevant conceptual context like 'bounded batch', but no parameter-specific semantics are needed.

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

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

The description uses a specific verb ('Capture') with a clear resource ('aggregate UniFi health observations') and a temporal qualifier ('immediately'). It clearly distinguishes this tool from passive query tools like query_observation_trends.

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

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

Explicitly states when to use this tool: 'Use before query_observation_trends to ensure recent data, or rely on scheduled capture otherwise.' This provides both a selection condition and a named alternative, making it easy for an agent to route correctly.

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

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

It discloses the mutating nature, persistence behavior, local-only scope, no-op behavior without confirm=true, and the success=false return caveat. This goes well beyond the single destructiveHint annotation and gives the agent accurate expectations for side effects.

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

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

The description is well structured with a clear opening, a behavioral note, and an args list. There is minor redundancy around confirm=true being required and the no-op return behavior, but overall every section contributes useful 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 mutation tool with only a destructiveHint annotation and no output schema, this description is thorough: it covers side effects, confirmation semantics, scope, return behavior, and routes to sibling tools. An agent has enough context to invoke it correctly and understand the outcome.

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

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

Schema description coverage is 100%, and the description largely mirrors the schema's parameter documentation. It adds some context (e.g., 'local_only' and no-op behavior), but does not substantially expand on what the schema already provides.

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

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

The description states a specific verb and resource: 'Create a controller-independent local client group.' It further clarifies what the operation does not do ('does not create anything on the UniFi controller'), which differentiates it from siblings like assign_client_group, list_client_groups, and delete_client_group.

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

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

The description clearly explains the confirmation requirement and points to relevant alternatives: 'Use assign_client_group to add members, or list_client_groups to see existing groups.' It does not explicitly enumerate when not to use this tool, but the guidance is strong enough for an agent to choose it appropriately.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It explicitly states that the operation is mutating, applied immediately, persisted on the UniFi console, that lower index values evaluate earlier, and that a controller-generated '(Return)' companion rule is typically added. These are meaningful side-effect disclosures beyond the schema.

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

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

The description is front-loaded with purpose and mutation status, then covers side effects, prerequisites, and an Args list. Every sentence contributes necessary information for safe invocation, and the structure makes the 11-parameter tool understandable without bloat.

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

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

For a tool with 11 parameters, no annotations, and no output schema, the description is complete: it covers all required inputs, defaults, protocol values, ordering semantics, prerequisite lookups, device/site targeting, and side effects. An agent has enough context to invoke it correctly and anticipate the outcome.

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

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

Schema description coverage is 100%, so the baseline is 3. The description repeats most parameter semantics already present in the schema, such as defaults, protocol choices, and the source of zone IDs. It adds useful grouping and emphasis for required parameters, but does not materially expand beyond the structured schema.

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

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

The description opens with a specific verb and resource: 'Create a zone-based firewall policy (UniFi Network 9+)'. It further clarifies the policy model (ALLOW/BLOCK/REJECT across a src_zone_id to dst_zone_id pair), which clearly distinguishes it from sibling tools like create_firewall_rule or set_firewall_policy_enabled.

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

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

The description gives clear context and explicit prerequisites: 'Requires zone ids from get_firewall_policies; review there first.' It also warns that the operation is mutating and applied immediately. It does not explicitly state when-not-to-use or name alternatives, but the zone-based framing and prerequisite guidance are strong.

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 provide destructiveHint=true, and the description adds valuable context on top: it is a 'Mutating operation: applied immediately and persisted on the controller.' This reveals immediacy and persistence behaviors not present in the annotation. It could also mention rollback or failure implications, but the existing disclosure is strong for a legacy API mutation.

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

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

The opening sentences are useful and front-loaded with purpose and usage guidance. However, the Args section duplicates the input schema content one-for-one, which adds length without earning its place. The Returns line adds value since there is no output schema, but the overall structure could be tighter by omitting the redundant parameter list.

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

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

For a complex 11-parameter mutating tool with destructiveHint and no output schema, the description covers the essential context: legacy scope, mutation semantics, persistence, the preferred alternative for newer APIs, and a prerequisite to review existing rules. It mentions a return value, though vaguely. Missing details like error behavior or uniqueness handling for rule names keep it just short of a 5.

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 every parameter. The description repeats the Args list verbatim without adding new semantic meaning. It does not explain relationships between parameters or edge cases, but given full schema coverage, the baseline of 3 is appropriate; the description simply does not add extra value.

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

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

The description clearly states the verb and resource: 'Create a legacy firewall rule', and specifies the scope (UniFi Network <9 or traditional API). It explicitly distinguishes itself from the sibling create_firewall_policy by saying zone-based policies should use that tool. This is a specific, well-scoped purpose statement.

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

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

The description gives explicit usage guidance: use create_firewall_policy for Network 9+ zone-based policies, and review existing rules with get_firewall_rules first. This tells the agent both when to use this tool and when to prefer an alternative, which is exactly what usage guidance should do.

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 destructiveHint=true annotation, the description discloses that without confirm=true the call 'is a no-op,' returns success=false, and requires the job to be allowlisted — exactly the kind of behavioral context annotations do not carry. It also states the persistence semantics with 'Mutating operation: persists a new interval schedule.' This fully aligns with destructiveHint and adds substantial value above it.

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 definition front-loads purpose in the first sentence and keeps the behavioral prose tightly scoped with a clear paragraph break before the Args list. However, the Args block duplicates schema descriptions for all five parameters at 100% coverage, and 'Requires confirm=true' is restated in the next paragraph — minor but real 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 mutating tool with no output schema, the description covers the confirmation gate, no-op behavior, allowlist constraint, and post-create lifecycle routing, which are the critical decision factors. It only partially describes the response ('Returns success=false unless confirm=true') and doesn't address duplicate names or error cases, but since the schema documents all parameters, the remaining gaps are minor.

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

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

Schema description coverage is 100%, with all five parameters already documented, so the baseline is 3. The Args section restates the schema text nearly verbatim ('name: Unique schedule identifier', 'interval_seconds: Recurrence period between runs, in seconds') without adding new semantic meaning. The one behavioral nuance, the confirm no-op, already exists in the schema's own confirm description, so the description adds no information beyond the structured schema.

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

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

The opening line 'Create an allowlisted recurring job' names a specific verb and resource, and the second paragraph clarifies it 'persists a new interval schedule that runs job_name... every interval_seconds,' distinctly a creation operation. It explicitly differentiates itself from lifecycle siblings by naming set_schedule_enabled and delete_schedule as separate operations, so an agent can tell them apart without opening their schemas.

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

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

The description gives direct routing: 'Use set_schedule_enabled to pause it, or delete_schedule to remove it,' which tells the agent what to use instead once a schedule exists. The allowlist and confirm=true requirements set clear preconditions for invoking this tool. It stops short of contrasting with the run_schedule_now sibling or one-off execution, so the 'when not to use' guidance is partial.

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 destructiveHint annotation, the description discloses that the change is applied immediately and persisted, that confirm=true is required, and that routing/VLAN/DHCP changes can disrupt connectivity. This is meaningful additional behavioral context.

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

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

Well front-loaded with purpose and mutation warning, and the flow from high-level guidance to Args is logical. The Args list is somewhat redundant with the 100%-covered schema, so it is not maximally concise, but it is organized and readable.

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

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

For an 11-parameter destructive tool with no output schema, the description covers defaults, optionality, enabling conditions, safety gate, and related inspect/delete operations. 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%, so the baseline applies. The description's Args section largely repeats the schema descriptions; the only extra value is grouping interdependent params (subnet/VLAN/DHCP) in the prose, which is marginal.

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?

Opens with a specific verb and resource — 'Create a new network/VLAN segment on the gateway' — and adds the default purpose. This clearly distinguishes the operation from update_network/delete_network 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?

States lifecycle alternatives explicitly: 'Inspect with get_networks; reverse with delete_network.' It also gives concrete creation conditions — CIDR subnet, optional VLAN, DHCP requires both dhcp_start and dhcp_stop, and confirm=true is mandatory for this disruptive mutation.

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 provide destructiveHint: true, but the description adds operational detail: 'Mutating operation: applied immediately and persisted on the UniFi console.' It also surfaces the workflow of reviewing and deleting rules, which is useful context beyond the annotation.

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

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

The description is well-structured with a clear purpose statement, a prominent mutating-operation warning, and targeted sibling guidance. The Args list is somewhat redundant with the schema, but the overall length is justified and each section 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?

For an 8-parameter mutating tool with no output schema, the description covers the operation's effect, persistence, related tools, and an alternative. It gives an agent everything needed to decide when to call it and what the result will be.

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 every parameter. The description's Args section largely restates the schema rather than adding new meaning, though it usefully distinguishes fwd_port vs dst_port as external vs internal ports.

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: 'Create a port-forwarding rule that opens an external WAN port and maps it to an internal host/port.' It clearly distinguishes this tool from related siblings by name-checking create_firewall_policy, get_port_forwards, and delete_port_forward.

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

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

The description explicitly instructs the agent to review existing rules with get_port_forwards first, to remove rules with delete_port_forward, and to prefer create_firewall_policy for zone-based/stateful filtering. This gives clear decision criteria for selecting this tool over alternatives.

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

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

Beyond the destructiveHint annotation, the description discloses that the operation persists a destination, is a mutating operation, and is a no-op returning success=false unless confirm=true. This adds meaningful safety and side-effect context the annotation alone does not provide.

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

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

The description is front-loaded with the key requirement (confirm=true) and is well-structured with a short explanation, lifecycle guidance, and an Args list. Some redundancy exists between the prose and the schema-covered Args section, but the description remains focused and readable.

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 mutating creation tool with no output schema, the description covers the essential invocation requirements: confirm=true, required name/url, optional secret/categories, and post-creation alternatives. It gives enough for an agent to call it correctly, though the full success response shape is not specified.

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

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

Schema description coverage is 100%, so the schema fully documents all five parameters. The description largely repeats the schema's parameter meanings and adds no new semantic detail about formats, constraints, or interactions beyond what is already in the schema.

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

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

The description states a specific action and resource: 'Create a filtered outbound webhook.' It clearly distinguishes this creation tool from lifecycle siblings by explicitly naming set_webhook_destination_enabled and delete_webhook_destination for later operations.

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

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

It gives clear context for use: creating a webhook destination requires confirm=true, and it points to sibling tools for pausing and deleting. It does not explicitly contrast with test_webhook_destination or list_webhook_destinations, but the creation scenario is unambiguous.

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?

While destructiveHint already marks mutation, the description adds concrete behavioral context: immediate application, persistence on the UniFi console, WPA2/WPA3 transition behavior, legacy client support, and guest isolation. This meaningfully expands on the annotation.

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 summary sentence is front-loaded, followed by a clear mutation warning and an organized Args list. Despite covering eight parameters, every sentence carries useful information 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?

For an 8-parameter create operation with only destructiveHint as annotation, the description covers required inputs, all defaults, security behavior, VLAN/guest options, site/device selection, and verification via get_wlans. Nothing essential for a correct call 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. The description improves on the schema by explaining why wpa3_transition retains WPA2 for legacy clients and by relating network_conf_id and is_guest to networking intent, though much of the Args section mirrors 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?

Opens with a specific verb and resource: 'Create a wireless network (SSID)' and immediately names the default security mode. This clearly distinguishes it from siblings like get_wlans, update_wlan, and delete_wlan.

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

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

The description gives clear context: it is a create operation applied immediately and persisted, and it explicitly routes to get_wlans for inspection. It does not explicitly state when not to use it or point to update_wlan/delete_wlan for existing SSIDs, so it stops short of full exclusion 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?

Beyond the destructiveHint annotation, the description discloses that members are detached, the UniFi controller is untouched, success=false is returned without confirmation, and the operation is reversible via create_client_group. This gives an agent a clear, accurate behavioral model.

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

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

The description is well-structured with a front-loaded purpose and a clear Args list. There is minor redundancy around the confirm requirement, appearing both in the opening paragraph and the parameter description, but the overall length is justified for a destructive operation.

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 four-parameter destructive tool with destructiveHint already set, the description covers purpose, required confirmation, side effects, recovery path, and the success/failure return signal. Nothing essential for an agent to safely invoke the tool is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The description's Args section largely restates the schema, and while it emphasizes the confirm no-op behavior, it does not add substantive new parameter-level meaning beyond the schema.

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

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

The description opens with a specific verb and resource: 'Delete a local group and its memberships.' It clearly distinguishes the operation from siblings like create_client_group and assign_client_group, and further scopes it to local-only groups that do not touch the UniFi controller.

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

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

The description explicitly states the confirm=true requirement and the no-op behavior without it, which is essential usage guidance. It also points to create_client_group as the recovery path, though it does not explicitly enumerate when to prefer an alternative over this tool.

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

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

Annotations only declare destructiveHint=true. The description adds meaningful behavioral context: the operation is mutating, removal is immediate and persisted, confirm=true is mandatory because traffic flow changes, and predefined controller policies are refused. These details go well beyond the annotation and give the agent an accurate safety and side-effect 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?

The description is front-loaded with the core purpose and clearly organized into behavioral notes and an Args block. It is efficient and readable, but the Args section largely duplicates the input schema descriptions, adding minor redundancy rather than earning each sentence entirely.

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

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

For a destructive delete tool with no output schema, the description covers all critical context: what is deleted, persistence, safety gate, refused inputs, how to source the ID, and site/device targeting. Nothing essential for safe and correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters fully. The description's Args section repeats the same text rather than adding new semantic meaning. It does not explain formats, valid values, or additional constraints beyond what the schema already provides.

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

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

The description opens with 'Delete a zone-based firewall policy', giving a specific verb and resource that clearly identifies the tool's function. It also distinguishes it from related sibling tools like delete_firewall_rule by specifying 'zone-based firewall policy'. This is unambiguous and immediately actionable.

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

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

The description explicitly states the required confirm=true gate, explains why it is required ('removing a policy changes traffic flow'), and notes that predefined controller policies are refused. It also directs the agent to obtain the policy_id from get_firewall_policies, providing clear guidance on the correct source and the condition under which deletion is disallowed.

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 destructiveHint=true annotation, the description explicitly states 'Mutating operation: permanently removes the rule from the controller,' disclosing that the operation is irreversible. It also surfaces the confirm=True gating requirement, which the annotations do not capture. This adds real behavioral context without contradicting the destructiveHint.

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

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

The description is compact and front-loaded: a one-line purpose, a one-line mutation warning, then organized Args and Returns sections with clear defaults. The Args section partially duplicates schema text, but the overall length is still appropriate and scannable.

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

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

For a destructive 4-parameter tool with no output schema, the description covers the critical usage facts: confirm=True requirement, permanence, ID provenance, site default, and optional device targeting. The notable gap is the Returns section — 'Deletion status' is vague, and with no output schema the agent has no way to know the success/error shape to expect.

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

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

Schema description coverage is 100%, so the schema fully documents all four parameters, warranting the baseline of 3. The description's Args block largely mirrors the schema verbatim (site default, confirm gate, device nullability); its only added value is provenance for rule_id (from get_firewall_rules).

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: 'Delete a legacy firewall rule.' The 'legacy' qualifier distinguishes it from sibling tools like delete_firewall_policy and creates/updates firewall rules/policies, so an agent can tell them apart at a glance.

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 its scope with the word 'legacy' and gives the source of the rule ID ('from get_firewall_rules'), but it never explicitly names alternatives such as delete_firewall_policy for the newer firewall-policy model, nor states when not to use the tool. Usage routing is left mostly 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?

Beyond destructiveHint=true, the description adds that deletion is 'removed immediately and persisted on the UniFi console' and explains the consequences of dropping dependent clients/routes. It also reveals the confirm gate as a safety mechanism, which is more behavioral detail than the annotation alone provides.

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

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

The description is compact and front-loaded: one-sentence purpose, a terse safety warning, and a clean Args list. Every sentence adds operational value, with no filler or repeated boilerplate.

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 four-parameter, one-required-parameter destructive tool with no output schema, the description covers the target, site/device selection, confirm requirement, risk, and prerequisite listing. Nothing an agent needs to safely invoke it is missing.

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

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

Schema description coverage is 100%, so the input schema already documents all four parameters. The Args section in the description mirrors the schema instead of adding new parameter-level semantics; the extra value is behavioral context, not 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?

The description opens with a specific verb and resource: 'Delete a network/VLAN by name or ID.' This immediately identifies the mutation and target, and the deletion semantics clearly set it apart from sibling network tools like get_networks, create_network, and update_network.

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

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

It explicitly requires confirm=true, warns about dropping clients and routes, and instructs the agent to 'List networks with get_networks first to confirm the target.' This gives a concrete prerequisite and safe workflow, so the agent knows exactly when and how to execute the deletion safely.

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

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

Annotations only declare destructiveHint=true, so the description carries the burden of explaining behavior. It adds valuable context: removal is immediate and persisted on the console, confirm=true is a mandatory safety gate, and deleting closes external access. This goes well beyond the annotation and gives the agent a clear mental model of consequences.

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 intro is front-loaded and informative, covering mutation behavior, consequences, and the confirm requirement in three concise sentences. However, the entire Args section duplicates the schema's parameter descriptions without adding new information, so not every part of the description earns its place.

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

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

The description covers all essential call decisions: required rule_id, confirm safety gate, site/device defaults, and the source of the rule id. With no output schema, it does not describe return values, but for a guarded delete operation the provided behavioral and parameter context is sufficient for an agent to select and invoke the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The Args section repeats the schema descriptions nearly verbatim and adds no new meaning beyond what is already in the input schema. The only framing benefit is connecting rule_id to get_port_forwards, which the schema already mentions.

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 ('Delete a port forwarding rule') and clarifies that the rule is targeted by id from get_port_forwards. This clearly identifies the operation, but it never explicitly names sibling tools like create_port_forward or get_port_forwards as alternatives, so it stops short of directly differentiating among them.

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

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

The description gives clear invocation context: it is a mutating delete that requires confirm=true because it closes external access, and the target id comes from get_port_forwards. It does not include explicit when-not-to-use guidance or name alternatives, but for a delete tool the usage context is strong enough to guide 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 flag destructiveHint=true, but the description adds crucial behavior: the confirm parameter makes the call a no-op when false, and it returns success=false without confirmation. This is valuable context beyond the annotation.

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

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

The description is well-organized with a clear lead sentence, behavioral note, alternatives, and parameter list. Minor redundancy exists ('Requires confirm=true' and 'Returns success=false unless confirm=true' overlap slightly), but overall it is efficient and scannable.

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 destructive tool, the description covers the core behavior, confirmation requirement, return signal, and alternatives. It does not specify what happens if the schedule is running, but the 'non-running' constraint partly addresses that. This is a minor gap rather than a major 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?

Schema description coverage is 100%, so the schema already documents both parameters clearly. The description repeats those meanings without adding new semantic detail, so a baseline score of 3 is appropriate.

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

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

The description opens with a specific verb and resource ('Delete a non-running schedule') and immediately distinguishes itself from sibling tools by pointing to create_interval_schedule and set_schedule_enabled. An agent can determine exactly what this tool does and what it is not.

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 states the key usage condition (non-running schedule), the required confirm flag, and explicitly names alternatives for adding or pausing schedules. This gives clear when-to-use and when-not-to-use guidance.

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

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

The description discloses destructive behavior beyond the destructiveHint annotation: it removes queued deliveries from the store, requires confirm=true, returns success=false without confirmation, and acts as a no-op without confirm. This gives the agent a precise safety model.

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

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

The description is well-structured with a clear summary, behavioral note, and argument list. There is minor redundancy around the confirm requirement appearing three times, but it remains compact and readable.

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 destructive operation, the description covers the action, consequences, confirmation safeguard, and the related create operation. With annotations and a complete input schema, no critical information is missing for an agent to call it safely.

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

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

Schema coverage is 100%, so the schema already documents both parameters fully. The description repeats the parameter meanings without adding significant new detail beyond what the schema provides.

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

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

The first sentence states a specific verb ('Delete') and resource ('webhook destination and queued deliveries'), making the operation unmistakable. It also contrasts with create_webhook_destination, which helps distinguish it from the most closely related sibling.

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

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

The description clearly establishes when this tool is appropriate: to permanently delete a webhook destination and its queued deliveries. It names create_webhook_destination as the alternative for adding a destination, though it does not discuss temporary disabling via set_webhook_destination_enabled as a non-destructive 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?

Beyond the destructiveHint annotation, the description discloses that deletion is immediate and persisted, and that deleting an SSID disconnects its clients. It also explains why confirm=true is mandatory, giving the agent important behavioral context before invocation.

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 tightly organized: a one-line summary, behavior/risk notes, prerequisite guidance, and a clear Args block. Every sentence contributes useful information with no redundancy.

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

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

For a destructive delete operation, the description covers the target, the safety flag, the site/device scope, the immediate effect, and the recommended prerereview. No output schema exists, but nothing essential to calling 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%, so the schema already documents all parameters. The description adds value by explaining why confirm is required, emphasizing that wlan accepts an ID or SSID name, and advising review of get_wlans first, which goes slightly beyond the schema text.

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

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

The first sentence states a specific verb ('Delete') and resource ('a wireless network (SSID)'), which clearly distinguishes it from siblings like create_wlan, update_wlan, and get_wlans. The description's scope is unambiguous.

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

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

The description provides clear operational guidance: it instructs the agent to review get_wlans first, resolve the target by ID or name, and requires confirm=true. It does not explicitly contrast with create_wlan or update_wlan, but the prerequisite and safety-gate context make the appropriate use 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 only mark destructiveHint; the description discloses the file-writing mutation, path confinement validation, credential requirement, no-op-until-confirm semantics, and the returned path/size. This goes well beyond the annotation and contradicts nothing.

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 opening sentence is front-loaded and the prose is information-dense. The Args block duplicates schema content, which adds length, but the description remains structured and every distinct behavioral point 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 only destructiveHint true and no output schema, the description carries the burden of explaining side effects, safety confirmation, path constraints, credentials, and result shape. It covers all of these, leaving no critical gap for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3; the description's Args section largely restates schema text. It adds a bit of prose context about output_path being confined and confirm gating the write, but no new parameter-level details 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 action: exporting a UniFi Protect recording clip as an MP4 file written to disk. It distinguishes itself from still-image capture by naming get_camera_snapshot as the alternative, which separates it from sibling tools.

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

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

Explicitly tells the agent to use get_camera_snapshot when a single still image is needed instead of a time-ranged clip. It also states the credential prerequisite and the confirm requirement, giving clear context for when the operation will actually write.

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 destructiveHint annotation, the description explicitly declares 'Mutating operation: writes a local report file immediately, persisted in the export directory,' and explains rejection behavior when confirm is false. This informs the agent of side effects and side-effect gating. No contradiction with annotations.

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

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

The description is compact and front-loaded: it states action, formats, safety requirement, and alternative in the first paragraph. Some redundancy exists between the prose and the repeated Args section, but every sentence contributes necessary operational context, and the structure is scannable.

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?

Combined with full schema coverage and the explicit safety/alternative statements, nothing an agent needs to invoke the tool correctly is missing. The description addresses the mutating side effect, required confirmation, file extension rules, and the preferred alternative — all critical to correct selection and invocation.

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

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

The input schema already documents all three parameters with 100% coverage, and the description's Arg section essentially repeats those descriptions. No additional semantics about types, defaults, or constraints beyond what the schema provides. 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?

Description opens with a concrete verb and object: 'Export an HTML or CSV report rendered from the portable snapshot model.' It specifies output formats and clearly differentiates from export_portable_snapshot by mentioning the raw machine-readable alternative. Even among many sibling tools, its purpose is unmistakable.

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

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

Explicitly directs the agent to prefer export_portable_snapshot when a raw machine-readable model is needed, which is a clear when-not-to-use. It also specifies the required confirm=true and format/extension constraints. This satisfies explicit guidance for 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?

The annotations only carry destructiveHint=true; the description goes well beyond this by disclosing that the call writes a file immediately to the confined export directory, is rejected without writing unless confirm=true, and returns a filename, size, schema version, and SHA-256 checksum. It also adds useful traits the annotations cannot express: deterministic and secret-free output.

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 core purpose is front-loaded in a single crisp sentence, followed by a compact paragraph that covers behavior, safety gate, return contract, and sibling routing. Every sentence earns its place, with no filler or redundant repetition of schema content.

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 no output schema present, the description correctly takes on the return contract itself, listing filename, size, schema version, and SHA-256 checksum. For a 2-parameter tool with no nested objects, the description covers invocation, safety confirmation, destination, and verification path — 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%, so both parameters are already fully documented in the input schema. The description largely restates the confirm safety gate ('rejected without writing unless confirm=true') that the schema already explains, adding no new constraints or syntax details beyond the baseline.

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

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

The first sentence names a specific verb (export), a specific resource (deterministic secret-free JSON snapshot), and a scope (local confined file). It also explicitly differentiates from the sibling export_network_report by mentioning that it produces raw JSON rather than human-readable HTML/CSV, so an agent can distinguish it from siblings 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?

The description explicitly names the alternative and the selection condition: 'Use export_network_report for human-readable HTML/CSV instead of the raw JSON model.' It also implies the follow-up workflow by pointing to verify_snapshot for later checksum verification, giving the agent clear routing guidance.

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

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

Annotations already declare destructiveHint=true, and the description adds concrete consequences: deletes stored client identity and history, and the client can reappear on reconnect. This goes beyond the annotation by explaining what is destroyed and the reconnection effect.

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 purpose, then a compact destructive warning and sibling routing, with only a short Args block. The Args block duplicates the schema, which prevents a 5, but nothing is wordy or off-topic.

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

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

For a destructive three-parameter tool with 100% schema coverage and a destructive annotation, the description covers what is deleted, whether the client returns, how to choose alternatives, and all parameter roles. No output schema is needed for an action like this.

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 mac, site, and device. The description's Args block restates those descriptions without adding new semantics or examples, keeping this at the baseline.

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

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

Opens with a specific verb-resource statement: 'Remove a client from the controller's known-clients list.' The description clearly delimits the operation against nearby siblings by naming kick_client and block_client as the alternatives for related but different actions.

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

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

Explicitly labels the operation destructive and states when to prefer alternatives: kick_client for dropping a session without deletion, block_client for persistent denial. An agent gets direct decision rules rather than having to infer 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 provide readOnlyHint=true, and the description reinforces it by saying 'Read-only operation.' Beyond that, it adds useful context: the tool lists 'unacknowledged/active alarms with severity and message' and scopes the query to a site and optional device. It doesn't describe pagination or rate limits, but for a simple read-only tool the added context is meaningfully helpful.

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

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

The description is well-structured and front-loaded: core purpose first, then read-only clarification, then routing to alternatives, then args. It is slightly redundant because 'Read-only operation' duplicates the readOnlyHint annotation and the Args section duplicates the schema, but the overall length is reasonable and every substantive sentence earns its place.

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

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

There is no output schema, so the description carries the burden of explaining return content; it does so by saying the tool lists 'unacknowledged/active alarms with severity and message.' It also covers when to use it and what to do afterward. Minor gaps remain: it doesn't specify the full alarm object structure, ordering, or empty-result behavior, but these are acceptable for a simple, low-complexity read-only 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%, and the schema already fully describes both 'site' and 'device' parameters. The description's Args section simply repeats the schema text verbatim ('Site to query. Defaults to "default"' and 'Optional console/device name...'), adding no new meaning. Baseline 3 is appropriate because 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 opens with 'Return the currently active alarms (faults and warnings) for a site,' which names a specific verb, resource, and scope. It distinguishes itself from siblings by explicitly contrasting with get_recent_events for non-alarm activity. This leaves no ambiguity about what the tool does.

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

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

The description states when to use the tool ('so you can see what needs attention') and explicitly names alternatives with conditions: use get_recent_events for a broad event feed, archive_all_alarms once handled, or analyze_network_issues for consolidated interpretation. This is model usage 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, and the description reinforces this with 'Read-only operation.' It adds behavioral detail beyond the annotation by stating the tool walks each site and returns a compact health snapshot per site including status, score, and key counts, which is useful context not present in the schema or annotations.

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

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

The description is well-structured and front-loaded: a one-sentence summary, a compact comparison paragraph that routes to alternatives, and a minimal Args section. Every sentence contributes useful information 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?

With one optional parameter, read-only annotations, and no output schema, the description covers the key gaps an agent needs: return shape, scope, relationship to sibling tools, and usage guidance. Nothing essential is missing for correct selection and invocation.

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

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

Schema description coverage is 100%; the single optional 'device' parameter is already documented in the schema as 'Optional console/device name to target a specific UniFi console; omit to use the default.' The description repeats this guidance but adds no new semantic meaning beyond the schema, so a 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 opens with a specific verb and resource: 'Return a health overview for every site managed by one UniFi console.' It clearly distinguishes itself from siblings by naming get_global_health and get_site_health and explaining the scope difference: all sites within one console versus one site or cross-console aggregation.

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

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

The description provides explicit when-to-use guidance with alternatives: use get_global_health for cross-console aggregation, prefer get_site_health for full per-subsystem detail of a single named site. This directly tells the agent how to route among the most similar sibling tools.

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

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

Annotations already provide readOnlyHint=true, and the description reinforces this with 'Read-only operation.' It adds valuable behavioral detail beyond the annotation by enumerating the returned fields and explaining the ID-then-name resolution order. It stops short of describing failure modes or output structure, but the added context is meaningful.

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

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

The description is well-organized: a crisp function statement, a concise read-only behavior summary, clear usage routing, and a compact Args block. Every sentence serves a purpose and nothing is redundant or 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 read-only lookup with two parameters and no output schema, the description covers the purpose, prerequisite, alternatives, parameter resolution behavior, and a summary of returned data. No critical information needed to call the 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 coverage is 100%, so the baseline is 3. The description adds one genuinely useful semantic detail: 'camera is resolved by ID first and then by name.' The Args section mostly mirrors the schema, but this resolution behavior gives extra meaning to camera_id beyond the schema text.

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 opening sentence, 'Get the full configuration and runtime record for one Protect camera,' states a specific verb, resource, and singular scope. It also names sibling tools (get_camera_snapshot, get_camera_health_summary) to distinguish this from related operations.

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

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

The description explicitly says 'Use list_cameras first to find the camera_id' and gives concrete alternatives with their conditions: get_camera_snapshot for an image and get_camera_health_summary for connectivity-only. This is clear when-to-use guidance with no inference required.

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

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

Goes well beyond the readOnlyHint annotation by describing the output shape: connected/disconnected partitioning, an overall 'healthy' or 'degraded' status, critical issues listing disconnected cameras, and remediation recommendations. This gives the agent a clear model of what the operation returns and how it behaves.

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

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

The description is well-organized: a clear first sentence defines the core purpose, the next sentences add behavioral detail and routing guidance, and the Args section handles the parameter. Every sentence earns its place with no redundancy.

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

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

For a read-only summary tool with one optional parameter and no output schema, the description covers the key return elements and selection behavior sufficiently. An agent has enough context to call the tool correctly and interpret its results.

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

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

The only parameter, device, is already fully described in the input schema with 100% coverage. The description repeats the same device guidance without adding new meaning, so the baseline of 3 is appropriate.

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

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

States a specific verb ('summarize') and resource ('connectivity and health of all cameras on one Protect console'), and explicitly distinguishes itself from list_cameras and get_camera_details. An agent can immediately understand the tool's scope and how it differs from nearby 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?

Explicitly says to use this tool for a fleet-wide connectivity check and names the alternatives for per-camera detail or a single camera's complete record. This gives clear when-to-use versus when-not-to-use guidance.

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

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

The description goes well beyond the readOnlyHint annotation by explaining the live-frame request, the base64 JPEG plus camera name/id return value, resize behavior, and the success=false result for non-CONNECTED cameras. This gives the agent a strong model of what will happen when invoked.

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 main behavioral description is front-loaded and concise, with useful failure-mode and resize details. The Args block duplicates the schema descriptions, which adds mild redundancy, but the overall structure is readable and not bloated.

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 tool with no output schema, the description is remarkably complete: it specifies the return format, behavior with optional width/height, the offline-camera failure case, and the recommended pre-check via get_camera_details. Nothing essential is missing.

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

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

Schema description coverage is 100%, so the schema already documents all four parameters. The Args section repeats the schema descriptions essentially verbatim, adding no new semantic information beyond what is already in the input schema.

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

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

The description clearly states the tool captures a still image from a Protect camera as a base64 JPEG, which is a specific verb and resource. It does not explicitly differentiate from related sibling tools like export_portable_snapshot or get_snapshot_capabilities, though the first sentence makes the core purpose unambiguous.

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

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

The description provides clear context, including the behavior for offline cameras and a direct recommendation to use get_camera_details to confirm the camera is online before calling. However, it does not explicitly state when to prefer this tool over related alternatives such as export_camera_clip or export_portable_snapshot.

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

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

The annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only operation'. It adds valuable behavioral context by enumerating what the response covers: identity, connection state, IP, signal/AP association, and history. No hidden mutation or side effects are implied.

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

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

The description is well-structured and front-loaded: purpose, then read-only/return content, then sibling differentiation, then args. The Args block is somewhat redundant with the schema, but the overall length is appropriate and every section is clearly organized.

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

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

The tool is a simple read operation, annotations cover safety, and the description lists the categories of returned data even without an output schema. It is complete enough for an agent to understand what it will get and when to use it, though exact response fields are not enumerated.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The Args section in the description mostly repeats the schema fields and defaults, adding little new meaning beyond restating that 'device' is optional and defaults apply.

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'), a specific resource ('full device record for one client'), and the lookup key ('by MAC address'). It also explicitly differentiates itself from list_clients/list_all_clients by explaining it returns deeper detail than summarized rows.

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

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

The description explicitly names the alternative tools (list_clients/list_all_clients) and gives the distinguishing condition: use this when you need depth beyond summarized rows. This gives an agent clear routing guidance for choosing this tool over its closest siblings.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only operation.' It adds useful context about what the report summarizes: signal-strength distribution, roaming stats, failed connections, and problematic clients. This goes beyond the annotation and helps set expectations about the tool's 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 description is well-structured and front-loaded with purpose, then usage alternatives, then parameters. It is appropriately concise, though the Args section is redundant with the input schema. Every non-arg sentence earns its place.

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

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

For a read-only report tool with two optional parameters and no required inputs, the description is complete. It explains what the report contains, how to choose among related tools, and what the parameter defaults are. No output schema exists, but the description gives enough information about the report's content to set expectations.

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

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

Schema description coverage is 100%, and the Args section in the description essentially duplicates the schema descriptions without adding new meaning. The baseline of 3 applies because the schema handles parameter documentation fully; the description adds no extra semantic value for parameters.

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

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

The description opens with a specific verb and resource: 'Generate a client experience report with connection-quality metrics for a site.' It clearly differentiates from sibling tools by naming troubleshoot_client and get_device_health_summary, so an agent can distinguish it from other reporting and client-related 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?

Explicit guidance is given for when to use which tool: troubleshoot_client for a deep dive on one specific client, get_device_health_summary for infrastructure view, and this tool for client-side summary metrics. This provides clear selection criteria beyond simple names.

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

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

The annotation readOnlyHint=true is reinforced by the description's 'Read-only operation' and 'does not mutate the controller.' It adds useful detail about resolving by identity, local_only data, and persistence, all of which exceed what the annotation alone provides.

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

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

The description is front-loaded with purpose, followed by a short behavior paragraph and a clear Args list. It is concise, but the Args section is redundant with the schema, which keeps it from a 5.

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

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

For a simple read-only tool with no output schema, it explains the return concept (tags and group membership), the identity resolution behavior, and the local-only nature. It does not discuss failure modes or response format, but it is sufficiently complete for an agent 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?

Schema description coverage is 100%, and the Args section of the description merely repeats the schema descriptions verbatim. No additional semantic context is added beyond what the input schema already 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?

The description opens with a specific verb and resource: 'Get durable local tags and group membership for one known client.' This clearly distinguishes it from generic client tools such as get_client_details and from listing tools, making the purpose immediately identifiable.

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

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

It explicitly states that set_client_tags or assign_client_group should be used to change the data, providing an clear when-not for mutations. It also frames the operation as read-only and local, giving solid usage context, though it does not contrast with other read-oriented sibling tools.

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

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

Beyond the readOnlyHint annotation, the description adds important behavioral context: the operation is read-only, previews are local, and apply_client_qos_policy performs no controller mutation in the current release. This meaningfully sets expectations and is consistent with the annotation.

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

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

The description is concise, front-loaded with the core purpose, and contains useful caveats. The Args section repeats schema-provided information but is not excessive; the overall structure is clear and efficient.

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

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

For a single-optional-parameter read-only capability check, the description is largely complete: it explains the preflight role, related policy tools, and local/no-mutation behavior. It does not specify the exact return format, but 'reports whether' is sufficient for an agent to act on the result.

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

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

Schema description coverage is 100%, and the description's Args section essentially duplicates the schema's parameter text. No additional semantic detail is added beyond what the input schema already provides, so the baseline 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 and resource: it 'reports whether a validated controller QoS adapter is available' for a targeted device. It also references plan_client_qos_policy and apply_client_qos_policy, which disambiguates it from nearby QoS-related 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?

Provides explicit usage context: 'Use this before planning a policy to set expectations.' It names related QoS tools and clarifies that apply_client_qos_policy performs no controller mutation, but it does not fully enumerate when-not-to-use conditions or alternative selection criteria.

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

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

Annotations declare readOnlyHint=true, and the description reinforces this by saying 'Read-only operation: returns the client's cumulative and recent traffic counters.' This adds useful behavioral context beyond the annotation, such as the counters being cumulative/recent and covering rx/tx, throughput. It does not describe exact return formatting, but that is less critical for a read-only stats tool.

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

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

The description is compact and front-loaded: first sentence states the purpose, second clarifies the read-only nature and return scope, third routes to alternatives, and the Args block is minimal. No wasted language.

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

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

The description is complete enough for selection and invocation: required parameter, default site, optional device, and alternatives are all covered. There is no output schema, but the description names the key returned data ('cumulative and recent traffic counters') and the operation type. A slight gap is the absence of units or exact return structure, but this is not blocking for a read-only traffic stats call.

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

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

The schema description coverage is 100%, with each parameter already documented accurately (mac, site, device). The description repeats the parameter meanings in an Args block but adds no additional semantic detail beyond what the input schema provides, so baseline 3 is appropriate.

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

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

The description states a specific verb and resource: 'Get traffic statistics (rx/tx, throughput) for one client by MAC address.' It also differentiates itself from nearby siblings by explicitly naming get_client_details and get_traffic_summary as alternatives for different use cases.

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: 'Use get_client_details for identity/connection state, or get_traffic_summary for site-wide traffic rather than a single client.' It also identifies that this is read-only, and the optional device parameter is scoped.

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

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

The readOnlyHint annotation already establishes safety, and the description adds meaningful behavior: reads are read-only, the device is resolved by MAC first then by name, and the return includes configuration and runtime data. It does not discuss failure modes, but the annotation lowers the bar.

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

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

The description is front-loaded with the core purpose and return contents, then gives alternatives and args. The Args block duplicates the schema descriptions, but the overall structure remains clear and efficient.

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

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

For a read-only detail lookup, the description covers what the tool returns, how the device is resolved, and how it differs from get_device_stats. It does not specify output format or error behavior, but with no output schema and a low-complexity tool, this is sufficient.

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

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

Schema coverage is 100%, so the schema already documents all three parameters. The description repeats the Args and adds a small behavioral detail about MAC-first resolution, but it does not substantially extend the semantic meaning beyond the schema.

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

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

The description uses a specific verb and resource: 'Get detailed configuration and runtime record for one UniFi device.' It then enumerates the returned content (ports, radios, uplink, system stats, temperatures, traffic counters), which clearly differentiates it from siblings like get_device_stats.

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

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

It explicitly tells the agent to use list_devices to find the MAC and get_device_stats for a metrics-only view without the full config dump. This directly guides tool selection against two relevant sibling tools.

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

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

The readOnlyHint annotation already declares the operation is read-only, and the description reinforces this by stating 'Read-only operation' and listing exactly what metrics are reported. It adds useful behavioral context about the scope and content of the summary, though it does not describe output format or potential response limitations.

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

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

The description is compact and well-organized: a single sentence states the core purpose, a second sentence clarifies read-only behavior and content, and the usage guidance names alternatives efficiently. The Args section is redundant with the schema but harmless and minimal.

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

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

Given the tool's relatively simple behavior, the description covers the essential contextual information: what the summary includes, that it is read-only, and which sibling tools cover related but different needs. No output schema exists, but the listed output content gives enough expectation. A short note about response shape or error behavior would make it fully complete.

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

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

Schema coverage is 100%, so the schema already documents both parameters with defaults and descriptions. The tool description restates the site and device parameters but adds no new semantic detail beyond what the schema provides. This matches the baseline for full schema coverage.

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

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

The description clearly identifies the operation (summarize device health), the resource (APs, switches, and routers at a site), and the specific data included (uptime, load, memory, temperature, firmware, devices needing attention). It also names sibling tools that serve different purposes, making the tool's unique role unmistakable.

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

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

The description explicitly tells the agent when to use this tool versus alternatives: use get_site_health or get_network_health for overall/site status, analyze_network_issues for issue reports, and get_client_experience_report for client perspective. This is direct routing guidance with no ambiguity.

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

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

Annotations already set readOnlyHint=true, and the description reinforces it with 'Read-only operation.' It adds transparency by listing exactly what is returned (media, link state, speed, native VLAN ID, PoE mode, peer MAC/IP) and notes the 'where known' caveat on peer data. No destructive or hidden behavior is possible.

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 narrative portion is tight and front-loaded, but the Args block duplicates the schema's parameter descriptions nearly verbatim. This is a minor redundancy since the input schema already documents mac, site, and device.

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

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

There is no output schema, so the description compensates by listing all returned port attributes and the 'where known' caveat. It also covers the mac format, site default, and optional device target, making the tool callable without external documentation.

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

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

Schema description coverage is 100%, and the Args section simply repeats the schema's parameter descriptions without adding new semantic detail. The baseline of 3 applies because the schema already carries the explanatory 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 first sentence states a specific verb and resource: 'List the switch/gateway ports on a device with link and VLAN details.' It enumerates the returned fields, which separates it from sibling read tools like get_device_details and explicitly links it to set_device_port.

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

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

The description explicitly prescribes when to use it: 'Use this to find the port_idx and current values before calling set_device_port.' This is a concrete workflow instruction, and the read-only label tells the agent it is safe for retrieval.

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

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

Annotations declare readOnlyHint=true, and the description reinforces and expands on this by listing exactly what metrics are returned and noting 'where applicable' for AP radio stats. This goes beyond the annotation's minimal signal, though it does not discuss rate limits or error conditions.

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

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

The description is front-loaded with the core purpose, followed by a compact metric list and explicit sibling alternatives. The Args section is structured and each sentence contributes meaningful guidance without redundancy or 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?

Despite lacking an output schema, the description names the expected return content in enough detail (CPU/memory, temperatures, fan, client counts, traffic, AP stats) for an agent to know what this tool provides. With all parameters documented and alternatives specified, nothing needed for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description's Args section largely duplicates the schema rather than adding new semantics; it clarifies MAC format and device targeting, but these are already present in the schema descriptions.

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

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

States a specific verb and resource: 'Get performance and traffic statistics for one UniFi device.' It enumerates the metrics returned and explicitly distinguishes itself from get_device_details and list_devices, so an agent can immediately understand its scope relative to 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?

Provides clear routing guidance: use get_device_details for full config records, list_devices for lightweight summaries, and this tool specifically for metrics. It also frames the operation as read-only, helping the agent choose appropriate contexts.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only operation.' It adds behavioral context beyond the annotation by explaining that results are ranked by detected application/category, which tells the agent what kind of analysis the output supports. It does not go into return format or aggregation details, but the read-only safety profile is clearly covered.

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

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

The description is front-loaded with the core purpose, followed by read-only context and alternative tools, and ends with a clean Args section. It is reasonably concise, though the Args section largely repeats the schema descriptions that are already present.

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

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

For a tool with no output schema, the description gives enough context that an agent knows what the tool returns (application/category breakdown ranking) and when to use it. It does not detail the exact output fields or time window, but all parameters are fully documented and the tool's role among siblings is clear.

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 site and device are already documented in the input schema with the same wording. The description's Args section duplicates this information rather than adding new semantic detail, so a 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 opens with a specific verb and resource: 'Return Deep Packet Inspection application-breakdown statistics for a site.' It further clarifies that it ranks traffic by detected application/category, making the tool's role distinct from traffic summary, time-windowed analysis, and per-client DPI views.

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

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

The description explicitly names sibling alternatives and the conditions under which they should be used: 'Use get_traffic_summary for a lighter volume-only overview, get_traffic_analysis for time-windowed trends and top talkers, or get_client_traffic for a single client's DPI view.' This gives an agent clear routing guidance.

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

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

The description explicitly labels the operation as read-only, matching the readOnlyHint annotation. It also discloses what the response contains: each known event source, its capabilities, and whether background polling is enabled. This adds useful behavioral context beyond the bare annotation.

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

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

The description is compact and front-loaded: the first sentence states exactly what is listed, the second confirms the read-only behavior and return contents, and the third gives practical usage direction. No wasted words.

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

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

Despite having no output schema, the description sufficiently explains what the tool returns and how to use that output. It also names the relevant sibling tools for follow-up actions. For a parameterless status/discovery tool, nothing essential 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 has zero parameters, so the input schema carries no semantic burden. The description still clarifies that the operation covers all known event sources, which is sufficient for a no-argument discovery endpoint.

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

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

The description names a specific verb ('List') and a precise resource ('event source capabilities and background polling state'). It clearly differentiates itself from siblings by framing this as a discovery/status tool, not an action tool like poll_events_now or list_runtime_events.

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

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

The description explicitly tells the agent when to use this tool: to discover source names for poll_events_now, or to decide to use list_runtime_events for stored events. This is direct routing guidance and names the relevant alternative tools.

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

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

Annotations provide only readOnlyHint=true, and the description adds meaningful behavior beyond that: policies are evaluated in index order, and predefined '(Return)' companions appear alongside custom rules. It also notes the UniFi Network 9+ version requirement. No contradiction with annotations.

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

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

The description is front-loaded with purpose, then return fields, then behavioral context, and then management alternatives. It is structured and each paragraph carries useful information. The only minor redundancy is the Args block duplicating schema text.

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 no output schema, the description summarizes the return payload sufficiently: name, action, protocol, index order, and source/destination zone ids. It also covers optional site/device targeting and key evaluation behavior. Pagination or exact response shape is not described, but that is a minor gap for a read-only list operation.

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

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

Input schema coverage is 100%, and both parameters are already described in the schema with the exact same text as the description's Args section. The description adds no new semantic meaning over the schema. Baseline 3 is appropriate.

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

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

The description opens with 'Get zone-based firewall policies (UniFi Network 9+)', a specific verb and resource, and enumerates the returned fields. The 'zone-based' qualifier clearly differentiates this from the sibling get_firewall_rules. The purpose is unmistakable.

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

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

The description explicitly names create_firewall_policy, set_firewall_policy_enabled, and delete_firewall_policy as the tools for adding or managing policies, guiding the agent to the right call for non-read operations. It also reinforces the read-only nature, which helps distinguish it from mutation tools. It does not explicitly contrast with get_firewall_rules, but the management alternatives are clearly 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, so the read-only claim is redundant, but the description adds useful behavior beyond the annotation by enumerating exactly what data is returned (name, action, protocol, port, ruleset, firewall-group bindings). It also flags that this is legacy functionality on modern controllers. No contradiction with annotations.

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

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

The description is compact and front-loaded with purpose, followed by return details and routing guidance. The Args section is somewhat redundant with the schema, but it is short and readable, so it does not significantly harm 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 simple read-only list tool with two optional parameters and no output schema, the description is complete: it states the operation type, the returned fields, defaults, and points to alternatives for modern controllers. Nothing essential is missing for correct invocation.

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

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

Schema description coverage is 100%, and the Args section in the description repeats the schema's parameter descriptions verbatim without adding new meaning. The baseline of 3 applies because the schema already fully documents both parameters.

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

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

The description opens with a specific verb and resource: 'Get legacy firewall rule configurations for a site.' It also lists the returned fields, and explicitly distinguishes itself from get_firewall_policies, making it easy for an agent to identify exactly what this tool does.

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

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

The description gives clear routing guidance: modern controllers should use get_firewall_policies, and zone-based filtering should use create_firewall_policy. This tells the agent both when to use this tool and when to choose a named 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?

The description goes well beyond the readOnlyHint annotation by explaining aggregation behavior: it aggregates active clients from network-enabled devices, computes wireless/wired/blocked totals, top 10 talkers, per-device counts, and includes an errors list when a console fails. This materially helps an agent predict behavior and output.

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

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

The description is compact and front-loaded: purpose, behavior, usage alternatives, and return shape each get a concise sentence. There is no filler or repetition that wastes the agent's attention.

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-argument read-only tool with no output schema, the description fully covers scope, aggregation semantics, alternatives, and the return dictionary including failure behavior. An agent has enough context to select and invoke the tool correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameter meaning. The baseline of 4 applies because no parameter guidance is needed.

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

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

The first sentence states a specific verb and scope: 'Summarize connected clients across every configured network console.' It clearly distinguishes this tool from per-console tools like list_clients and names related siblings, so an agent can tell what it does without opening schemas.

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

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

The description explicitly says to use this tool for fleet-wide client visibility and names alternatives: get_global_inventory for the device roster, get_global_health for subsystem health, and list_clients for full per-client detail. This provides clear routing guidance with 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?

Beyond the readOnlyHint annotation, the description discloses what the operation collects (WAN/LAN/WLAN status, health score, device/user counts), how it folds it into a healthy/degraded verdict, and that a per-device errors list appears when a console fails. This is meaningful behavioral context beyond the structured annotation.

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 front-loads the core purpose in the first sentence, then adds a scoped usage sentence and a compact return-value summary. No filler or redundancy beyond a harmless restatement of read-only behavior.

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

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

For a zero-parameter read-only tool with no output schema, the description is complete: it covers scope, aggregated output fields, verdict semantics, failure behavior, and alternative tools. An agent has enough to invoke and interpret the result correctly.

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

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

The tool has zero parameters and schema coverage is 100%, so there is no parameter semantics burden on the description. The baseline for a no-parameter tool is 4; the description appropriately omits parameter details.

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

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

The description uses a specific verb and resource ('Aggregate site health across every configured network console') and clearly identifies the fleet-wide scope. It distinguishes itself from sibling tools by naming get_site_health for single-console detail and other global tools for inventory/client counts.

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 states exactly when to use the tool ('single fleet-wide health check') and lists alternatives with their purposes: get_global_inventory for device roster, get_global_client_summary for client counts, and get_site_health for full subsystem detail on one console. This is explicit routing with little 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?

Beyond the readOnlyHint annotation, the description discloses the underlying mechanism: it calls list_devices on each network-enabled device, merges results, tags entries with source device name, and captures per-console errors. It also specifies the return shape, giving the agent a clear behavioral model.

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

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

The description is well structured: a one-sentence purpose, a short read-only behavior note, explicit usage routing, and a compact Returns section. Every sentence adds information; none are redundant or filler.

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

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

For a zero-argument read-only aggregation tool, the description fully covers what it does, how it behaves, when to use it, and what it returns. There is no output schema, so the description's return-structure explanation is essential and sufficient.

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

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

The tool has zero parameters and the schema coverage is 100%, so the description does not need to explain parameter meanings. The baseline of 4 applies because there are no parameters to document.

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: 'Aggregate the full device inventory across every configured network console.' It also enumerates the device categories included (AP, switch, gateway, router), and clearly distinguishes this tool from nearby siblings by naming what it is not for.

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

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

The description gives explicit guidance: use this for a merged multi-console device view, use list_unifi_devices for the console roster itself, and use get_global_health / get_global_client_summary for aggregated health/client counts instead. This clearly routes the agent away from similar tools.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with 'Read-only operation' without contradicting it. It adds useful context beyond annotations: the exact returned fields, the targeting of a specific Protect console, and the explicit negative scope of not returning footage or snapshots.

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

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

The description is well-structured: core action first, then scope and use cases, then the parameter explanation. It is compact and informative, though 'Read-only operation' is slightly redundant with the annotation and the Args block mirrors the schema.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description is complete: it explains the parameter resolution rule, the read-only nature, what fields are returned, and what is explicitly not returned. An agent has enough information to invoke and interpret the tool correctly.

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

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

The schema description coverage is 100%, and the description's Args block essentially repeats the schema's wording for the optional `device` parameter. No additional semantic meaning, like format constraints or resolution order beyond the already-documented 'omit to use the first Protect-enabled device', 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?

The description opens with 'List all configured UniFi Protect liveviews (camera view layouts)', which is a specific verb and resource. It further clarifies the return contents (name, id, cameras, layout) and explicitly states it does not return footage or snapshots, distinguishing it from related media-retrieval tools.

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

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

It explicitly states when to use the tool: 'Use this to discover view groupings for dashboards or to confirm which cameras belong to a named liveview'. It also provides a when-not boundary by noting it 'does not return footage or snapshots'. However, it doesn't name alternative sibling tools for footage or snapshots, so it falls short of a 5.

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

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

The readOnlyHint annotation already marks it read-only, and the description reinforces the read-only nature while adding genuine behavioral detail: it queries Protect events, maps them to camera names/human-readable timestamps, returns count and per-event list, and requires Protect credentials. This goes beyond annotation-only information.

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, followed by concise read-only/requirements/alternatives and a compact Args block. No filler; each section contributes.

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 query with no output schema, the description tells the agent what it will get (count and per-event list with camera name/timestamp), how to constrain results, and which credential prerequisites exist. That is sufficient to invoke and interpret the result.

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

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

Input schema already covers all four parameters with the same descriptions and defaults, so the description adds no new meaning for hours, limit, camera_id, or device. The Args section is useful for visibility but not semantically additive 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?

Opens with a specific verb and resource: 'Return recent camera motion events, resolved to camera names and timestamps.' It also names sibling alternatives, immediately distinguishing this tool from get_smart_detections and get_protect_event_summary.

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

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

Explicitly states when to use alternatives: get_smart_detections for AI classification, get_protect_event_summary for aggregate counts. Also gives the lookback-window context and required credentials, making the selection criteria 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?

The description labels the operation read-only, matching the readOnlyHint annotation, and adds meaningful context about what the condensed report contains: WAN/LAN/WLAN status, a composite health score, and device/user tallies. It does not describe exact return formatting, but the annotation lowers the burden and the description still adds substantive behavioral detail.

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 opening sentence and the alternatives paragraph are tight and front-loaded. However, the Args block duplicates the input schema's descriptions almost verbatim, which adds length without new information for an agent that already has access to the schema.

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

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

With only two optional parameters, a readOnly annotation, and no output schema, the description provides sufficient selection criteria, default behavior, and a summary of the returned report contents. It could be more explicit about the exact response structure, but nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the baseline is 3. The Args section in the description restates the schema descriptions (site defaults to 'default'; device is optional console name) without adding new constraints, format details, or examples beyond what the schema already provides.

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

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

States a specific verb and resource: 'Return a single overall health summary for one site's network.' It further specifies the aggregated content (WAN/LAN/WLAN status, composite health score, device/user tallies) and explicitly distinguishes itself from sibling tools like get_site_health, get_all_sites_health, and get_global_health.

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

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

Explicitly names the alternatives and the conditions that select them: use get_site_health for full per-subsystem detail, get_all_sites_health for a multi-site sweep, and get_global_health for cross-console aggregation. This gives an agent clear routing guidance with no inference required.

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

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

The description declares 'Read-only operation' and explains what the tool returns, adding value beyond the readOnlyHint=true annotation. It does not cover edge cases like site-not-found behavior, but for a simple read operation the disclosed behavior is sufficient.

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

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

The description is compact and front-loaded: purpose, read-only nature, return contents, alternatives, then parameters. Every sentence contributes useful information, and the argument block is clearly formatted.

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