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

The annotation already marks the operation as destructive, so the description does not need to repeat that warning. The description clarifies that the action moves a pending device into a site, but it does not disclose additional consequences such as provisioning side effects or reversibility; the annotation carries most of the safety burden.

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. Every word contributes to identifying the action, object, key, and destination.

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, but the description omits the significance of the optional siteId and the expected MAC address format. The destructive annotation and schema cover the rest, so the definition is minimally complete but has a clear gap around site-selection behavior.

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

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

With zero schema description coverage, the description partially compensates by mapping 'MAC address' to deviceMac and 'site' to siteId. However, it does not explain that siteId is optional or what happens when it is omitted, leaving ambiguity about site targeting.

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 ('adopt'), the object ('pending device'), the identifying key ('MAC address'), and the destination ('into the site'). This clearly distinguishes it from the many read/list/update siblings, since no other tool covers adoption.

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 'pending device' gives clear context for when this tool should be used: for devices that have not yet been adopted, not for already-managed devices. It does not explicitly name alternatives or exclusions, but the pending-device scope provides sufficient usage guidance.

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

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

The destructiveHint annotation already flags this as a destructive operation, but the description adds no behavioral context beyond that. It does not disclose that existing port names will be overwritten, how partial failures are handled, or whether the batch is atomic. With the annotation covering the safety profile, some credit is given, but the description itself contributes no additional transparency.

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

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

The description is two concise sentences with no filler. The core operation and constraints are front-loaded, and the entry structure is stated efficiently. Every sentence contributes to understanding the 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 relatively simple batch mutation tool, the description plus schema and destructiveHint cover the essential invocation details: target switch, list of port/name pairs, and mutation safety. However, it lacks guidance on overwrite semantics, success/failure behavior, and when the optional siteId is needed, so it is adequate but not complete.

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

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

Schema description coverage is 0%, so the description must compensate. It does mention that each entry contains a port number and a name (with length constraint), which partially maps to portNameList. However, it completely omits switchMac and siteId, and the only added semantic beyond the schema is the phrase 'port number'. This is insufficient for full 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 states a specific verb ('set names'), the resource ('switch ports'), and the batching scope ('multiple switch ports'). The 'Batch' qualifier distinguishes it from the singular sibling setSwitchPortName, while 'names' separates it from batch operations on profiles, status, and PoE.

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 is implied: use this tool when you need to set names on multiple ports at once. However, it does not explicitly say when not to use it or point to the singular alternative setSwitchPortName for single-port changes, so the guidance remains implicit rather than explicit.

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

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

The destructiveHint annotation already signals that this changes device state. The description adds the scope of the operation (multiple ports) and the PoE mode semantics, but does not disclose consequences such as power loss to connected devices or any prerequisites. With annotations present, this is acceptable but not expansive.

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 phrase earns its place: the action, the object, the scope, and the mode semantics.

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

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

For a batch mutation of switch ports, the description covers the core intent and required poeMode values, but leaves the roles of switchMac, portList, and siteId to be inferred from names or schema. Without an output schema, the response behavior is also undisclosed, making the description adequate but incomplete.

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 only 25%, with most parameters undocumented. The description repeats the poeMode mapping already present in the schema and adds no new meaning for switchMac, portList, or siteId. Given the low coverage, the description should compensate but does not.

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 action: batch enable/disable PoE on multiple switch ports, with an explicit on/off mapping. It also distinguishes itself from the singular sibling setSwitchPortPoe through the 'Batch' and 'multiple' qualifiers.

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 word 'Batch' plus 'multiple switch ports' clearly signals when this tool is appropriate, and the key sibling setSwitchPortPoe would be for single-port changes. It does not explicitly name the alternative or provide a when-not-to-use condition, so it stops just short of a 5.

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

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

The destructiveHint annotation already signals mutation, but the description adds no behavioral context beyond what the annotation and schema parameter profileOverrideEnable already convey. It does not explain consequences such as whether disabling the override reverts ports to their previous profile or whether the operation is idempotent.

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 compact sentence with the action and object front-loaded. It has no redundant wording, but the brevity sacrifices useful detail that the agent needs for correct invocation.

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 mutating batch operation with destructiveHint and no output schema, yet the description only restates the basic purpose. It fails to explain the roles of three of four parameters or what the result of disabling an override means, making it incomplete for reliable autonomous use.

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 only 25%, with profileOverrideEnable being the only described parameter. The tool description also only references the override concept and does not explain switchMac, portList, or siteId, leaving most parameters under-documented for an agent.

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 ('Batch enable or disable'), the target resource ('profile override'), and the scope ('multiple switch ports'). The word 'Batch' also helps distinguish it from single-port sibling tools like setSwitchPortProfileOverride.

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 'Batch...multiple switch ports' implies this tool is for applying the override setting to several ports at once, but it does not explicitly mention when not to use it or name the single-port alternative. The usage guidance is implied rather than stated.

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

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

Annotations already provide destructiveHint=true, so the description need not restate destructiveness. It adds the specific state change (enable/disable) but does not disclose side effects such as immediate loss of connectivity on disabled ports, idempotency, or behavior when applied to already-matching ports. Given the annotation covers the core trait, the description adds minimal but acceptable 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?

Two short sentences with no filler; the action and resource are front-loaded and the status mapping is stated crisply. Every word earns its keep.

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

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

For a destructive batch mutation with no output schema, the description gives the core semantics but omits guidance on when to choose it over singular alternatives, the role of optional siteId, and expected return or error behavior. Adequate for a straightforward operation but leaves several gaps an agent might encounter.

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 only 25%, covering just 'status'. The description repeats '0=off, 1=on' but adds no meaning for switchMac, portList, or siteId. With low schema coverage, the description fails to compensate by explaining how these parameters interact or what format they should take.

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 ('enable or disable'), a clear resource ('switch ports'), and a batch scope ('multiple'), which distinguishes it from singular setSwitchPortStatus and sibling batch operations. It also encodes the status mapping (0=off, 1=on) directly, leaving no ambiguity about the operation's 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?

The word 'Batch' implies this should be used when multiple ports need status changes, but the description does not explicitly mention when to prefer it over singular setSwitchPortStatus or other batch tools like batchSetSwitchPortPoe/Name/Profile. No exclusions or alternatives are named, so usage guidance is only implied.

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

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

Annotations already mark the tool as destructive, and the description adds the meaningful behavioral consequence of denying network access. However, it does not disclose details such as whether blocking disconnects an active session, whether it is reversible, or whether siteId is required for multi-site environments. The description is consistent with destructiveHint but leaves some behavioral ambiguity.

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 that front-loads the verb and resource, then gives the mechanism and effect. No filler or redundant restatement; every part contributes useful information.

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

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

For a simple blocking action, the description covers the core operating intent and the required parameter's meaning. Still, it omits the role of siteId, does not mention that unblockClient is the inverse operation, and gives no indication of what happens to an already-connected device. These gaps matter for a destructive tool with no output schema.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that clientMac is a MAC address, but it says nothing about siteId, leaving an optional-but-unexplained parameter. An agent would not know whether siteId scopes the operation or is needed in certain deployments.

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 uses a specific verb ('Block') with a clear resource ('a client device'), the exact identifier ('MAC address'), and the consequence ('preventing it from accessing the network'). It is immediately distinguishable from siblings like unblockClient, updateClient, and listClients.

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

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

The description states the action but gives no guidance on when to choose this over alternatives. It does not mention unblockClient as the inverse, nor does it describe prerequisites or situations where blocking might be inappropriate. The usage context is only implied by the tool name and ordinary meaning of 'block'.

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 destructiveHint=true annotation already flags that this tool modifies state, and the description does not contradict it. The description adds purpose context but does not disclose potential traffic disruption or other side effects of creating the ACL rule; with the annotation present, this is acceptable but not additive.

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

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

Two sentences with no filler; the primary purpose is front-loaded and the second sentence supplies actionable setup guidance. 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 covers the core rule-construction need via the listFirewallAcls pointer and identifies the tool's purpose. However, it leaves the optional siteId parameter unexplained, does not state what happens when siteId is omitted, and provides no hint about the return value or confirmation behavior for a create operation with nested objects.

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 only 50%: `rule` has a schema description but `siteId` does not. The description helps by directing the agent to listFirewallAcls for the expected rule shape, compensating for the free-form `rule` object, but it fails to explain the meaning or effect of `siteId`.

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

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

