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

With no annotations provided, the description carries the full burden, and a one-line effect statement ('Block a client device from the network') is all it offers. It does not disclose whether the block persists across reboots, whether it immediately disconnects an active client, or whether it can be reversed via unblock_client. For a network-altering mutation, these gaps leave the agent guessing about 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 a single eight-word sentence with no filler, redundancy, or repetition of structured data. The verb is front-loaded, so an agent immediately knows the action before reading the parameter details.

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

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

For a one-parameter tool this is close to minimally viable: the agent knows the action and the required input. But with no output schema and no annotations, the description does not cover post-call behavior such as confirmation, error conditions (e.g., unknown MAC), or reversibility. The gaps are notable but not crippling for such a simple tool.

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

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

Schema description coverage is 100%, so the mac parameter is already documented as 'MAC address of the client to block.' The description adds no additional parameter context, such as MAC format expectations (colons vs dashes) or validation rules. Per the rubric, the baseline 3 applies when the schema carries the burden, and that is exactly the case here.

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

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

The description uses a specific verb ('Block') with a clear resource ('a client device') and scope ('from the network'), making the core action unambiguous. It reads distinctly from the many read-oriented siblings like list_clients and get_client_details. However, it does not explicitly differentiate from block_restricted_youtube, whose narrower scope must be inferred from its name rather than contrasted here.

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

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

No guidance is given about when to use this tool versus alternatives such as block_restricted_youtube, unblock_client, or reconnect_client. An agent must infer the use case solely from the verb and the file naming convention. There are no exclusions, prerequisites, or when-not-to-use notes.

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 disclosing behavior. It states the blocking action and its scope, but does not explain side effects (e.g., whether existing YouTube sessions are terminated, whether the block is persistent, whether special permissions are required, or what the response looks like). This is a significant gap for a mutating operation with zero annotation coverage.

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

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

The description is a single sentence with the verb, object, and scope front-loaded. Every word earns its place, and there is no filler or redundant information.

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

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

With no parameters and no output schema, the operational core of the tool is fully described. The only minor gap is that the description does not explicitly mention how the operation relates to sibling tools (e.g., that unblock_restricted_youtube reverses it), though the sibling list itself implies this. This is a nearly complete definition for such a simple tool.

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

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

The tool takes zero parameters, so the input schema is complete by definition (schema_description_coverage is 100%). The description compensates for the lack of parameters by explicitly specifying the scope ('all Restricted devices'), which is exactly the kind of semantic detail an agent needs. Baseline 4 for 0-parameter tools.

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 ('Block') and a specific target ('YouTube') plus a defined scope ('all Restricted devices'), making the action unambiguous. It clearly distinguishes this tool from the sibling 'unblock_restricted_youtube' which reverses the operation.

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 a clear use case and therefore orients an agent toward when it would be relevant, but it gives no explicit guidance on when to choose this over alternatives such as block_client or unblock_restricted_youtube. There is no when/when-not language or mention of conditions that would make this the right 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure, yet it only states the basic mutation and says nothing about duplicate-name handling, idempotency, reversibility, required permissions, or return content. The 'bandwidth limits' phrase restates parameter intent, not runtime 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?

One sentence with the verb front-loaded and no filler words. 'Create' states the action, 'new user group' the resource, and 'with bandwidth limits' the relevant parameters — every word earns its place.

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

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

The flat 3-parameter schema is fully documented and the purpose is clear, but with no annotations, no output schema, and no disclosure of return values, duplicate-name behavior, or error conditions, an agent cannot anticipate failure modes or verify that creation succeeded. For a mutating tool, this is a significant operational gap.

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

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

Schema coverage is 100%, so the schema already documents all three parameters (name, up, down) with units and the -1 unlimited sentinel. The description's 'bandwidth limits' adds no meaning beyond what the schema provides, leaving the score at the baseline 3.

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

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

The description uses a specific verb ('Create') and resource ('user group'), with 'with bandwidth limits' previewing the up/down parameters. The action is unambiguous within a sibling list dominated by get/list/set tools, though it does not explicitly name or rule out related siblings like set_client_user_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?

No guidance is given on when to use this tool versus alternatives — there are no prerequisites, exclusions, or references to sibling tools like list_user_groups for inspection or set_client_user_group for assigning users. The only usage signal is the verb 'create,' which is implied rather than stated as a decision rule.

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. 'Create' correctly implies a mutating operation, but the description does not disclose side effects, permissions, whether the operation is reversible, or what happens when creating multiple vouchers. The one-line description only states the action without behavioral context.

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

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

The description is a single sentence with zero filler, front-loaded with the action verb and object. It is appropriately concise for a simple tool and contains no redundant 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?

The tool is low-complexity with complete schema coverage for its required parameters, making a minimal call possible. However, with no annotations and no output schema, the description does not mention what the tool returns (e.g., voucher codes) or any operational context. It is adequate but leaves behavioral and result-related gaps.

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

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

Schema description coverage is 100%, and the input schema already documents all three parameters: note, count, and minutes. The description does not add extra parameter meaning, but the schema handles that responsibility adequately. A baseline of 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 uses a specific verb ('Create') and a specific resource ('guest WiFi voucher'), making the tool's purpose immediately clear. It also differentiates from siblings like create_user_group because no other sibling targets vouchers. This is a strong, unambiguous 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 no guidance on when to use this tool versus alternatives, no prerequisites, and no exclusions. While there is no obvious sibling for voucher creation, the tool does not explain when an agent should choose it, such as when generating guest access credentials. This is a clear gap.

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?

There are no annotations, so the description carries full responsibility for behavioral disclosure. 'Power cycle' implies a disruptive action, but the description does not state that PoE power to the attached device will drop, that the client will be temporarily disconnected, or whether the switch remains otherwise unaffected.

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?

This is a single, direct sentence with no filler, boilerplate, or repetition. It is appropriately sized for a simple two-parameter tool and front-loads the essential action and target.

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 tool with complete schema coverage, this is minimally viable: an agent can select the tool and construct a call. However, because it is a disruptive operation, has no annotations, and has no output schema, adding a note about expected impact or return behavior would make it meaningfully more complete.

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

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

The input schema already documents both parameters at 100% coverage, so the description does not need to explain them. The description does not add any extra semantic detail beyond the schema, so the baseline score of 3 is appropriate.

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

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

Fewer than ten words, the description names a specific verb ('Power cycle') and resource ('PoE port on a switch'), which clearly distinguishes it from sibling actions like rebooting a whole device (reboot_device) or reading network state (get_network_status). An agent can infer exactly what this tool does and what it operates on.

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

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

The description gives no guidance about when to use this tool, when not to use it, or which sibling alternative might be more appropriate. With a large sibling list containing similar recovery-related actions like reboot_device and reconnect_client, the absence of any selection criteria is a real gap.

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 verb 'Delete' makes the destructive nature of the operation clear, and 'by id' communicates the required input. But since there are no annotations, the description carries the full burden and does not disclose additional behavioral traits such as irreversibility, permission requirements, or what happens on failure.

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

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

The description is a single, clear sentence with no unnecessary words. It states the action, the object, and the required identifier in an efficient, front-loaded manner.

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 one-parameter delete operation with no output schema, the description is sufficiently complete. It covers what the tool does and how to target the rule. Additional details about return values or error handling would be nice but are not essential for this simple operation.

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

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

Schema description coverage is 100% and the 'id' parameter is already described as 'The _id of the rule to delete.' The tool description adds no further parameter context beyond what the schema already provides, so the baseline of 3 applies.

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

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

The description uses a specific verb and resource: 'Delete a port forwarding rule by id.' It clearly identifies the action and target, and distinguishes itself from sibling tools like get_port_forward_rules, update_port_forward_rule, and delete_traffic_rule.

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

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