States a specific action and resource ('Create a firewall ACL rule') plus its intended use ('inter-VLAN isolation or traffic control'). This distinguishes it from sibling tools like listFirewallAcls and deleteFirewallAcl without needing to open their schemas.

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

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

Explicitly directs the agent to call listFirewallAcls first to learn the expected rule shape, which is clear contextual guidance. It does not spell out exclusions or when to prefer other firewall tools, but the create-vs-read/delete contrast is evident from the sibling names.

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

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

Annotations include destructiveHint=true, so the bar is lower, but the description adds no behavioral context beyond the action. It does not mention potential side effects such as network disruption, irreversibility, or any requirement for an existing site, and it neither contradicts nor elaborates on the destructive hint.

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 that puts the action and resource first and lists key fields with no filler. Every word earns its place, and the structure is immediately scannable.

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

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

For a tool with 7 parameters, one required nested object, no output schema, and a destructiveHint, the description is under-specified. It does not mention what the tool returns, whether siteId is required for a valid call, or what side effects may occur, leaving an agent dependent entirely on the schema.

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

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

The description highlights VLAN, gateway/subnet, and DHCP settings, giving a rough sense of the primary parameters. However, with 71% schema coverage, most fields are already described in the schema, and the description adds no new detail and omits purpose, igmpSnoopEnable, and siteId.

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 ('Create') and resource ('LAN network'), and lists the core configuration aspects (VLAN, gateway/subnet, DHCP settings). This clearly differentiates it from sibling tools like updateLanNetwork, deleteLanNetwork, and createLanProfile.

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 'Create a new LAN network' implies the tool is for creation, but there is no explicit guidance on when to use it versus alternatives like updateLanNetwork or deleteLanNetwork, and no prerequisites are mentioned. The intended use case is clear but not contrasted with related tools.

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

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

The annotations include destructiveHint: true, but the description adds no behavioral context beyond that. It does not explain potential side effects on switch ports, whether creating a profile affects existing devices, or what happens if a profile with the same name exists.

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

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

The description is a single, front-loaded sentence with no filler words. It efficiently conveys the core purpose without 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?

With 9 parameters, 8 required, no output schema, and a destructive hint, the description is too thin. It does not explain what a LAN profile is used for, the role of siteId, constraints on network assignments, or what the result of the operation is.

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 78%, so most parameters already have meaningful descriptions. The description adds only a high-level grouping ('native/tagged network assignments and port settings') without explaining parameters beyond what the schema provides.

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

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

The description states a specific verb and resource: 'Create a new LAN profile' with details on network assignments and port settings. This clearly distinguishes it from siblings like createLanNetwork and updateLanProfile by naming the exact resource type and 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?

No guidance is given on when to use this tool versus alternatives like createLanNetwork, updateLanProfile, or setSwitchPortProfile. The description only says what the tool does, not when it is the appropriate choice.

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

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

With no annotations, the description carries the full behavioral burden and does so well. It discloses the destructive side effect (hard PoE power cut, collateral port drops, including PoE-powered controllers) and the authentication requirement, which are exactly the non-obvious traits an agent needs.

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

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

Two efficient sentences front-load the purpose, then add the high-value safety warning and credential requirement. No filler, no repetition, and every sentence earns its place.

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

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

For a mutating creation tool with no annotations, no output schema, and a nested free-form data object, the description leaves critical gaps: it never mentions siteId, does not specify what fields data should contain beyond a time-range-to-port binding, and says nothing about response behavior. An agent would still have to guess at the request shape.

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 data parameter gains meaning beyond the schema: it binds a time-range profile to switch ports and points to listTimeRanges. However, siteId is completely undocumented in both schema and description, and data's additionalProperties are unconstrained, so parameter semantics are only partially enriched.

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 the action 'Create' and object 'PoE schedule' clearly and immediately. It also distinguishes the tool from createRebootSchedule by warning to prefer a reboot schedule on Omada-managed devices, and from update/delete/list siblings by the create verb.

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

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

Explicitly tells the agent to prefer createRebootSchedule when the target is an Omada-managed device and explains why: PoE is a hard power cut and drops anything else sharing the port. It also names the required credentials, giving a clear precondition for calling the 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?

With no annotations provided, the description carries the full disclosure burden. It adds genuinely useful behavioral context: times are interpreted in the site timezone and specific credentials are required. However, it omits significant operational consequences — that this schedules actual device reboots that will disrupt connected clients, and that the schedule is enabled by default. Meaningful context, but not a complete behavioral picture.

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

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

Three sentences with zero filler: purpose first, then the value proposition, then two actionable caveats (timezone verification and credentials). Every sentence earns its place and the most decision-relevant information is front-loaded.

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

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

For a 10-parameter tool with conditional logic (dayOfWeek required when timingType=2, dayOfMonth when timingType=3) and no output schema, the description covers the core flow well but leaves gaps. It doesn't explain that the schedule triggers real device reboots affecting clients, nor clarify the role of siteId. The schema partially covers the conditional timing logic, which keeps this from scoring lower.

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 description adds real value beyond the schema by clarifying that time parameters are interpreted in the site timezone, which affects hour/minute/dayOfWeek semantics. The 'targeting specific devices' phrase maps to deviceMacs. However, with schema coverage around 60%, parameters like name, siteId, and monthOfYear remain undocumented in both schema and description, so the description only partially compensates for the coverage gap.

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-resource pair ('Create a reboot schedule') plus a scope qualifier ('targeting specific devices'), making the tool's function immediately identifiable. The create verb cleanly distinguishes it from sibling tools listRebootSchedules, updateRebootSchedule, and deleteRebootSchedule without needing to open any schemas.

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

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

The description provides a concrete when-to-use rationale ('capping the memory creep that makes access points degrade over long uptimes') and names a prerequisite step ('verify that first with getSiteSettings'), which is explicit cross-tool guidance. It stops short of explicitly naming alternatives or exclusion conditions, but the context it gives is enough for an agent to decide when this tool applies.

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 destructiveHint annotation already covers the safety profile, and the description confirms that the object destroyed is a firewall ACL rule. It adds no further behavioral detail such as irreversibility, immediate enforcement, or whether siteId matters, but it does not contradict the annotation.

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

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

A single, front-loaded, unambiguous sentence with no filler. Every word contributes to the 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 simple deletion with a destructiveHint annotation and no output schema, the core invocation is adequately covered. The unexplained optional siteId and the absence of any note about permanence or side effects are minor gaps, so it falls just short of fully complete.

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

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

Schema description coverage is 0%, so the description carries the burden. It clarifies that the required aclId is the firewall ACL rule's ID. However, it does not explain the optional siteId parameter at all, leaving a partial gap in 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 uses a specific verb ('Delete'), a clear resource ('firewall ACL rule'), and the selection criterion 'by its ID'. This leaves no doubt about the operation and differentiates it from sibling tools like listFirewallAcls and createFirewallAcl.

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 tool name and description clearly frame it as the deletion operation for firewall ACL rules, so the intended context is obvious. It does not explicitly mention how to obtain the ID (e.g., via listFirewallAcls) or state exclusions, but no competing deletion tool exists for this specific resource.

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 destructiveHint=true annotation already tells the agent the operation is destructive, and the description adds no further behavioral context — no cascading effects on attached devices or profiles, no irreversibility statement, no prerequisite conditions. The description is consistent with the annotation but contributes nothing beyond it.

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

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

Single sentence with no filler: the verb, object, and lookup key are front-loaded and every word earns its place. This is appropriately sized for the information it conveys.

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

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

For a destructive two-parameter tool with 0% schema coverage and no output schema, the description is incomplete: an agent cannot tell what siteId is for, whether deletion cascades to devices, or what response to expect. A single sentence may suffice for a list tool, not for a mutation with an under-documented parameter set.

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; it clarifies that networkId is the lookup key ('by its network ID') but leaves siteId entirely unexplained — its role, optionality, and relationship to networkId are ambiguous. A destructive call with two weakly documented parameters needs more.

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 combines a specific verb ('Delete'), a clear resource ('a LAN network'), and the identification method ('by its network ID'). Among siblings such as createLanNetwork, updateLanNetwork, and getLanNetworkList, the delete verb unambiguously identifies this tool's 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?

No guidance is provided on when this tool should be used, what must hold before calling it (e.g., having obtained a networkId from getLanNetworkList), or which alternatives might be more appropriate. No exclusions or alternative routing is given.

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

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

No annotations are present, so the description carries the burden of behavioral disclosure. It does add a useful authentication requirement, OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD. However, for a destructive operation it does not explicitly state that deletion is permanent or describe any side effects on the schedule's associated ports or site.

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

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

The description is compact: one sentence states the operation and target, and the second adds the required credential context. There is no filler or redundant restatement of schema information.

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

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

For a mutation tool with no annotations, no output schema, and zero schema description coverage, the description is incomplete. It omits the meaning of siteId, does not explain what the response will look like, and provides no guidance on error cases or side effects, leaving an agent under-equipped to invoke it correctly.

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

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

Schema description coverage is 0%, so the description should compensate, but it only says 'by id' without explicitly mapping that to the scheduleId parameter. The siteId parameter is completely unexplained, leaving an agent without enough meaning to confidently populate the optional parameter.

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 PoE schedule by id' — clearly distinguishing it from siblings like createPoeSchedule, updatePoeSchedule, and listPoeSchedules. The 'by id' qualifier also clarifies the operation is targeted at a single existing schedule.

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 'Delete a PoE schedule by id', but the description gives no explicit guidance about when to choose this tool over alternatives such as deleteRebootSchedule or the other PoE schedule operations. It does not state prerequisites beyond credentials or mention any exclusion cases.

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

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

No annotations are provided, so the description carries the behavioral disclosure burden. It does add an authentication prerequisite (OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD) that is not inferable from the schema. However, it does not mention side effects, irreversibility, or failure behavior, leaving notable behavioral gaps for a destructive 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 two short sentences with the primary action front-loaded and no redundant wording. Every sentence contributes meaningful information.

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

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

For a destructive tool with no annotations and no output schema, the description is insufficiently complete. It omits siteId semantics, expected response or errors, and edge-case behavior. An agent can proceed only if scheduleId alone is always sufficient and the auth variables are known externally.

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 should explain both parameters. It only says 'by id', which adds little beyond the scheduleId parameter name. The optional siteId parameter is entirely unexplained, leaving an agent without enough context for correct invocation.

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 (delete), the resource (reboot schedule), and the selection mechanism (by id). This distinguishes it from sibling tools such as createRebootSchedule, updateRebootSchedule, and listRebootSchedules.

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 does not provide explicit when-to-use or when-not-to-use guidance, nor does it point to alternatives. The credential requirement is a prerequisite, not usage guidance, so an agent must infer suitability from the tool name and action 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 destructiveHint=true already declared in annotations, the description is not required to restate destructiveness. It adds useful behavioral context beyond annotations (paths are relative and the omadacId prefix is auto-prepended). However, it does not disclose what happens with arbitrary inputs — no warning about the lack of validation or info about response/error shape. Genuinely useful but 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?

Three sentences, every one earning its place: purpose, routing rule, and the critical path-format detail (with example). Information is front-loaded and there is zero fluff.

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 broad 5-parameter tool with no output schema, the description covers the core routing question and path format, and the annotation covers safety. But a complete example invocation (method + path + body) would substantially reduce agent error, and the version parameter is unexpplained. Adequate for a generic fallback, but not richly complete.

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

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

Schema description coverage is 0%, so the description bears the burden. It clarifies the most important parameter (path) by stating it is relative and giving a concrete example with a placeholder. However, it adds nothing about method, body, queryParams, or version — though the enums on method and version plus intuitive names partially mitigate this. Partial compensation only.

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 ('Execute an arbitrary Omada API call') and explicitly frames itself as the catch-all for 'any endpoint not covered by other tools'. This clearly distinguishes it from the 76 specific sibling tools, so an agent knows exactly what niche it fills.

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

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

Gives explicit routing guidance: 'Use this for any endpoint not covered by other tools.' This tells the agent when to pick this tool over the alternatives. It stops short of explicitly stating the inverse rule (do not use when a dedicated sibling exists), but the implication is clear.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. The prerequisite dependency is disclosed, and 'Get' implies a read operation, but the description does not explain what happens if startCableTest was not run, whether results are polled, or how the response is structured.

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 with no filler. The core purpose is front-loaded, and the crucial prerequisite is stated immediately after. 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 captures the essential workflow and core purpose, but with no output schema and no parameter details, an agent is left guessing about return values and the role of siteId. It is barely adequate for a simple two-parameter read tool, 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?

Schema description coverage is 0%, so the description must compensate for missing parameter documentation. It only vaguely maps to switchMac via 'for a switch' and does not mention the optional siteId or clarify any relationship between the parameters. The parameter names are somewhat self-explanatory, but the description itself adds little.

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 resource ('cable test results'), and the target ('a switch'). It also distinguishes itself from the sibling startCableTest by making clear this is the follow-up read operation, not the initiation.

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 instruction 'Run startCableTest first' provides a clear precondition and effectively tells the agent when this tool is appropriate: after a cable test has been started. It does not explicitly mention alternatives or when not to use it, but the workflow dependency is unmistakable.

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 alone must disclose behavioral traits. 'Fetch details' conveys a read operation, but there is no mention of required context such as siteId, error behavior for unknown clients, or whether the result is a single object or nested structure. This is minimal but not misleading.

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 wasted words, which is structurally clean. However, it is under-specified to the point of being terse rather than usefully concise, so it does not earn full credit.

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 zero parameter documentation, a one-line description is insufficient. An agent would not know how to format the required clientId, whether siteId is needed for multi-site environments, or what 'details' the response will contain.

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% and the description adds no meaning to either parameter. While 'specific' hints that clientId is the target identifier, it does not explain what siteId is for, whether clientId is a MAC address or internal ID, or any format expectations. The description fails to compensate for the schema's silence.

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 ('Fetch') and resource ('a specific Omada client'), which is immediately distinguishable from list-oriented siblings like listClients. However, it does not explicitly differentiate its scope from getDevice or clarify what kind of client entity is meant, so it falls just short of a perfect score.

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 listClients, listClientsActivity, or getDevice. The phrase 'a specific' implies the user already has an identifier, but the description does not state that prerequisite or mention any exclusions.

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

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

With no annotations provided, the description carries the burden of behavioral disclosure. 'Fetch' clearly signals a read-only operation with no destructive side effects, which is useful. However, it does not disclose response format, error behavior, or whether siteId influences the result, leaving gaps beyond the minimal safety indication.

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 core meaning, making it an excellent example of efficient writing.

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

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

For a tool with no output schema and sparse parameter documentation, the description leaves important gaps: when to use this versus getSwitch or listDevices, whether siteId is needed in certain contexts, and what 'detailed information' includes. The low schema coverage and absence of guidelines make this insufficiently complete.

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

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

Schema description coverage is 0%, so the description must compensate for parameter documentation, but it does not. The phrase 'specific Omada device' loosely implies deviceId identifies the target, yet siteId is completely unmentioned and its optionality or purpose is left unexplained.

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 ('Fetch') and resource ('detailed information for a specific Omada device'), making the primary purpose unambiguous. It hints at differentiation from list-like siblings by emphasizing 'specific', but does not explicitly name alternatives, 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 phrase 'specific Omada device' implies this tool is for retrieving details about one known device rather than listing many, which is an implied usage context. However, it provides no explicit guidance on when to choose this over siblings like getSwitch or searchDevices, and no when-not-to-use exclusions.

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

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

With no annotations, the verb 'Get' clearly signals a non-destructive read, and the description adds meaningful scope by naming the returned categories: ACL rules, IP groups, and security policies. It does not mention auth or preconditions, but for a simple fetch that is a minor omission.

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 with the action and object, and zero filler. Every clause adds information about what this getter returns.

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 a one-parameter getter and hints at the return content, but it does not explicitly confirm that siteId is required or describe the return shape beyond the inclusion list. Since there is no output schema, the description carries more responsibilty than it fully shoulders.

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% and the description only refers to 'a site' without explaining the siteId parameter or clarifying that it is required; the input schema also omits a required array. The single parameter is self-descriptive by name, but the description does not compensate for the lack of schema documentation.

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 operation ('Get'), resource ('firewall configuration and rules'), and scope ('for a site'), and enumerates what is included: ACL rules, IP groups, and security policies. This clearly differentiates it from sibling mutation tools like updateFirewallSetting and create/deleteFirewallAcl.

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 read/retrieval use case but gives no explicit when-to-use or when-not-to-use guidance and does not name alternative getters/setters. The phrase 'for a site' is the only contextual cue, so an agent must infer when to choose this tool over related firewall mutation 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?