The description implies usage: use this when you want to delete a specific port forwarding rule by its id. However, it provides no explicit guidance on when not to use it or when to prefer alternatives such as update_port_forward_rule or ensure_port_forward_rule.

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 states that the tool deletes, but does not mention whether deletion is irreversible, whether deleting a nonexistent id is an error, what side effects occur, or what the response looks like. For a destructive operation this is thin.

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

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

The description is a single, front-loaded sentence with no unnecessary words. It efficiently communicates the action, target resource, and required identifier for a simple one-parameter tool.

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

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

The tool is simple, and the schema covers the only parameter, making the call invokable. However, the absence of annotations and an output schema leaves important context unaddressed, such as idempotency, failure behavior, and the result of a successful deletion. This is adequate but minimal.

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 fully documents the required id parameter. The description's 'by id' phrase adds little beyond what the schema states, and no extra format, source, or validation context is given for the id.

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 ('Delete') and a specific resource ('traffic rule'), and identifies the selector ('by id'). This cleanly distinguishes it from sibling tools like get_traffic_rules or update_traffic_rule.

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

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

The intended use is implied by the tool name and description, but there is no explicit guidance on when to use this tool instead of update_traffic_rule or ensure_traffic_rule, and no mention of using get_traffic_rules to obtain the id. No alternative routing is provided.

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 present, so the description needs to disclose whether detection is passive or active, whether it has side effects, and what it returns. It states only the high-level outcome, leaving the tool's operational behavior opaque.

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

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

The description is a single, front-loaded sentence with no filler. It is compact and readable, though it trades detail for brevity.

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

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

For a one-optional-parameter read-style tool, the description gives the core purpose but omits the output/return behavior and any assumptions (e.g., requiring admin privileges or a scan). It is adequate for basic invocation but not 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?

The single parameter iotVlanId is fully described in the schema ('Optional IoT VLAN ID to exclude'), and the description adds no parameter-level detail. With 100% schema coverage, 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 names a specific action ('Identify') and a specific resource ('potential IoT devices that are not on the IoT VLAN'), which makes the tool's function clear. It does not explicitly compare itself to overlapping siblings like list_devices or search_network, so it falls short of full differentiation.

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

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

No guidance is given about when to choose this over alternatives such as list_devices or search_network, nor are any prerequisites or follow-up actions mentioned. The only contextual clue is the tool's name, so an agent must infer usage.

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

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

No annotations exist, so the description carries the full disclosure burden, yet it only states the bare action. It does not disclose whether throttling is reversible, whether it persists or overwrites existing traffic rules, what side effects (e.g., degraded device connectivity) may result, or whether admin privileges are required. For a mutating network operation, this is a material gap.

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

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

A single tight sentence with the verb front-loaded and no wasted words. It is appropriately compact, though the terseness contributes directly to the behavioral transparency and usage-guidance gaps.

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 one optional parameter and full schema coverage, the description is partially adequate, but as a mutating action with no annotations and no output schema, it omits essential context: mechanism, reversibility, interaction with existing rules, and what qualifies a device as 'IoT' or 'high-bandwidth'. Related sibling tools like detect_iot_devices and ensure_traffic_rule imply workflows that the description never references.

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 thresholdMbps already documented including type, unit, and default value. The description adds no parameter-level meaning beyond echoing the concept of bandwidth, 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 uses a specific verb ('Throttle') and a clear target resource ('high-bandwidth IoT devices'), conveying a rate-limiting action that is conceptually distinct from block_client, reboot_device, or cycle_poe_port. However, it does not state the mechanism (traffic rule, QoS policy, rate limit) and does not differentiate itself from update_traffic_rule or ensure_traffic_rule, which could plausibly perform the same action.

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

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

There is no guidance on when to invoke this tool versus alternatives. With close siblings like update_traffic_rule, ensure_traffic_rule, and block_client all capable of affecting device bandwidth, an agent has no basis for selecting among them. No context, preconditions, or exclusions are provided.

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 are absent, so the description carries the full disclosure burden. 'Create or update' does reveal an idempotent upsert behavior, which is useful, but it stops short of stating what identifies an existing rule (match key), whether an existing rule is overwritten, or what happens on conflicting field values. For a mutation tool with zero annotation coverage, this is under-disclosed.

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?

Six words, zero filler, and the action verb is front-loaded. It is maximally scannable and every word earns its place; the only deduction is that the extreme terseness is achieved by sacrificing usage and behavioral detail that other dimensions have to supply.

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 7-required-parameter mutation tool with no annotations and no output schema, a single sentence is inadequate. Critical operational facts are missing: how 'ensure' resolves an existing rule, whether it can create, update, or both by name, what conflicts do, and what the call returns. The surrounding get/update/delete_port_forward_rule sibling family makes this omission more consequential for agent decision-making.

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 57%, with fwd, src, proto, dst_port, and fwd_port already documented meaningfully — including the practical 'usually any' hint on src. The description adds no parameter-level information and does not compensate for the undocumented name and enabled fields, though those are fairly self-explanatory. Moderate schema coverage keeps this at 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 pair ('Create or update') attached to a concrete resource ('port forwarding rule'), and the 'ensure' naming convention is honored by revealing the upsert semantics. It clearly distinguishes from get_port_forward_rules and delete_port_forward_rule, though the overlap with update_port_forward_rule is never resolved explicitly.

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

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

No guidance is given on when to prefer this tool over update_port_forward_rule, which is a near sibling whose existence creates genuine ambiguity. The description neither states the condition that selects the ensure path nor mentions any prerequisites or exclusions, leaving the agent to guess which operation is intended.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does disclose the upsert behavior (create or update), which is genuinely useful since 'ensure' semantics imply it will not fail on existing rules. However, it does not state whether updating an existing rule merges or replaces it, whether unspecified fields are reset, what prerequisites exist, or what side effects occur — notable gaps for a mutating 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 single sentence is front-loaded with the active verb phrase and contains no redundant clauses. However, its brevity reflects under-specification rather than pruning, and the word 'complex' is wasted, so this is not appropriately sized for the tool's 8-parameter surface.

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

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

A 6-word description is grossly inadequate for a tool with 8 parameters, 2 enums, conditional target-array relationships, no annotations, and no output schema. An agent cannot determine which target_* arrays apply to which matching_target values, how updates interact with existing rules, or what a successful invocation returns.

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 0%, so the description must compensate for the bare schema, but it mentions no parameters at all. Critical semantics are undocumented: how matching_target (NETWORK/DOMAIN/APP/APP_GROUP/IP_GROUP) conditionally relates to the various target_*_ids arrays, what the action enum values imply, and what 'enabled' defaults to.

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 pair ('Create or update') and a specific resource ('traffic rule'), making the idempotent upsert nature clear. It does not explicitly differentiate itself from the sibling update_traffic_rule, though the create-or-update phrasing implies the distinction. The qualifier 'complex' is vague filler that does not add meaning.

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

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

There is no guidance on when to choose this tool over update_traffic_rule, delete_traffic_rule, or get_traffic_rules. The 'create or update' phrasing gives an implied usage context, but no explicit conditions, exclusions, or routing guidance are provided for an agent deciding between 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool lists recent alarms and threats, but does not clarify default behavior around 'archived', whether threats are separate from alarms, how results are ordered, or what the response looks like.

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

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

The description is a single, front-loaded sentence with no filler or redundant information. Every word contributes to conveying the core 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?

The tool has only two optional parameters, no nested objects, and full schema coverage, so it is quite callable as-is. However, with no output schema and no usage guidance, an agent may still lack clarity on expected return shape or when to choose this tool over similar network-status siblings.

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 provides full descriptions for both parameters ('limit' and 'archived'), covering 100% of them. The description itself adds no parameter-level detail, so the baseline score of 3 applies.

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

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

The description clearly identifies the operation with a specific verb ('List') and resource ('recent network alarms and threats'), making the tool's purpose understandable. However, it does not explicitly distinguish itself from siblings like get_events or get_deep_dive, so it falls short of full sibling differentiation.

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

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