With no annotations provided, the description carries the full behavioral burden. The verb 'Get' and the focus on 'information' imply a read-only, non-destructive operation, and the description names the expected return content. However, it does not explicitly state side-effect-free behavior, required permissions, or caveats about update availability.

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, front-loads the core action and resource, and contains no filler or redundant information. Every word contributes to the 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 simple read tool, the description names the expected return fields, but it omits the optional siteId parameter, any error conditions, and how this tool relates to overlapping siblings. Without an output schema or annotations, the description leaves meaningful gaps for an agent to navigate.

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 undocumented parameters. It loosely maps 'a device' to deviceMac but never explains deviceMac or the optional siteId parameter, leaving the agent without semantic guidance for the parameters.

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

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

The description states a specific verb and resource ('Get firmware information') and clarifies the output scope ('current version and available updates'). It is distinct from action-oriented siblings like startFirmwareUpgrade, though it does not explicitly differentiate itself from getDevice.

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 getDevice or listDevices. It does not state exclusions, prerequisites, or context, leaving the agent to infer appropriate 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?

No annotations are provided, so the description carries the behavioral burden. It does signal a read-only operation via 'Get' and partially discloses return content ('WAN settings and connectivity details'), but it does not mention permissions, error behavior, or what happens when siteId is omitted/invalid. The read implication is fairly clear, but the full burden is not 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?

The description is a single, well-formed sentence with no filler. It is front-loaded with the action ('Get internet configuration information') and immediately adds the site scope and content details. Every phrase 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 one-parameter getter, the description conveys the core purpose and hints at return contents. However, with no output schema and no annotations, it does not fully clarify the invocation contract, especially whether siteId is required, or the exact shape/scope of the returned data. It is minimally adequate but has clear 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 0%, and the only parameter, siteId, has no schema description and is not listed as required. The description only says 'for a site,' which loosely hints at siteId's role but does not name the parameter, state that it is required, or explain accepted values. With such low schema coverage, more compensation is needed.

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

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

The description uses a specific verb ('Get') and a distinct resource ('internet configuration information'), scoped to a site and further clarified by 'including WAN settings and connectivity details.' This distinguishes it from LAN/WLAN/firewall setters at a high level, though it does not explicitly name any sibling tool to disambiguate.

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

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

There is no statement about when to use this tool versus alternatives like getSiteSettings, getLanNetworkList, or getFirewallSetting. No exclusions, use cases, or sibling references are provided, so the agent must guess when this tool is preferred.

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 burden of behavioral disclosure. It does convey that this is a read-only list operation and indicates the kind of data returned, but it does not mention potential behavioral details such as whether an empty list is possible, whether siteId must reference an existing site, or whether any filtering/pagination behavior applies.

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 with the core operation, and no filler. Every phrase adds useful information about scope or return content.

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

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

For a simple one-parameter list tool, the description covers the resource, the site scoping, and the expected content of the result. However, it omits any explicit guidance on the siteId parameter or on how this tool relates to sibling LAN network tools, leaving some gaps for the agent to fill.

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% and the description never explicitly mentions siteId or its role. The phrase 'in a site' is only an indirect hint that the single parameter scopes the request. Since the description must compensate for the lack of schema documentation, this is insufficient.

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 operation ('Get the list') and the specific resource ('LAN networks configured in a site'), and it adds concrete scope details (VLAN settings, IP ranges, DHCP configuration). This distinguishes it from sibling tools like createLanNetwork, updateLanNetwork, deleteLanNetwork, and getSsidList.

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 usage is implied by the purpose: use this when you need the LAN network inventory for a site. However, it does not explicitly state when not to use it or point to alternatives such as create/update/deleteLanNetwork for modifications, leaving some routing to the agent's inference.

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

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

With no annotations, the description carries the behavioral disclosure burden. The word 'Get' clearly signals a read-only operation, and the second sentence defines the domain concept. However, it does not disclose response format, pagination, authorization needs, or how the siteId affects results.

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

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

The description is two concise sentences. The main action is front-loaded and the second sentence adds useful domain context without wasting space.

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 this description is adequate, but without annotations or an output schema it leaves gaps: whether siteId is mandatory, what the response list contains, and any site-scoping constraints are not fully specified. It needs slightly more context to be 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 schema has 0% description coverage and the single siteId parameter is not described beyond the phrase 'in a site.' The description hints at the parameter's role but does not explain requiredness, format, or behavior when omitted, which is especially relevant since siteId is not marked required in the schema.

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

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

The description starts with a specific verb and resource ('Get the list of LAN profiles') and clarifies what LAN profiles are (network settings applied to switch ports). It is clear and distinguishable from related tools, though it does not explicitly name a sibling alternative like getLanNetworkList.

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 getLanNetworkList, createLanProfile, or updateLanProfile. The description implies the purpose but provides no exclusions, prerequisites, or context for choosing among related LAN-related 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?

With no annotations, the description carries the transparency burden and it does well: it reveals that only one type is returned per call, that page/pageSize are API-required despite schema defaults, and that two invocations are needed. It omits return shape, but the resource is well understood from name and text.

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, all informative, with the purpose, scoping, and call pattern presented in order. No filler or repetition that would dilute the guidance.

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 no output schema and no annotations, so a bit more return-format detail could help, but the description already tells the agent what to call, how many times, and what to pass. That is sufficient for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds operational semantics beyond the schema: both page and pageSize must be sent, and type must be varied across two calls to get the full picture. That adds real invocation 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?

States a specific verb ('Get') and resource ('port forwarding status and rules for a site'), then clarifies the User/UPnP split. This distinguishes it clearly from the sibling list/get tools, none of which target port forwarding.

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

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

Explicitly explains that complete information requires two calls, one per type. It does not compare to alternatives, but no direct sibling alternative exists, so the repeated-call guidance is strong practical direction.

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. It clearly implies a read-only operation via 'Get', discloses the required credentials, and adds a non-obvious caveat about timezone affecting schedule times. It could go further by mentioning output shape or error behavior, but the key auth and read-only traits are present.

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

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

The description is front-loaded with 'Get full site settings' and the following enumeration, while the timezone caveat and credential requirement each earn their place. It is a bit long because of the settings list, but it is not padded.

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

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

The description adequately explains what data is returned and what auth is required, and gives a practical timezone warning. However, it omits any guidance on the siteId parameter, possible default-site behavior, or output structure, and there is no output schema to fill that gap. For a one-parameter getter this is workable 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?

schema_description_coverage is 0% and the description never mentions siteId, how to obtain it, or whether it can be omitted. The only hint is the word 'site' in the description, which is not enough to meaningfully explain the lone parameter. The parameter name and minLength are left to carry all semantic weight.

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

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

Tthe description states a specific operation, 'Get full site settings', and lists a concrete set of settings (timezone, NTP servers, mesh, band steering, LED, etc.) that make the tool's scope clear. It does not explicitly contrast itself with sibling getters, but the 'full site settings' framing distinguishes it from narrower tools like getFirewallSetting or getSsidDetail.

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 a clear practical trigger: 'Check the timezone here before trusting any schedule time.' It also states the authentication precondition OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD. It does not explicitly name alternatives or excluded cases, so it falls short of a full when-to-use guide.

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 discloses what content the response covers (security settings, rate limits, scheduling, advanced configurations), and 'Get' implies a read-only operation. However, it does not explicitly state read-only safety, error behavior on invalid IDs, permission requirements, or response format — and with no annotations, those disclosures were needed.

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 totaling roughly 30 words, with the purpose front-loaded in the first sentence and operational detail in the second. There is no filler; both sentences earn their place, and the format is scannable for an agent.

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

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

For a 3-parameter tool with no annotations and no output schema, the description covers the core purpose and two of three parameters but leaves siteId undocumented. The content-area list partially compensates for the missing output schema by telling the agent what fields to expect, but error/edge-case behavior and the optional parameter gap remain unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. It adds valuable provenance for two required parameters: wlanId originates from getWlanGroupList and ssidId from getSsidList. However, the optional siteId parameter is completely omitted from the description and remains unexplained in both the schema and the description — a real gap given zero schema-level documentation.

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

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

States a specific verb (Get) and resource (detailed information for a specific SSID), and enumerates the content areas covered: security settings, rate limits, scheduling, and advanced configurations. The phrase 'specific SSID (wireless network)' differentiates it from list-style siblings like getSsidList, though it never names a sibling explicitly.

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

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