The description provides no guidance on when to use this tool versus alternatives such as get_events, get_deep_dive, or get_network_health. It also gives no exclusions or conditions that would help an agent decide between related monitoring 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?

No annotations are present, so the description bears the full behavioral burden. It only states the action and resource; it does not disclose whether the data is current vs. historical, how 'top' is determined, whether a time range applies, or what the response shape is. For a tool with no annotations, this is a significant gap.

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

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

The description is a single front-loaded sentence with no filler, making it very efficient for such a simple tool. It is concise, though the brevity contributes to missing behavioral context.

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

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

Given that this is a one-optional-parameter tool with no output schema, the combination of description and schema provides a minimum viable understanding. However, because there are no annotations and the description omits behavioral details (e.g., metric definition, scope, response), it is not fully complete for safe autonomous 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 schema fully documents the single 'limit' parameter, including its type and default value, so the 100% coverage baseline applies. The description does not add any information about the parameter 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 uses a specific verb ('Get') and a clear resource ('top bandwidth consumers'), making the primary function immediately understandable. It does not explicitly distinguish this from sibling tools like get_dpi_stats or list_clients, but the resource phrase is sufficiently specific.

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

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

There is no mention of when to prefer this tool over alternatives such as get_dpi_stats, get_client_dpi, or get_network_health, nor any exclusionary guidance. The purpose statement weakly implies usage for identifying heavy network users, but no explicit decision context is provided.

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 behavioral transparency burden. It does convey a read-only intent through 'get', but it does not disclose what 'comprehensive details' includes, whether authentication is needed, or any edge-case behavior. This is a minimal but not misleading disclosure.

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

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

The description is a single sentence with no filler or redundancy. It is directly front-loaded with the action and target resource, making it easy for an agent to parse quickly.

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

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

For a one-parameter getter, the description is minimally viable, but the phrase 'comprehensive details' is vague and there is no output schema to clarify the return payload. It also omits any relationship to similar sibling tools, leaving the agent to infer when this tool is the right choice.

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

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

The input schema fully describes the only parameter ('MAC address of the client') with 100% coverage, so the description adds little beyond the schema. This matches the baseline for high schema coverage.

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

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

The description clearly states a specific verb ('get') and resource ('specific network client'), and 'comprehensive details' signals a full-detail lookup rather than a list operation. It does not explicitly differentiate from siblings like get_client_history or get_client_dpi, but the resource and scope are reasonably distinct.

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

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

No guidance is given on when to use this tool versus alternatives such as list_clients, get_device_details, get_client_history, or get_client_dpi. There are no exclusions, prerequisites, or conditions provided.

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 reveals that this is a read operation but adds nothing beyond that — no mention of return format, pagination behavior, whether the client must be online, data freshness, or how results are aggregated. The description essentially restates the tool's name with minimal added 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?

A single, front-loaded sentence that names the verb and resource immediately. There is no wasted text, and the expansion 'DPI' is a useful clarification. It could earn a 5 by also naming the differing sibling in the same breath, but as written it is efficiently 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?

For a simple 2-parameter read tool with no output schema, the description is minimally viable — an agent knows what to call and roughly what to pass. But it lacks any return-value expectations, default behavior for 'limit', or guidance distinguishing it from get_dpi_stats and get_bandwidth_stats, which leaves meaningful gaps for a correct 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?

Schema description coverage is 100% (both 'mac' and 'limit' have descriptions), so the schema does the heavy lifting. The description's phrase 'for a specific client' reinforces the mac parameter's role and implies per-client scoping, but it does not add meaning beyond what the schema already documents. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Get'), a clear resource ('Deep Packet Inspection (DPI) statistics'), and a scope ('for a specific client'). This differentiates it from the sibling get_dpi_stats, which presumably covers network-wide DPI data. However, it does not explicitly name the sibling or the selection criterion, so the differentiation is implicit rather than stated.

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

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

No guidance is given on when to use this tool versus alternatives. With 50+ siblings including get_dpi_stats, get_bandwidth_stats, and get_client_details, an agent is left to infer the use case from the name alone. There are no exclusions, prerequisites, or 'use X instead' statements.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. The verb 'Search' implies a non-mutating read operation and 'controller history' indicates temporal scope, but the description does not disclose response shape, pagination, permissions, or any edge 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 a single, focused sentence with no filler or redundancy. It communicates the essential operation immediately and every word earns its place.

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

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

The tool is simple with only two parameters and no output schema, so the description does not need to be extensive. However, the absence of sibling differentiation and behavioral details leaves some ambiguity about what 'controller history' means and how results relate to current client data.

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

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

Schema description coverage is 100%, so the schema already documents query and hours parameters. The description adds general context about clients and history, but it does not provide additional parameter-level semantics beyond what the schema states.

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

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

The description uses a specific verb ('Search') and a specific resource ('clients in the controller history'), making the core operation clear. It does not explicitly differentiate from siblings like list_clients, search_network, or get_client_details, so it falls short of a 5.

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

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

The description provides no guidance on when to use this tool versus alternatives such as list_clients, search_network, or get_client_details. There are no exclusions, prerequisites, or context cues beyond the word 'history', so the agent must infer usage.

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

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

With no annotations and no output schema, the description must disclose behavior, but it only says the tool 'performs' a deep dive. It does not state whether this is read-only, whether it aggregates data, whether it has performance implications, what data sources it draws from, or what the response contains.

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

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

The description is a single sentence with no filler and the three listed topics are easy to parse. However, it is concise at the expense of useful detail, so it does not quite earn a 5.

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

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

For a no-input tool, the description should make the output scope clear, but it leaves the result format and depth unspecified. Given the large sibling list and the absence of annotations or an output schema, an agent has no way to predict what this call returns or why it is preferable to the narrower network-health and DPI tools.

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 is empty and there are zero parameters, so there is nothing for the description to add about parameter meaning. The baseline of 4 applies because no parameter documentation burden exists.

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 three content areas — network health, DPI stats, and active client traffic — but 'perform a deep dive' is not a specific operational verb and does not clarify what the tool returns. It also overlaps heavily with siblings like get_network_health, get_dpi_stats, and get_client_dpi, so an agent cannot distinguish this tool from those based on the description alone.

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

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

There is no guidance on when to use this tool instead of the many overlapping siblings. The description neither states a preferred use case, nor excludes alternatives, nor explains how a 'deep dive' differs from simply calling get_network_health or get_dpi_stats.

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 disclosing behavior. 'Get' implies a read operation, but the description does not state whether the operation is read-only, whether special permissions are needed, what happens for invalid MAC addresses, or what kind of 'detailed information' is returned.

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

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

The description is a single, tightly written sentence with no filler or repetition. Every word contributes to the meaning, making it easy to parse quickly.

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

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

For a simple one-parameter tool, this is minimally adequate: the agent can identify the action and provide the required MAC address. However, with no output schema and no description of what 'detailed information' includes, the agent lacks context about the expected return value or potential error conditions.

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

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

Schema description coverage is 100%, so the schema already documents the 'mac' parameter. The description adds only the word 'specific', which aligns with the parameter but provides no extra format or behavioral details beyond the schema.

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

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

The description clearly states a specific verb ('Get') and resource ('detailed information about a specific device'), which distinguishes it from broader list tools like list_devices. However, it does not explicitly distinguish between a 'device' and a 'client', so it is not fully differentiated from get_client_details.

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

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

The description gives no guidance on when to use this tool versus alternatives, and does not mention any exclusions or prerequisites beyond the required MAC address. An agent gets no help deciding between get_device_details, get_client_details, or list_devices.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only implies a read operation via 'Get' and adds nothing about aggregation scope, what the statistics measure, whether data is live or historical, or ordering semantics. It does not contradict any annotation because none exist.

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

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

A single sentence with no wasted words, front-loaded with the core verb and resource. It is appropriately compact for a one-parameter tool, though the brevity partly stems from under-specification rather than deliberate efficiency.

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 simple (one optional parameter, no nested objects), but with no output schema and no annotations, the description leaves gaps: it does not clarify what qualifies as 'top applications' (by bytes, flows, blocked traffic?), the aggregation granularity, or how it differs from get_client_dpi. Minimal adequate for the simplest agent use, but thin against a large sibling set with overlapping DPI/statistics tools.

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

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

Schema description coverage is 100% for the single optional limit parameter, which is already documented as 'Number of top applications to return (default: 10)'. The description adds no parameter meaning beyond the schema, so the baseline of 3 applies.

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

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

The description states a clear verb ('Get') and resource ('DPI statistics for applications'), so an agent knows what the tool retrieves. The phrase 'for applications' hints at an aggregate scope that distinguishes it from get_client_dpi in spirit, but it does not explicitly name or differentiate from any 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?

There is no guidance on when to use this tool versus alternatives like get_client_dpi, get_bandwidth_stats, or get_deep_dive. No when-to-use conditions, exclusions, or alternative routing are mentioned, leaving the agent to infer selection purely from the name.

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

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

With no annotations, the description carries the full burden of behavioral disclosure, but only states 'Get recent network events.' It does not clarify whether this is read-only, what kinds of events are returned, how results are ordered, or any limits like pagination.

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 single sentence is compact and front-loaded, with no filler. It sacrifices explanatory value for brevity, but as a structure it is appropriately short for a one-parameter read 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 tool with no output schema, this might be acceptable if 'network events' were unambiguous. However, the large sibling set contains several event-like tools, and the description does not define event scope or distinguish itself, leaving the agent to guess.

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 covers 100% of the parameter, including the meaning and default of 'hours.' The description's word 'recent' weakly echoes the parameter's purpose but adds no meaningful semantic detail beyond the schema entry.

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 concrete action and resource: retrieving recent network events. It is clear at a basic level, but does not differentiate events from closely related siblings like get_alarms or get_router_logs, so it stops short of a 5.

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

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

The description gives no guidance on when to choose this tool over alternatives such as get_alarms, get_router_logs, or get_client_history. An agent must infer usage from the name and one optional parameter.

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

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

With no annotations, the description carries the full behavioral burden. 'Get all' implies a read-only listing operation and the parenthetical clarifies the group types, but it does not disclose return format, ordering, pagination, or any operational constraints. This is adequate but not rich.

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

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

The description is a single, front-loaded sentence that states the action, scope, and resource type with no wasted words. It is concise while still being informative.

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

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

This is a simple zero-parameter read tool, and the description provides the essential selection information: it returns all configured firewall groups and the relevant group types. It does not describe the output structure, but given the low complexity and absence of parameters, the description is reasonably complete.

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

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

The tool has zero parameters and schema coverage is 100%, so there is nothing for the description to add about parameters. The description still adds useful context by naming the group categories '(IP, Port)', which exceeds the baseline for a no-parameter tool.

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

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

The description uses a clear verb and resource: 'Get all configured firewall groups' with an explicit scope of '(IP, Port)'. It is distinct from the sibling get_firewall_rules by naming 'groups' as the resource, though it does not explicitly contrast itself with that sibling.

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

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

The description gives no guidance about when to use this tool versus alternatives like get_firewall_rules or get_traffic_rules. There is no mention of context, prerequisites, or exclusions, so an agent must infer usage solely from the name.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The word 'Get' implies a read-only operation, but the description does not mention authentication requirements, pagination, result sizing, or any side effects. It reveals little beyond the basic action.

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

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

The description is a single, efficient sentence with no wasted words. It front-loads the action and the resource immediately. The length is appropriate for a tool with no parameters and a straightforward purpose.

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 getter, this description is complete enough for selection and invocation: an agent knows what it returns and that no arguments are needed. It does not describe output structure, but the absence of an output schema and the simplicity of the operation make this a minor gap.

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

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

The tool has zero parameters, so there is nothing for the description to clarify. Per the baseline for tools with no parameters, this is adequate. The description does not need to compensate for schema gaps because there are no schema properties.

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 all configured firewall rules.' It clearly distinguishes the tool from siblings like get_firewall_groups and get_port_forward_rules by naming the exact object being retrieved. It does not explicitly differentiate itself from siblings, but the resource term is specific enough.

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

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

There is no guidance on when to use this tool versus alternatives. The description simply states what it does, with no exclusions, prerequisites, or references to sibling tools like get_firewall_groups or get_traffic_rules. The usage context must be inferred entirely from the tool name.

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

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

The word 'Check' implies a read-only, non-mutating operation, which is useful behavioral information in the absence of annotations. However, the description does not disclose what happens after the check, whether any endpoint is contacted, or what the output represents beyond 'available updates.'

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

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

A single clear sentence with no redundancy. It front-loads the action and immediately states the scope. Every word earns its place.

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

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

For a no-parameter, no-output-schema tool, the description is mostly sufficient: it names the operation and the scope. It could be improved by noting whether the tool only lists updates or performs any additional actions, but this is a minor gap given the simple signature.

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 there is no parameter documentation burden. The description accurately reflects the tool's scope without needing to explain any inputs.

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 ('Check') and a clear resource ('available firmware updates'), and scopes it to 'across all devices.' This clearly differentiates it from sibling tools like get_network_status or get_device_details, which target different resources.

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

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

No guidance is provided about when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or any sibling tool that might also seem relevant, such as get_device_details or list_devices.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. The verb 'Get' makes clear this is a non-mutating retrieval operation, and the parenthetical indicates what data will be returned. However, it does not describe output format, potential response size, or any other operational caveats.

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

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

The description is a single concise sentence with no filler. It front-loads the action and resource, then adds precise subcategories in parentheses. Every word contributes to understanding.

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 configuration getter, the description is largely complete: it names the domain and distinguishes it from status, topology, and wireless configuration siblings. It lacks an output schema and explicit usage boundaries, but neither is critical for this simple tool.

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

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

The tool has zero parameters, so the baseline is 4 and the description is not required to explain parameter behavior. The parenthetical still adds useful semantic detail about what configuration domains the result covers, which helps an agent understand the tool's purpose.

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

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

The description names a specific action and resource: 'Get logical network configurations' and immediately clarifies the scope with concrete categories (VLANs, subnets, DHCP). This clearly distinguishes it from sibling tools like get_network_status, get_network_topology, and get_wlan_config.

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: this is the tool to use when retrieving logical network settings such as VLANs, subnets, or DHCP. It does not explicitly name alternatives or state when not to use it, so it falls just short of a perfect score.

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

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

With no annotations, the description must carry the behavioral burden, but it only says 'Get detailed health status' without explaining what subsystems are covered, whether the call is expensive or real-time, or what form the result takes. The read-only nature is implied by 'Get', but little else is disclosed.

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

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

A single, front-loaded sentence with no filler. It earns its place but uses the vague intensifier 'detailed' instead of naming the actual subsystems, so it could be more informative without growing much.

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 tool with no output schema and no annotations, the description is unusually thin: it omits the subsystem list and any relationship to sibling health/status tools. An agent cannot tell exactly what it will receive or when choosing it is appropriate.

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 there is no parameter to document. The description does not need to add parameter semantics, and the baseline for no-parameter tools is 4.

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

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

Description states a clear action (Get) and resource (detailed health status of network subsystems), so an agent can tell it is a read/health tool. However, it does not explicitly distinguish it from the similarly named get_network_status 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?

No guidance on when to prefer this tool over get_network_status, get_bandwidth_stats, get_alarms, or get_router_logs. The context is implied to be 'when you need health status', but no exclusions or alternatives are named.

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

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

With no annotations provided, the description must carry the behavioral burden. 'Get' implies a non-destructive read operation, but no detail is given about latency, side effects, prerequisites, or what the returned status contains. It is minimally transparent but not rich.

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

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

The description is a single concise sentence with no filler. It is appropriately sized for a zero-parameter getter and communicates the core purpose immediately.

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

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