Provides clear workflow context by naming the prerequisite calls: wlanId must come from getWlanGroupList and ssidId from getSsidList. This effectively routes the agent into the correct call sequence as the detail-fetch step after listing. However, it gives no when-not-to-use guidance and no explicit comparison to alternative getters among the many 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, the description is the only behavioral signal. It clearly implies a read operation via 'Get the list,' but it does not state authorization needs, pagination, error behavior, or response structure beyond the presence of ssidId. The behavior is mostly 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?

Two short sentences with no filler. The core purpose is front-loaded, and the second sentence adds only actionable prerequisite and successor 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 description forms a coherent chain: obtain wlanId, get SSID list, then call getSsidDetail with ssidId. It omits return-format details and siteId semantics, which is a small gap for a simple getter, especially given no output schema or annotations.

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. It explains wlanId's provenance and that ssidId is usable downstream, but it leaves the optional siteId completely unexplained and does not describe wlanId's format or meaning beyond its source.

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

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

States a specific verb and resource: 'Get the list of SSIDs configured in a WLAN group.' The follow-up instruction to use the ssidId for getSsidDetail differentiates it from the detail sibling, making its role clear.

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

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

Provides explicit workflow context: wlanId comes from getWlanGroupList, and the resulting ssidId feeds getSsidDetail. This is clear guidance for when to call it, though it does not mention exclusions or cases where another list tool would be preferable.

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 burden and does state the core behavior: it reads and returns full switch information, specifically including portList. However, it does not disclose whether the operation is read-only, how errors or missing MACs are handled, or any response envelope details.

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 contains the key action, resource, notable output field, and required lookup key. There is no filler or redundancy.

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

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

For a simple getter with two parameters and no output schema, the description covers its main purpose and the primary parameter. It is adequate but incomplete: siteId, error behavior, and relationship to sibling tools are left unaddressed.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies that switchMac is a MAC address, but it does not explain the optional siteId parameter at all, leaving part of the input schema undocumented.

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 ('Get'), a specific resource ('full switch info'), and a distinguishing detail ('including portList array') plus the lookup key ('by MAC address'). This differentiates it from siblings like getDevice, getSwitchPorts, and getSwitchStackDetail.

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

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

The description implies usage when full switch details for a given MAC are needed, but it does not explicitly state when to prefer this over alternatives such as getDevice or getSwitchPorts. No exclusions or alternative-route guidance 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, the description carries the burden of behavioral disclosure. 'Get' conveys a read-only retrieval operation, and 'VLAN trunking configuration' describes what is returned. However, it does not explain output shape, paging/errors, or how siteId/site scope affects 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 efficient sentence with no filler or redundancy. The core verb and resource are front-loaded, 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 fairly simple, but with no output schema and no annotations, the description needed to provide more context about the required switchMac parameter and the meaning/siteId. The current one-liner is minimally identifying but leaves the agent without enough detail to invoke it confidently.

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 was expected to compensate for the undocumented parameters. It does not explain switchMac or siteId at all; 'for a switch' is only a faint clue to the required switchMac and siteId is completely unexplained.

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 specific resource ('switch networks / VLAN trunking configuration'), which clearly identifies what the tool retrieves. This also distinguishes it from siblings like setSwitchNetworks (a write operation) and getSwitchPorts (a different resource).

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

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

The description explains what the tool does but gives no guidance on when to choose it over alternatives. It does not mention related tools such as getSwitch, getSwitchPorts, or setSwitchNetworks, nor does it state any exclusions or conditions.

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 burden. 'Get' implies read-only and the description lists return fields, but it says nothing about pagination, error cases, authentication needs, or whether the result is ordered or paginated.

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 that begins with the action and resource and immediately conveys the key identifier. No filler or redundant wording.

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 simple getter: it names the resource, identifier, and main output fields. However, siteId remains unexplained, there is no mention of alternative tools, and non-success behavior or return shape is unspecified.

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. It clarifies that switchMac is a MAC address, but it says nothing about the optional siteId parameter. Only partial semantic coverage for the parameters.

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

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

States a specific verb, resource, and identifier: it gets all ports for a switch by MAC address. It also lists the returned attributes (status, profile, PoE, link speed, STP state), making it clearly distinct from sibling getters like getSwitch or getSwitchNetworks.

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

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

Provides clear context: use when you need all ports for a specific switch identified by MAC. It says no alternative conditions or exclusions, so it stops short of giving explicit when-not-to-use guidance.

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

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Fetch' implies a read-only operation, but the description does not mention authorization requirements, error behavior, or what the returned information includes. This is a meaningful gap for a tool with no annotation support.

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 wasted words, and the core action is front-loaded. It is efficient, though the brevity leaves some contextual gaps that are 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?

For a tool with no annotations and no output schema, the description is too thin. It does not explain return value shape, the role of the optional siteId parameter, or how this differs from related switch tools. An agent could guess the basic intent but not fully understand invocation context.

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

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

Schema description coverage is 0%, and the description does not mention stackId or siteId at all. The schema only provides raw field names, so the agent gets no semantic help about how siteId relates to stackId or what values are expected.

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: 'Fetch detailed information for a specific switch stack.' This clearly identifies the operation and distinguishes it from siblings like getSwitch, getSwitchPorts, and getSwitchNetworks, though it does not explicitly contrast itself with 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?

No guidance is provided about when to use this tool versus alternatives such as getSwitch or getDevice. The description implies use when stack details are needed, but it gives no context, prerequisites, or exclusions.

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

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

There are no annotations, so the description carries the full behavioral burden. It discloses pagination and the kind of information returned, which is useful. It does not mention required time constraints, authorization, or that archived threats are included/excluded by default, leaving some behavioral ambiguity.

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, compact sentence that front-loads the core purpose and then lists key return contents. Every word contributes value, and there is no redundant repetition of the schema.

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

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

For a tool with 9 parameters, 3 required, and no output schema, the description is fairly minimal. It gives a good orientation, but it does not clarify required time/archive parameters, the meaning of 'global view,' or whether the result has any aggregate/statistical nature. The schema covers paramters, so the gaps are moderate rather than severe.

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

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

The schema description coverage is 100%, so the baseline is 3. The description does not add meaningful parameter-level guidance; it lists output fields rather than explaining input semantics. No additional context about required startTime/endTime/archived or filtering behavior is provided in the description.

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

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

The description uses a specific verb and resource: "Get the global view threat management list." It also lists concrete content types (severity, source/destination IPs, countries, classification), which makes the purpose unmistakable. No sibling tool overlaps with 'threat list,' so it is clearly differentiated.

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

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

The description implies when to use the tool: when you need the global threat management list. However, it does not explicitly state when not to use it or name alternatives such as listEvents or listLogs. The usage context is inferable but not made explicit.

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

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

No annotations are provided, so the description carries the behavioral transparency burden. 'Get' implies a read-only operation, but the description does not explicitly confirm side effects, authentication needs, response format, or pagination. The added context about WLAN groups and the wlanId linkage is useful but incomplete.

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

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

The description is concise, front-loaded with the main purpose, and every sentence earns its place. The first sentence states what the tool does, the second provides context, and the third connects to the next workflow step without fluff.

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 list tool, the description covers the core purpose and provides a useful output hint ('Use the wlanId from this list'). However, with no annotations and no output schema, it would benefit from clarifying siteId semantics and the expected response shape. The description is minimally viable but leaves some context 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 0%, so the description needs to compensate for the undocumented siteId parameter. The description mentions 'in a site' and 'wlanId' in output, but it does not explicitly explain the siteId input, whether it is required, or where it comes from. The parameter name is self-explanatory, but the description adds minimal semantic value 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 action and resource: 'Get the list of WLAN groups configured in a site.' It also distinguishes itself from the sibling getSsidList by explaining that WLAN groups contain SSIDs, so an agent can tell which tool to use first.

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 sequential guidance: 'Use the wlanId from this list to call getSsidList.' This establishes when this tool fits into a workflow, though it does not explicitly mention when not to use it or compare it to other sibling tools.

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

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

With no annotations, the description carries the full behavioral burden. 'List' implies a read-only operation, but nothing is said about pagination, response shape, authorization needs, or what happens when siteId is omitted.

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 seven-word sentence with no filler, front-loading the action and resource. It is efficient, though more detail could have been added without becoming bloated.

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

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