The description is adequate for invoking the tool since no parameters are required, but it does not clarify what 'status' includes, what the response shape looks like, or how this differs from get_network_health. With no output schema, more explanatory context would help the agent 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?

The tool has zero parameters and schema coverage is 100%, so there are no parameter gaps. The description does not need to add parameter semantics, and the baseline for a zero-parameter tool is appropriate.

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

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

The description uses a clear verb and resource: 'Get overall network health and status' identifies the tool as a high-level read operation. However, it does not differentiate from the similarly named sibling get_network_health, so an agent may not know which one to choose.

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

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

No guidance is provided about when to use this tool versus alternatives such as get_network_health or get_bandwidth_stats. The agent is left to infer usage from the name and description.

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

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

No annotations are present, so the description bears full responsibility for behavioral disclosure. It mentions that the output is a 'simplified view of uplinks,' which gives a hint about scope, but it does not explicitly state that the operation is read-only, describe the return format, or note any rate limits or prerequisites.

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

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

The description is a single, tightly packed phrase with no filler or redundant words. It front-loads the action and object and is appropriately sized for such a simple, parameterless tool.

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

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

For a parameterless tool with no output schema and no annotations, the description is minimally viable: it tells the agent that the result is a simplified uplinks view. However, it lacks any details about the response shape or how this differs from related topology/status/config tools, so an agent might still be unsure when 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?

The input schema is empty with zero parameters, so there is nothing to explain beyond the schema itself. With zero parameters, the baseline of 4 is appropriate, and the description adds no parameter semantics because none 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 the specific verb 'Get' with the resource 'network topology' and the clarifier 'simplified view of uplinks,' which clearly states what the tool returns. It is distinct enough from siblings like get_network_status or list_devices, but it does not explicitly name or differentiate itself from those 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 provides no guidance on when to use this tool versus the many sibling tools. There are no scenarios, prerequisites, or exclusions mentioned, leaving the agent to infer usage solely from the name and one-line description.

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

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

Annotations are absent, so the description is the only behavior signal. The verb 'get' clearly implies a read-only, side-effect-free operation, and 'all configured' indicates a full list without filters. However, it does not disclose response format, pagination, permission requirements, or whether disabled rules are included.

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

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

A single, focused sentence with no filler. It front-loads the verb and resource, and includes the 'all' scope efficiently. Every word carries meaning.

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 list operation with no output schema, the description covers the essential purpose and scope. It could optionally mention response structure or error behavior, but the low complexity makes this adequate.

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

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

The schema is empty with zero parameters, so there is nothing for the description to add beyond the schema. The phrase 'all configured rules' usefully reinforces that no filters or parameters are required.

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

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

States a specific verb ('get'), resource ('port forwarding rules'), and scope ('all configured'). This clearly distinguishes it from sibling mutation tools like ensure/update/delete_port_forward_rule and from related read tools like get_firewall_rules and get_traffic_rules.

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 no when-to-use guidance or explicit alternatives. An agent cannot tell from the description alone when to choose this over get_firewall_rules or get_traffic_rules, nor are any exclusion conditions mentioned.

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

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

With no annotations provided, the description carries the full burden. 'Check' signals a read-only query, but there is no disclosure of return format, possible failure modes, or whether this reflects a global or per-client state. Still, for a zero-parameter status check, the basic behavior is adequately conveyed.

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 one focused sentence with no filler or redundant wording. The key subject, verb, and qualifier are all front-loaded.

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

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

The tool is simple: no inputs, no output schema, and a straightforward status question. The description is largely complete, though it could slightly clarify what 'Restricted devices' means and what the response looks like. These are minor gaps given the tool's simplicity.

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

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

The tool has no parameters, and the schema has no properties, so there is no parameter semantics gap for the description to fill. The 0-parameter baseline of 4 applies.

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

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

The description uses a specific verb ('Check') and identifies the exact resource and state ('if YouTube is currently blocked for Restricted devices'). It is immediately distinguishable from sibling tools like block_restricted_youtube and unblock_restricted_youtube.

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 this tool as a status-check rather than an action tool, which is the right context for use. It does not explicitly name alternatives, but sibling names block_restricted_youtube and unblock_restricted_youtube make the distinction evident.

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 present, so the description must carry the behavioral disclosure. It clearly indicates a read-only fetch over SSH, but it omits prerequisites like SSH availability/credentials and does not mention output size, pagination, or failure modes.

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

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

The description is a single, front-loaded sentence with no filler. Every word contributes to identifying the action, resource, and method.

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?

This is a simple tool with only two optional parameters fully documented in the schema. However, with no output schema and no annotations, the description leaves SSH prerequisites and the exact result format unaddressed; these gaps are noticeable but not critical for a basic log-fetching 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 both parameters already have meaningful descriptions. The tool description adds little beyond the word 'recent,' which only loosely relates to the lines parameter, so it does not substantially enhance 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 ('Fetch'), a specific resource ('recent system logs from the router'), and the transport ('via SSH'). This is clear and distinguishes it from generic siblings like run_ssh_command.

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

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

There is no explicit guidance on when to use this tool versus alternatives such as run_ssh_command or other network getters. The intended use is implied by the name and wording, but no exclusions or selection criteria are given.

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

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

No annotations are provided, so the description carries the full disclosure burden. It disambiguates the rule system and scope ('all', unfiltered), but it does not state whether the operation is strictly read-only, what the returned rule objects look like, or any ordering/pagination behavior. Risk is low for a list operation, but the burden was only partially met.

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

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

A single 15-word sentence with the core action front-loaded and the clarifying context in a parenthetical. Every word earns its place and there is zero 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 zero-parameter read-only list tool, the description covers what is returned and which rule system it belongs to, which is sufficient for correct invocation. The main gap is that with no output schema, the structure of each traffic rule is undocumented, which would hinder agents feeding results into update_traffic_rule or delete_traffic_rule.

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, which earns a baseline of 4. The description reinforces that there is no filtering by saying 'all traffic rules', which matches the empty schema exactly.

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

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

States a specific verb and resource ('List all traffic rules') with explicit scope ('all'). The parenthetical anchors the tool to ensure_traffic_rule and distinguishes it from siblings like get_firewall_rules and get_port_forward_rules, so an agent can pick the right rule-list tool 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?

Usage context is implied: naming ensure_traffic_rule suggests this is the read counterpart in a list-then-ensure/update/delete workflow. However, there is no explicit when-to-use guidance or exclusion of alternatives such as get_firewall_rules or get_port_forward_rules.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that the tool gets configurations, implying a read operation, but does not disclose return format, potential side effects, permission requirements, or any edge cases. The vague 'etc.' adds no behavioral clarity.

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

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

The description is a single short sentence that is front-loaded with the core action and resource. Every word contributes to identifying the tool's purpose, and no unnecessary filler is 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 zero-parameter tool the description is minimally adequate: the agent can invoke it without arguments and expect WiFi configuration data. However, there is no output schema and the description only vaguely hints at the return content with 'etc.', leaving the exact response structure unclear.

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 confirms this, so there is nothing to document. The baseline of 4 applies; the description's mention of SSIDs and security gives helpful context about what the returned configuration covers, though it doesn't add parameter-specific detail.

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

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

The description clearly identifies the tool as retrieving WiFi network configurations and gives concrete examples such as SSIDs and security settings. It distinguishes itself from the broader sibling 'get_network_config' through the specific 'WiFi' qualifier, though it does not explicitly name or contrast 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?

The description provides no guidance on when to use this tool versus alternatives like get_network_status or get_network_config. There are no stated conditions, exclusions, or references to sibling tools, so the agent must infer usage from the tool name alone.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, but it only repeats that the tool lists clients. It does not clarify what 'connected' means relative to the status parameter, mention that results are read-only, or indicate any filtering default beyond what the schema already says.

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

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

The description is a single, front-loaded sentence with no filler or repetition. Every word contributes to the basic purpose, making it easy to parse quickly.

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

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

For a tool with no annotations, no output schema, and many sibling tools, a one-line description is insufficient. It does not explain what information is returned, how 'clients' differ from 'devices', or when to choose this over search_network/list_devices, leaving important selection context unresolved.

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 'search' and 'status' are already documented in the input schema. The description adds no extra meaning about how these parameters interact with the 'connected' notion, so the baseline of 3 is appropriate.

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

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

The description uses a clear verb ('List') and identifies the resource ('network clients'), so an agent can grasp the basic operation. It does not distinguish 'clients' from the sibling 'list_devices', leaving some ambiguity about whether these are endpoint stations or infrastructure devices.

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

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

The description gives no guidance on when to use this tool versus closely related siblings such as list_devices, search_network, or get_client_details. It neither states a preferred context nor names alternatives, so an agent must guess from the tool name alone.

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

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

With no annotations, the description carries the full burden. 'List' conveys a read-only operation and 'all' conveys scope, but the description does not mention pagination, return format, default filtering behavior, or permissions. It is acceptable but minimal.

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

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

The description is a single efficient sentence with no filler. The core action, scope, and device categories are all front-loaded and immediately understandable.

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

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

For a simple list tool with two optional parameters, the description is mostly sufficient, but the absence of an output schema and absence of any usage guidance leaves some gaps. An agent still knows what the tool does, but not exactly what the response contains or when to prefer it over related tools.

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 both parameters are already documented by the schema. The parenthetical 'APs, switches, gateways' adds generic context for device types, but the schema already provides concrete examples like uap, ugw, and usw, so the description adds limited 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 action ('List') and the resource ('all network devices'), and gives concrete categories ('APs, switches, gateways'). It is easily distinguished from siblings like get_device_details, list_clients, and get_network_topology.

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 no guidance on when to use this tool versus alternatives such as search_network, get_device_details, or get_network_topology. The only implied usage is broad inventory listing, but no explicit context or exclusions are provided.

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

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

With no annotations provided, the description carries the behavioral burden. It discloses that this is a listing operation covering all clients and devices, and that the result includes counts and usage locations. It does not explicitly say 'read-only', but the verb 'List' strongly signals non-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?

One sentence, no filler, and the key content (what is listed and what each entry contains) is front-loaded. Every word earns its place.

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

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

This is a simple zero-parameter read tool with no output schema. The description fully specifies the resource scope and the information returned (tags, counts, and usage locations), so an agent has enough 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?

The tool has zero parameters, so there is nothing for the schema to describe. The description reinforces that the listing is unfiltered ('all tags'), which is the only parameter-related meaning an agent needs.

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

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

The description states a specific verb ('List'), a distinct resource ('tags currently applied to clients and devices'), and the output shape ('with counts and where they are used'). This clearly distinguishes the tool from siblings like list_devices, list_clients, and set_device_tags.

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 conveys clear read-only inspection context for tag usage across clients and devices. It does not explicitly name an alternative such as set_device_tags for modifying tags, but the read-vs-write separation is strongly implied by the wording.

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

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

With no annotations, the description carries the safety burden. The verb 'List' and the qualifier 'existing' communicate a non-mutating operation, and the description discloses the output fields returned. It does not mention pagination or rate limits, but those are less critical for a simple list operation.

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

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

One sentence, front-loaded action, and every phrase carries meaning: the operation, the object, and the relevant return content. No filler or repetition.

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

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

For a parameterless list tool with no output schema, the description is complete enough: it tells the agent what the call returns and implies a read-only, all-groups result. 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?

The tool takes zero parameters and the schema is empty, so there is nothing for the description to clarify. The baseline for no parameters is 4, and the description appropriately adds output semantics instead.

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 (List) and resource (existing user groups), plus the key result fields. This is enough to distinguish it from mutation siblings like create_user_group and set_client_user_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 intended use is implied by 'List existing user groups,' but the description does not explicitly say when to prefer this over alternatives or provide exclusions. For a no-parameter read tool, the lack of guidance is a minor gap.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but does not disclose side effects, duration, reversibility, or that the 'enable' parameter can turn flashing off. The behavior is minimal and somewhat self-evident, but important operational details are missing.

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

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

The description is a single concise sentence with no filler. It front-loads the action and purpose immediately, making it easy for an agent to parse quickly.

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

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

The tool is simple and the schema covers invocation details, but there is no output schema and the description does not mention what happens after the call, such as whether it returns success/failure or how long the LED flashes. It is adequate but has clear gaps around behavior and return semantics.

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 adds no additional meaning about 'mac' or 'enable', so the baseline score of 3 applies.

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

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

The description uses a specific verb ('Flash the LED') and names the exact resource ('a device'), making the tool's function unambiguous. It clearly distinguishes this from the many read-only information siblings like get_device_details or list_devices.

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

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

The phrase 'to locate it' gives a clear use case: physically finding a device by flashing its LED. It does not explicitly mention alternatives or exclusions, but the context is clear enough for an agent to know when this tool is appropriate.

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

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

With no annotations provided, the description carries the full disclosure burden. It earns credit for the word 'Propose,' which tells the agent the tool does not unconditionally execute a migration and aligns with the dryRun default of true. However, it fails to disclose what actually happens when dryRun=false — whether devices are disconnected, network settings change, or the migration is reversible — which is significant for a potentially disruptive network operation.

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

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

The description is a single 11-word sentence with the core action front-loaded before the object and destination. Every word contributes meaning, and nothing is redundant with the schema. This is appropriately concise and well structured.

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

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

Although the tool has only two parameters, it is a mutation-capable tool with no annotations, no output schema, and no return-value description. The description omits prerequisites (e.g., running detect_iot_devices first), the effects of an actual migration, and what the tool returns. For an operation that can alter network state, this is too thin to be fully actionable.

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, justifying the baseline of 3. The description's 'target network' mirrors the targetNetworkId parameter and 'Propose' aligns with the dryRun default, but neither adds new semantic detail beyond what the input 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 action ('Propose migration') on a specific resource ('detected IoT devices') with a clear destination ('target network'). The verb distinguishes it from the sibling tools detect_iot_devices and enforce_iot_limits without needing to read their schemas. However, the word 'Propose' introduces a slight ambiguity about whether the tool actually performs the migration or only plans it.

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 offers no guidance on when to use this tool versus its siblings. It does not mention that detection should happen first via detect_iot_devices, nor does it distinguish its role from enforce_iot_limits. An agent is left to infer usage entirely from the tool name and the description's verb.

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 simply states a desired outcome without mentioning side effects, whether the operation mutates configuration, idempotency, permissions, or what happens when invoked. The mutation-like nature of 'ensure' is implied but not explicitly disclosed.

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

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

The description is a single sentence with no wasteful words, which is appropriately concise for a one-parameter tool. However, it is not front-loaded with the most useful operational detail (the action itself), and 'ensure' is vague enough that the sentence could be more informative without additional length.

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 annotations, no output schema, and a parameter that is not explained in context, the description is incomplete. It gives no indication of return values, side effects, or what configuring defaultGroupId actually does to throttling behavior. An agent cannot fully predict the consequences of invoking this 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% for the single parameter, so the schema already documents defaultGroupId as 'Default user group ID for VIPs'. The description adds a slight connection to the purpose but does not provide additional semantic detail beyond the schema 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 'Ensure VIP devices are not throttled' clearly identifies the resource (VIP devices) and the intended outcome (not throttled), which distinguishes it from sibling tools like get_network_status or block_client. However, it does not specify the actual operation performed, leaving 'ensure' somewhat vague about whether this is a configuration action or a policy check.

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

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

There is no guidance about when to use this tool versus alternatives such as set_client_user_group, ensure_traffic_rule, or enforce_iot_limits. The description does not state prerequisites, conditions, or situations where this tool should be preferred, so the agent must infer usage from the name and parameter.

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

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