For a tool with no annotations, no output schema, and a single parameter, the description is too sparse to enable confident invocation. It does not clarify that siteId needs to be supplied or what the returned list contains, and it gives no help in choosing among the many client-related 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?

Schema description coverage is 0%, and the description only loosely references 'a site' rather than explicitly explaining the siteId parameter, its requiredness, or its format. The parameter name is self-explanatory, but the description does not compensate for the missing schema documentation.

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 concrete action ('List') and resource ('network clients') scoped to a site, making the core purpose clear. It is distinguishable from siblings like getClient or listClientsActivity, though it does not explicitly differentiate itself from 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 about when to use this tool versus closely related siblings such as listMostActiveClients, getClient, or listClientsPastConnections. No prerequisites, context, or exclusions are 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?

No annotations are provided, so the description carries the burden. It does disclose that the tool returns time-series data with categories and client types (wireless/EAP and wired/switch), which is useful. However, it does not mention potential limitations like time range defaults, data granularity, or whether data is read-only.

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

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

The description is two sentences, front-loaded with the core purpose, and every sentence contributes useful information. No fluff or redundant phrasing.

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

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

There is no output schema, but the description does summarize the response content. However, it lacks details about default time ranges, response format, or how to interpret the time snapshots, which an agent would need to call it correctly without further probing.

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

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

Schema description coverage is 100%, so parameters are already well-documented. The description adds general context about 'time' and 'dashboard' but does not add meaning beyond the schema's parameter descriptions.

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

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

The description uses a specific verb ('Get') and resource ('client activity statistics over time from the dashboard'), and clearly distinguishes this from siblings by emphasizing time-series data of new, active, and disconnected clients. This makes it easily differentiable from tools like listClients or listMostActiveClients.

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

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

The description provides clear context: 'Useful for monitoring client connection trends and activity patterns.' It implies when to use this tool without explicit exclusions or named alternatives, but the context is strong enough to guide selection among sibling tools.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It identifies the operation as read-only via 'Get,' specifies the returned data categories (timestamps, traffic, duration, device details), and lists supported behaviors (pagination, filtering, sorting, fuzzy search). It does not describe response structure in detail, but the core behavioral profile is 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 sentences front-load the resource and scope, then compactly enumerate supported capabilities. There is no filler or repetition of schema details.

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

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

For an 8-parameter, no-required-param read tool with a fully described schema, this definition provides sufficient invocation context. The lack of an output schema is partially offset by the included return-field summary, though a full response-structure note would make it fully complete.

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

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

Schema coverage is 100%, so every parameter already has a description. The description adds a useful capability-level summary but no new per-parameter semantics 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 names a specific resource ('client past connection list') and states it returns clients that have 'previously connected to the network.' This clearly separates it from current-client siblings like listClients and makes the historical scope 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?

Usage is implied through phrases like 'past connection list' and 'previously connected,' so an agent can infer this is for historical rather than current connections. However, it never names alternatives such as listClients or gives explicit when-to-use/when-not-to-use guidance.

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

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

With no annotations provided, the description carries the full disclosure burden, yet it only states the core action. It does not reveal that siteId is effectively required despite the schema listing no required fields, nor does it mention return format, pagination, or behavior on invalid site IDs. The verb 'List' weakly implies a read operation, but little else is transparent.

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 zero filler, and the verb and resource are front-loaded. It is efficiently written, though the brevity partly reflects how little behavioral information is offered.

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 and no output schema, more than this is needed: the schema marks siteId as not required while the description implies a site must be specified, and nothing disambiguates this from searchDevices or listDevicesStats. The single-parameter surface keeps it from being a 1, but the gaps are material.

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. It partially does: 'for a specific site' tells the agent that siteId scopes the listing. However, it does not clarify the ID format or how to obtain it; with only one well-named parameter, this is a moderate gap rather than a severe one.

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

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

The description names a specific verb ('List'), a specific resource ('provisioned network devices'), and a scope ('for a specific site'), so an agent can immediately grasp the tool's function. It is not a tautology and reads distinctly from siblings, though it does not explicitly name alternatives like searchDevices or listDevicesStats.

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 listDevices versus overlapping siblings such as searchDevices, listDevicesStats, or getDevice. The phrase 'for a specific site' is a weak contextual hint that the tool is site-scoped, but no conditions, exclusions, or alternatives are stated.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It does add meaningful behavior: pagination, fuzzy search by specific fields, and filtering by tag or device series type, with the 0/1 mapping defined. It does not describe the response shape or what 'statistics' contains, and there is no output schema to fill that gap, so the agent cannot fully anticipate the return format.

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

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

The description is two sentences with no filler: the main purpose is front-loaded, and the second sentence packs the concrete search and filter semantics. Every clause earns its place, including the 0/1 mapping for device series type.

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 an eight-parameter tool with no output schema, no annotations, and no explicit alternative routing. The description leaves the nature of the returned statistics, the aggregation level, and how multiple search/filter parameters interact unspecified. For a complex list-style tool, this is insufficiently complete for reliable agent 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?

Only page and pageSize have schema descriptions, so the description must compensate for the remaining six parameters. It does so by mapping searchSns/searchMacs/searchNames/searchModels to fuzzy search by serial, MAC, name, and model, and by explaining filterDeviceSeriesType with the 0/1 basic/pro meaning. It stops short of defining how multiple filters combine or what value formats are expected, but it adds substantial meaning beyond the bare 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?

Description states a specific action ('Query statistics') and resource ('global adopted devices'), then lists concrete capabilities: pagination, fuzzy search, and filter dimensions. It distinguishes itself from sibling tools like listDevices or searchDevices by focusing on statistics rather than raw device lists, though it does not name those siblings explicitly. Minor ambiguity remains about precisely what kind of statistics are returned.

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 'statistics for global adopted devices' implies this is for aggregate statistical data rather than per-device management or listing, so an agent can infer a likely use case. However, there is no explicit when-to-use or when-not-to-use guidance, nor any mention of alternatives such as listDevices, searchDevices, or getDevice. The usage context is implied, not stated.

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

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

With no annotations, the description carries the transparency burden. It adds 'paginated' and the event-type categories, which are useful behavioral context, and 'list' implies a read-only operation. However, it doesn't disclose ordering, time window, result shape, or the fact that siteId is not required in the schema, leaving some ambiguity.

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 front-loaded sentence contains all the essential info: operation, resource, pagination, and event categories. No fluff or redundant restatement of the tool name or schema defaults.

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 paginated list tool, the combination of description and input schema covers the basic call pattern (page, pageSize, and site context). However, missing output schema and no return-format description, plus no guidance on siteId optionality or time range, leave gaps that a fully complete definition would close.

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 67%: page and pageSize already have descriptions, so the description doesn't need to restate them. The phrase 'for a site' gives semantic context to the otherwise undocumented siteId parameter, but it doesn't clarify that siteId is optional. Net value is moderate but sufficient.

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

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

The description states a clear verb ('List') and resource ('events for a site') and gives concrete event categories (alerts, warnings, system events), making its purpose evident. It doesn't explicitly differentiate from similar siblings like listLogs or getThreatList, so it isn't maximally disambiguating.

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 usage conditions, prerequisites, or alternative tools are mentioned. The sibling list contains many list/get tools, and there is no guidance on when to choose this over listLogs or getThreatList. The only implied use is 'when you want events for a site'.

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 behavioral burden. It indicates a read-only 'List' operation, but does not disclose pagination, result ordering, default behavior when siteId is omitted, authentication needs, or any output characteristics.

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. The parenthetical adds useful clarification without bloating the definition.

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 read tool, this is minimally viable, but it leaves gaps: no output schema, no alternative routing guidance, and no explanation of the siteId parameter beyond the phrase 'for a site.' An agent could likely invoke it correctly, but would be guessing about result details and edge cases.

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 provides no description for siteId, and schema description coverage is 0%. The phrase 'for a site' adds some domain meaning, but the description does not clarify siteId's format, whether it is optional, or what happens when it is omitted.

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 clear resource ('firewall ACL rules'), and a scope ('for a site'). The parenthetical clarifies what ACLs are, and the tool is easily distinguished from siblings like createFirewallAcl, deleteFirewallAcl, and getFirewallSetting.

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 usage is implied: use it when you need to list firewall ACL rules for a site. However, it provides no explicit guidance about when to prefer this over related tools like getFirewallSetting or how it differs from firewall settings retrieval.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It usefully reveals the authentication requirement (OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD) and implies a read-only operation via 'List,' but it omits behavior around the optional siteId (e.g., what happens if omitted) and does not describe output format, pagination, or error cases.

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

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