No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states the action 'Restart' and does not mention that a reboot interrupts connectivity, requires the device to be reachable, or what happens to existing sessions.

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

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

The description is a single short sentence with no filler or redundant phrasing. It is front-loaded with the action and resource, making it easy to parse quickly.

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

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

While the schema covers the parameter, there is no output schema, no annotations, and no note about side effects or post-conditions. For a disruptive action like restarting a device, the description is too sparse to fully inform an agent about expected behavior and potential impact.

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

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

The input schema fully documents the only parameter `mac` with the description 'MAC address of the device to restart'. The tool description adds nothing beyond the schema, so it meets the baseline but does not improve parameter understanding.

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

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

The description 'Restart a Unifi device' clearly states a specific action and resource, so an agent knows exactly what the tool does. It does not explicitly differentiate from siblings like cycle_poe_port or locate_device, but 'restart' itself 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?

There is no guidance on when to use this tool versus alternatives, such as when a device is unresponsive or after configuration changes. No exclusions, prerequisites, or preferred contexts are mentioned, leaving the agent to infer usage.

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

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

With no annotations, the description must carry the behavioral burden. 'Force a client to reconnect' conveys that the action actively drops and re-establishes the client session, which is the core side effect. It does not explicitly warn about temporary disconnection or how offline clients are handled, leaving some transparency implicit.

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

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

The entire definition is one short sentence with no filler or duplicated schema content. It leads with the action, then adds the roaming use case in a compact parenthetical.

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-parameter, low-complexity action, the core inputs and purpose are covered. A brief note on expected impact, such as the client temporarily disconnecting, would make it more complete, but no critical invocation detail 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 schema already documents 'mac' as the MAC address of the client to reconnect with 100% coverage. The description introduces no additional syntax, validation, or semantic detail for the parameter. Baseline 3 applies because the schema handles the parameter documentation burden.

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

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

The description opens with the imperative 'Force a client to reconnect', naming a specific verb and resource. It is distinguishable from sibling device-level actions like reboot_device and cycle_poe_port because it targets the client's network session. The parenthetical 'useful for roaming' adds a concrete purpose.

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

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

'Useful for roaming' provides a clear context in which the tool should be used, signaling the agent to reach for it when a client is not roaming correctly. It does not name alternatives or state when not to use it, so it falls slightly 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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals the transport (SSH) but not that arbitrary commands can have destructive side effects (e.g., a command like 'reboot' or config-wiping commands), what privileges the SSH session holds, or how output is returned. This is a significant gap for a tool that can run anything.

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

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

One sentence, zero filler — 'Execute a command directly on the router via SSH' is efficient and front-loaded with the action and target. It is genuinely concise rather than under-specified; the terseness costs behavioral depth, but that is penalized in other dimensions.

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 mechanical call is clear: one required parameter, fully documented. However, this is arguably the highest-risk tool in the catalog — raw command execution on a router — and the description omits safety context, privilege disclosure, and any note about output handling. With no annotations and no output schema, the description needed to compensate and did not.

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 concrete examples ('top -n 1, info, dmesg'), so the schema already documents the parameter adequately. The description adds the SSH execution context but no parameter-level detail beyond the schema. Baseline 3 applies 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 states a specific verb (execute), a resource (the router), and a transport method (SSH). The word 'directly' signals raw shell access, which clearly separates it from the structured get_*/set_* siblings. It doesn't explicitly contrast with a named sibling, but the SSH/direct phrasing makes the distinction apparent.

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

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

No guidance on when to use this tool versus the 50+ structured sibling tools, no exclusions, and no prerequisites. It is implied that this covers arbitrary commands not exposed by the API, but an agent is left to infer that entirely. For a raw-execution tool sitting among many high-level operations, explicit routing guidance is missing.

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 present, so the description carries the full burden of behavioral disclosure. It only states the search scope and keys, omitting output format, match semantics (exact vs partial), no-match behavior, and any potential side effects. It is not misleading, but it is minimal.

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

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

A single sentence with no filler words; the verb and key details are front-loaded. Every word earns its place.

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

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

The tool is simple (one required parameter, no output schema), so the description is adequate for basic invocation. However, with no annotations or output schema, the description should clarify return values and query behavior. The alias mismatch is an additional gap.

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

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

Schema description coverage is 100% for the single query parameter. The tool description adds 'alias' and the 'devices or clients' scope beyond the schema, but this slightly conflicts with the parameter description, which omits alias. The added meaning is marginal yet acceptable.

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 ('Search') and resource ('devices or clients') and names the search keys (IP, MAC, hostname, or alias). This clearly distinguishes it from sibling listing tools like list_devices and list_clients, though it does not explicitly contrast 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?

There is no guidance on when to use this tool versus alternatives such as list_devices, list_clients, or get_device_details. No when-not conditions or alternative tool names are provided; usage must be inferred from the search verb alone.

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

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

No annotations are provided, so the description carries the full behavioral burden. It adds one genuinely useful behavioral detail — that this field overrides hostname — but does not disclose what happens to an existing alias, whether the MAC must exist, idempotency, or permission requirements. It exceeds a bare statement of mutation but does not fully compensate for the missing annotations.

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

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

Two sentences with zero filler. The first sentence front-loads the action and target; the second adds the essential semantic clarification. Every word earns its place.

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

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

For a simple two-parameter setter with no output schema, the description covers what it does, how it identifies the client, and the field's behavioral effect. It could optionally mention that it replaces any existing alias or note error behavior when the MAC is unknown, but these are minor gaps for a tool of this complexity.

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

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

Schema description coverage is 100%, so the schema already documents both parameters adequately. The description adds marginal value by explaining that 'name' is the UniFi name field with hostname-overriding behavior, which enriches the name parameter's meaning, but it does not add format, constraints, or selection guidance 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 ('Set the friendly name (alias) on a client by MAC') and clarifies the semantic distinction from the hostname. This clearly differentiates it from siblings like set_client_note and set_client_user_group without needing to inspect 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 context for when to use this tool is implied via the field semantics ('overrides hostname'), which hints at the display-naming use case. However, there is no explicit when-to-use guidance, no exclusions, and no routing to closely related siblings like set_client_note or set_client_user_group.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently signals a write operation but says nothing about permission requirements, behavior on an unknown MAC, persistence, side effects, or that a new note overwrites prior text — the clearing behavior appears only in the schema, not the description. For a mutation tool with zero annotation coverage, this is a significant gap.

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

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

A single 15-word sentence that front-loads the verb and resource with zero waste. Every phrase ('freeform', 'by MAC') carries semantic weight, and nothing is repeated from 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?

The tool is simple (2 flat parameters, no output schema) and the schema fully documents the arguments, so an agent can invoke it correctly from the description alone. However, there is no guidance on post-conditions (e.g., the note being readable via get_client_details), failure behavior, or how this setter relates to the many other set_client_* and client-state tools, leaving completeness adequate but not rich.

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 both parameters are already fully documented. The description adds marginal value — 'freeform' clarifies the note is arbitrary text and 'by MAC' confirms the lookup key for the mac parameter — but the schema's 'use empty string to clear' is the more operationally useful detail. The baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb ('Set'), the exact mutated resource ('the freeform note field on a client'), and the addressing method ('by MAC'). It is immediately distinguishable from client-related siblings such as set_client_alias, set_client_user_group, block_client, and get_client_details, which target different attributes or behaviors.

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

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

No explicit when-to-use, when-not-to-use, or alternative tools are named. The intended trigger (attaching freeform text to a client record) is inferable from the resource wording and the sibling set, but the description leaves routing entirely to implication and never contrasts this with set_client_alias for labeling or get_client_details for reading.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It reveals the purpose (throttling) but omits important side effects: whether this overwrites an existing group assignment, whether it requires the group and client to exist, or what happens to prior throttling settings. This is a nontrivial mutating operation and the behavioral transparency is limited.

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

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

The description is a single, focused sentence that front-loads the core action and appends a useful purposive qualifier. There is no redundant wording or unnecessary detail.

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

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

Given the low complexity (2 simple params, full schema coverage, no output schema), the description is adequate but not complete. It lacks details such as whether the user group must pre-exist, whether the assignment replaces any existing group, and what the result or confirmation is. These gaps could leave an agent uncertain about calling the tool correctly.

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

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

Schema description coverage is 100%, so the baseline is 3. The description does not add any meaning beyond the schema, except implicitly indicating that the group_id refers to a throttling group. Since the schema already documents client_id and group_id clearly, the description adds no substantial parameter-level 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 uses a specific verb and resource: 'Assign a client to a specific user group'. It clearly states the operation and target, and the parenthetical '(for throttling)' adds relevant context that distinguishes this from other client-management tools like set_client_alias or block_client.

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

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

The context '(for throttling)' implicitly suggests this tool is for applying throttling policy via a user group, but it does not explicitly state when to use it versus alternatives such as create_user_group or list_user_groups. No when-not conditions or alternative routing is provided.

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

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

With no annotations provided, the description carries the full transparency burden, and it delivers on the two most dangerous behaviors: the operation is a full replacement ('Replaces all existing tags') rather than additive, and target resolution is automatic ('Auto-detects client vs device by MAC'). It does not cover failure modes, permission requirements, or response behavior, but the essential mutation semantics are disclosed.

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

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

Three short sentences, zero filler. Each sentence earns its place: the action, the critical replacement caveat, and the auto-detection behavior. Front-loaded with the core operation before the caveats.

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

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

For a low-complexity flat 3-parameter tool, the description plus fully-covered schema specify everything needed to call it correctly. The main gaps are no mention of error behavior when auto-detection fails (despite the `target` param existing for that case) and no output information, though no output schema exists to lean on. Still, the essential semantics are all 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%, so the baseline is 3. The description's 'Auto-detects client vs device by MAC' adds modest insight into how the `target` parameter's default 'auto' behaves, but the replacement note merely restates what the schema already says for `tags`. The schema does the heavy lifting here.

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

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

The description names a specific verb ('Set'), a precise resource ('the tags array'), and a targeting mechanism ('by MAC', 'client or device'). It is immediately distinguishable from siblings like set_client_alias, set_client_note, and list_device_tags because the resource being mutated is explicit.

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 use case is clearly conveyed: this is the tool for setting tags on a client or device. The second sentence ('Replaces all existing tags') gives implicit when-not guidance — if the caller wants to preserve existing tags, this is the wrong tool. However, it does not explicitly route to a read counterpart like list_device_tags or discuss when the `target` override should be used.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure, and it only restates the operation ('unblock' = undo a block). It doesn't disclose side effects, whether the device regains connectivity automatically, error behavior for an already-unblocked client, or permission requirements.

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?

Seven words, zero waste, and the core action is front-loaded. Every element ('Unblock', 'previously blocked', 'client device') earns its place, though the brevity does leave behavioral gaps that are accounted for elsewhere in the score.

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-parameter tool with no output schema or annotations, the description covers the core operation adequately. However, it leaves unspecified what the call returns on success, what happens for a client that isn't blocked, and how this interacts with block_client — minor gaps, but gaps nonetheless for a mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents the mac parameter fully ('MAC address of the client to unblock'). The description adds no parameter-level detail beyond that, which puts it at the baseline for high 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 names a specific verb ('Unblock') and resource ('client device'), and the qualifier 'previously blocked' ties it to the inverse of block_client. It's unambiguous about what the tool does, though it doesn't explicitly name siblings like block_client or reconnect_client to draw the distinction.

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

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

No guidance is given on when to use this tool versus alternatives. 'Previously blocked' implies a precondition, but the description never states that this is the inverse of block_client, nor does it distinguish unblocking a device from reconnect_client or unblock_restricted_youtube.

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 does disclose that the action is global ('all Restricted devices'), which is useful, but it says nothing about whether the change is persistent, whether it is reversible via block_restricted_youtube, whether it requires admin privileges, or what the resulting network state looks like. For a state-changing operation with zero annotation coverage, this is a significant gap.

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

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

A single sentence with zero filler words. The action, target, and scope are all front-loaded, and no sentence could be removed without losing 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?

Adequate for a parameterless action: the agent knows what to invoke and that it takes no arguments. However, with no annotations and no output schema, the agent is left guessing about the return value, side effects, and whether any preconditions apply (e.g., YouTube must currently be blocked). The core invocation is covered, but the surrounding behavior is not.

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

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

The input schema has zero parameters, so there is nothing for the description to add beyond the schema; per the rubric, 0 params earns a baseline of 4. The description's wording implies a parameterless, network-wide action, consistent with the empty schema.

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

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

States a specific verb ('Unblock'), a resource ('YouTube'), and a scope ('all Restricted devices'). It is immediately distinguishable from the inverse sibling block_restricted_youtube and the status-check sibling get_restricted_youtube_status without needing to open any schema. 'Restricted' reads as a device group concept in this system, making the target population 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?

No explicit when/when-not guidance is given; the sibling alternatives (block_restricted_youtube, get_restricted_youtube_status) are never referenced. Usage is only implied by the binary semantics: call this when YouTube is blocked for Restricted devices and needs re-enabling. The context is inferable but nothing is spelled out.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal the key PATCH behavior ('Pass any subset of fields to patch'), which is valuable and beyond the tool name's implication of a full update. However, it does not disclose what happens when the id is not found, whether it returns the updated rule, or any side effects. This is partial disclosure, not complete.

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

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

The description is two short sentences with zero fluff. The primary action is front-loaded ('Update an existing port forwarding rule by id'), and the essential patching behavior is stated in the second sentence. Every word earns its place.

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

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

The description is not complete enough for a mutating tool without an output schema. It fails to explain the return value or error behavior (e.g., what happens if the id does not exist). It also does not relate itself to sibling tools such as ensure_port_forward_rule or get_port_forward_rules, leaving the agent without guidance on prerequisites or fallback paths. Several relevant contextual details are 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 fully documents both parameters. The description adds 'by id' and 'subset of fields to patch', which mildly reinforces the payload's 'Partial rule fields to update' but does not introduce new semantic meaning. Baseline 3 is appropriate.

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

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

The description clearly states 'Update an existing port forwarding rule by id' – a specific verb ('Update'), a specific resource ('port forwarding rule'), and a specific identifier method ('by id'). It also says 'Pass any subset of fields to patch', which differentiates it from sibling tools like get_port_forward_rules, ensure_port_forward_rule, and delete_port_forward_rule. An agent can confidently know what this tool does without ambiguity.

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

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

The description implies usage context: it is for modifying an already-existing rule ('existing') by id with partial fields. However, it does not explicitly state when to prefer this over alternatives such as ensure_port_forward_rule (which likely creates or updates) or when not to use it. The guidance is implied rather than explicit, so it earns a mid-range score.

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 burden. It discloses that this is a partial patch rather than a full replacement, which is a useful behavioral trait. It omits failure behavior and permission requirements, but the simple mutation semantics are reasonably clear.

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

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

Two short sentences, front-loaded with the verb and object, and no filler or redundant context. Every word earns its place.

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

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

For a two-parameter update with no output schema, this is largely complete: an agent can determine the required id and partial payload shape. It could mention error behavior or whether the rule must exist, but the core invocation needs are covered.

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 already explains id and payload in detail, including example field names. The description's 'Pass any subset of fields to patch' only reinforces the schema without adding new parameter-level insight.

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

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

Clearly identifies the action (update), resource (traffic rule), and key discriminator (by id). Distinguishes from get/delete siblings, though not from ensure_traffic_rule.

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

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

Gives a clear patch convention: pass any subset of fields. Does not explicitly contrast with ensure_traffic_rule or state prerequisites, but 'existing traffic rule' implies the primary use case.

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