The description is compact and well-structured: the core function is front-loaded, followed by a relevant usage note and the credential requirement. Every sentence adds value and there is no redundancy or filler.

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

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

For a simple one-param read tool, the description covers purpose, use case, and credentials. However, with no output schema, it does not explain the return shape, and it leaves the behavior of the optional siteId ambiguous. This is adequate but not fully complete for an agent invoking it correctly in all cases.

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 documenting the single parameter, siteId. It only vaguely references 'a site' without explicitly naming siteId or explaining its format, optionality, or default behavior. This leaves meaningful semantic gaps for the agent.

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 IP/port groups configured in a site.' The addition of 'IP/port groups' and the firewall ACL context clearly differentiates it from sibling list tools like listFirewallAcls or listClients, so an agent can identify the tool's unique 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?

The description implies usage context by noting that groups can be used in firewall ACL rules, which tells the agent when this tool is relevant. However, it does not explicitly state when to use it versus alternatives like listFirewallAcls, nor does it mention exclusions or prerequisites beyond the credential requirement.

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 must carry the full behavioral burden. It discloses pagination and log types but does not explain response format, ordering, date filtering, permissions, or limits beyond the schema's max pageSize.

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 the primary action front-loaded and a useful clarifying parenthetical. No wasted words.

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

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

For a simple paginated list tool, the description is adequate but minimal. It lacks an output schema and does not describe return structure or required parameters, though the tool name and description imply a list of log entries.

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 67%, with page and pageSize already documented. The description adds meaning by tying the logs to a site (siteId) and confirming pagination, but it does not elaborate on siteId format or provide significant semantic detail beyond the schema.

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

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

The description states a clear verb and resource: 'List paginated logs for a site,' and the parenthetical adds the specific log categories. It does not explicitly differentiate from the sibling listEvents, but 'logs' is a reasonably distinct resource.

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 context that logs are per-site but offers no guidance on when to use this tool versus siblings like listEvents or other list tools. No exclusions or alternative routing 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, the description carries the full burden. It discloses the sorting basis, the returned fields, and the dashboard-oriented nature, and 'get' implies a read-only operation. However, it does not mention ordering direction, pagination, limits, or behavior when no clients exist, leaving some gaps.

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

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

Three tight sentences with no filler: the main action and sort are front-loaded, followed by return fields and a concise use-case note. Every sentence adds value.

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

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

For a simple one-parameter list endpoint, the description covers the core behavior and return fields, but it leaves parameter semantics ambiguous and does not state whether siteId is mandatory. Given no annotations and no output schema, it is adequate 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?

Schema coverage is 0% and the description never explicitly describes siteId, the sole parameter. 'In a site' hints that siteId identifies the site, but the description does not clarify whether it is required, optional, or how it is validated. The description therefore fails to compensate for the schema's lack of parameter documentation.

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

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

Clearly states it gets the most active clients in a site, sorted by total traffic, and enumerates the returned fields. This distinguishes it from sibling tools like listClients (full list), getClient (single client), and listClientsActivity (activity log), making its purpose unambiguous.

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

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

The description frames this as a dashboard endpoint for a quick overview of top clients by traffic, giving the agent clear context for when to use it. It does not explicitly name alternatives or state when not to use it, but the intended use case is reasonably clear.

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

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

With no annotations, the description must carry behavioral disclosure. It does include the authentication requirement (OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD) and explains what PoE schedules are conceptually, which is useful. However, it never explicitly states that the list operation itself is read-only and has no side effects, nor does it describe output or pagination behavior. This is adequate but has clear gaps.

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

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

The description is concise and front-loaded with the action. Both sentences earn their place: the first states the purpose and scope, and the second explains the domain effect and required credentials. There is 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?

This is a simple one-parameter tool, and the description gives enough for a basic understanding: what it lists, at what scope, and what credentials are needed. However, there is no output schema, and the description does not clarify what the returned list contains, whether the call is safe/read-only, or where siteId comes from. It is reasonably complete for a simple tool but still leaves important 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 0%, so the description should compensate for the siteId parameter. The phrase 'for a site' loosely maps to siteId, but there is no explanation of how to specify or obtain the site ID, whether it is required, or how it relates to listSites. The single parameter is only minimally illuminated.

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 action and resource: 'List PoE schedules for a site.' It adds helpful domain context about what PoE schedules do, which also distinguishes this from generic schedule tools. It does not explicitly contrast it with siblings like listRebootSchedules, 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 implies the tool is used to retrieve PoE schedules for a specific site and notes that credentials are required. It does not explicitly state when to prefer this over related tools such as listRebootSchedules or how to obtain siteId. Usage context is present but exclusionary or alternative 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?

With no annotations provided, the description carries the full disclosure burden and uses it well: it reveals that nextExecute is a millisecond epoch in UTC and warns about a concrete DST failure mode, plus states the auth requirement. It stops short of a 5 because it never explicitly confirms the operation is read-only or side-effect-free, leaving 'List' to carry that implication.

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

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

Three sentences with no filler: purpose, then a high-value UTC/DST interpretation caveat, then the credential requirement. The verb-object is front-loaded and every sentence adds information an agent would otherwise lack.

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 list tool with no output schema, this is nearly complete: purpose, result contents, a subtle data-interpretation trap, and credentials are all covered. The only meaningful gap is that it never points the agent to listSites for the siteId or describes the result shape.

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, but it only notes that the tool operates 'for a site,' mapping siteId to its role without explaining how to obtain it (e.g., from listSites) or its expected format. The parameter's own name carries most of the semantic weight.

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

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

States a specific verb and resource ('List reboot schedules') with explicit scope ('for a site') and enumerates what the response contains (which devices each one targets and the next execution time). The name and content clearly distinguish it from sibling mutation tools (createRebootSchedule, updateRebootSchedule, deleteRebootSchedule) and from listPoeSchedules.

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

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

Usage is implied rather than explicit: the description reads as a straightforward read operation, and it does provide prerequisites ('Requires OMADA_WEB_USERNAME/OMADA_WEB_PASSWORD'). However, there is no when-to-use vs. when-not-to-use guidance or routing to alternatives such as listPoeSchedules or the create/update/deleteRebootSchedule trio.

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. 'List' clearly implies a read-only operation returning configured routes, but the description does not disclose response shape, pagination, ordering, or required permissions. For a simple list operation this is adequate but still leaves gaps.

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. The action, resource, and scope are front-loaded, 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 read-only listing tool with no output schema or annotations, the description is minimally sufficient. However, it omits details about the siteId requirement and the return format, which an agent would need for fully reliable invocation.

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

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

Schema description coverage is 0% and the description does not explain siteId's format, source, or requiredness. The phrase 'for a site' connects the parameter to a concept, but it does not compensate for the lack of schema-level documentation, especially since the schema marks no parameters as 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?

The description clearly states the verb (List), the resource (static routes), and the scope (configured for a site). This distinguishes it from the many sibling tools that operate on different resources such as clients, devices, or firewall ACLs.

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 instead of other network/route-related tools, nor how to obtain the siteId. The description only implies usage context through the phrase 'for a site' without offering any explicit selection criteria or alternatives.

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

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

Without annotations, the description carries the full burden of behavioral disclosure. It clearly implies a read-only list operation, which is helpful, but it does not mention pagination, response format, ordering, site fields, or any controller-state nuances. This is acceptable but minimal for a simple parameterless list tool.

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

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

The description is a single, front-loaded sentence with no filler or redundancy. Every word contributes 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?

Given the zero-parameter schema and simple scope, the description is nearly complete for selecting and invoking the tool. However, since there is no output schema and no annotations, the description could have added a bit more detail about the response shape or site data returned.

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

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

The input schema has zero parameters and schema description coverage is 100%, so there are no parameter semantics to document. The description appropriately avoids inventing parameters.

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

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

The description uses a specific verb and resource: 'List all sites configured on the Omada controller.' It clearly communicates the operation and scope, and it is immediately distinguishable from sibling tools that target clients, devices, or firmware.

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, and does not mention any exclusions, prerequisites, or context in which listSites is the right choice. The tool's applicability must be inferred entirely from its name and generic phrasing.

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. It discloses the authentication requirement and implies a read-only listing operation, but it does not mention pagination, result format, or behavior when no profiles exist. For a simple list operation 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 two sentences with no filler. The core action is front-loaded, and the explanatory second sentence earns its place by defining the resource's role in the broader system.

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 list tool with no output schema and no annotations, the description provides useful domain context and credential requirements. However, it does not mention the return value or how to obtain a valid siteId, which an agent might need to call it correctly in context.

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

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

Schema description coverage is 0%, so the description must compensate. It mentions 'for a site' which gives context for the siteId parameter, but it does not explain where to obtain the siteId, whether it is required, or what values are valid. The single parameter is simple enough that this partial guidance is merely adequate.

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

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

The description states a specific verb and resource: 'List time range profiles for a site.' It also clarifies what these profiles are and how they relate to PoE schedules, WLAN schedules, and ACL rules, which distinguishes this from sibling tools like listPoeSchedules or listFirewallAcls.

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

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

The description gives clear context for when this tool matters: time range profiles are the reusable primitive that other schedule and rule types bind to. It does not explicitly name alternatives or state when not to use it, but the domain explanation is enough to guide an agent toward this tool when time range profile IDs are needed.

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

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

The annotation already declares destructiveHint=true, so the destructive nature is covered. The description aligns with that by stating a reboot, but it adds little beyond the structured annotation and does not disclose effects like temporary device unavailability or connection drop. With annotations present, this is acceptable but not enhanced.

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

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

The description is a single front-loaded sentence with no filler or redundancy. Every word contributes to the core meaning, and the structure makes it easy for an agent to parse quickly.

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

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

For a simple two-parameter destructive tool, the description conveys the core operation adequately, especially with the destructiveHint annotation. However, it does not explain return behavior, the role of siteId, or the practical impact of the reboot, which leaves the agent with some uncertainty when invoking the tool.

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

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

Schema description coverage is 0%, so the description must compensate for the lack of parameter documentation. It does clarify that deviceMac is the targeting identifier, but it entirely omits any semantics for the optional siteId parameter, leaving meaningful ambiguity for the agent.

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 ('Reboot'), a clear resource ('network device'), and the identifying mechanism ('by its MAC address'). This is fully distinguishable from siblings like getDevice or createRebootSchedule, and the verb+resource pattern is unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives. In particular, there is no mention that this is for immediate reboots while createRebootSchedule exists for scheduled reboots, and no exclusions or prerequisites 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?

The description states the forceful reconnect behavior, which adds context beyond the destructiveHint annotation. However, it does not explain side effects such as dropping the current session or whether the client will automatically reconnect or need assistance.

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 concise sentence with no filler words or repetition. It communicates the essential action and identifying parameter 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?

For a simple two-parameter action, the description is minimally viable: it states the operation and the identifying parameter. Yet it lacks siteId semantics, usage context, and any clarification of destructive consequences beyond what annotations already signal.

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

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

With 0% schema description coverage, the description must compensate. It clarifies clientMac by saying 'by its MAC address', but it does not explain siteId at all, leaving that parameter's meaning and necessity unclear.

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 ('Force') with a clear resource ('a client') and action ('reconnect to the network by its MAC address'). This clearly distinguishes it from sibling tools like blockClient and updateClient.

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

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

No explicit guidance is provided for when to use this tool versus alternatives such as blockClient, unblockClient, or updateClient. The scenario is implied, but no exclusions or alternative routing are 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?

No annotations are provided, so the description must disclose behavior on its own. It only says the tool searches and returns matching devices; it omits output format, pagination, exact match behavior, or any implication about access/error handling. This is a thinn behavioral description for a tool with no other context.

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

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

The description is two short sentences with no filler. The primary scope is front-loaded ('Search for devices globally across all sites the user has access to'), and the next sentence adds the matching behavior.

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

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

For a simple one-parameter tool, the description covers the basic purpose, but because there is no output schema and no parameter documentation, it should at least specify what the search key matches and what kind of result is returned. As written, an agent may invoke it without knowing how to construct a searchKey or 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 input schema only defines a searchKey string with minLength 1, and schema description coverage is 0%. The description merely repeats 'search key' in prose without explaining what fields are searched, whether it matches partial strings, IDs, IPs, or device names. This is insufficient compensation for the missing schema descriptions.

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

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

The description states a specific action ('Search for devices'), a clear resource ('devices'), and a distinct scope ('globally across all sites the user has access to'). This also differentiates it from siblings like listDevices or getDevice, which are likely site-scoped or single-device lookups.

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

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

The description provides clear usage context: call this when you need to find devices across all sites the user can access, using a search key. It does not explicitly state when not to use it or name alternatives, but the global-scope wording gives sufficient routing context.

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

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

destructiveHint=true already flags this as a mutation and the description is consistent with it — setting device state is genuinely a change. The description adds the three LED mode semantics but nothing further (e.g., operational impact of disabling a status LED, or behavior when the MAC is not found). With annotations covering the safety profile, a 3 is fair.

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 15-word sentence with the verb front-loaded and zero filler. Every word contributes: the action, the resource, the allowed states, and the addressing mechanism.

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 three-parameter state-set tool with destructiveHint=true and no output schema, the description gives the essential operational picture: what is set, the possible values, and how the target is identified. The only notable omission is siteId semantics; otherwise nothing needed to invoke it correctly is missing.

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

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

Schema description coverage is only 33% (ledSetting is described). The description compensates for deviceMac ('by its MAC address') and ledSetting ('on/off/site-default' matching 0/1/2), but siteId is left completely unexplained — the agent cannot tell why or when it is needed, which is a real gap at this coverage level.

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 verb+resource ('Set the LED'), enumerates the three valid modes (on/off/site-default), and identifies the target via MAC address. This clearly differentiates it from mutation siblings like setSwitchPortStatus or setSwitchPortPoe without needing to open the schema.

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

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

No guidance is given on when to use this tool versus alternatives, nor when siteId should be supplied. There are no context cues, exclusions, or mention of prerequisites such as the device needing to be adopted or online, so the agent must infer usage entirely from the name and schema.

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 include destructiveHint=true, but the description adds no further behavioral context beyond the literal connect/disconnect effect. It does not mention potential impact such as disconnecting internet access, reversibility, or state changes on the gateway.

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, efficient sentence with no fluff. The key verb and resource are front-loaded, making it easy to scan.

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

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

For a mutating tool with no output schema and only 25% parameter documentation, the description is too sparse. It does not clarify how to obtain gatewayMac, portId, or siteId, nor what response or side effects to expect.

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

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

Schema description coverage is only 25% (only action is documented). The description's phrase 'gateway WAN port' hints that gatewayMac and portId refer to a gateway and its WAN port, but siteId remains unexplained and no parameter details are added.

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

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

States a specific verb (connect/disconnect) and a specific resource (gateway WAN port). It clearly identifies the operation and is distinct from sibling tools like setSwitchPortStatus, which targets switch ports.

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

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

No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. The action enum implies connect/disconnect scenarios, but the description does not explain when to choose this over related port-management 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?

With no annotations provided, the description carries the full behavioral burden. It goes beyond a simple mutation statement by warning that timezone alone does not enable DST, explaining that DST is a separate disabled site setting, and describing the wall-clock impact on schedules. This is valuable, concrete behavioral disclosure.

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

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

The core purpose is stated in one direct sentence, followed by a relevant warning that earns its length. The DST explanation is verbose but necessary for correct usage. 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 simple setter with no output schema, the description covers the most important operational risk (DST behavior) and directs the agent to verification steps. It is not fully complete because siteId semantics remain unclear and there is no mention of expected response or result handling, but it is strong 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?

The schema already documents timeZone with an IANA example, and the description reinforces its meaning by warning that it does not affect DST. It also hints that region/scenario fields are handled internally. However, siteId is left completely undocumented, and at 50% schema coverage the description does not fully resolve parameter ambiguity.

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

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

Starts with a specific verb and resource: 'Set the site timezone.' It also clarifies the tool's distinct role by noting it 'handles the region and scenario fields the controller requires alongside it,' which helps differentiate it from generic updateSiteSettings. No ambiguity about what operation is performed.

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 actionable guidance: after setting the timezone, check site.dst via getSiteSettings and use the schedule's notInDst flag as confirmation. It also states the authentication requirement. It does not explicitly enumerate when to avoid the tool, but the context is clear enough for selection.

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