WhiteOmadaMcp

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

Annotations already declare readOnly, idempotent, non-destructive behavior, so the safety profile is covered. The description adds real behavioral context the annotations cannot: version-dependent log availability on controller 6.2+ and the path base semantics. It does not mention auth requirements or rate limits for this raw passthrough.

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

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

Two tightly written sentences, front-loaded with the core purpose before the version caveat. Every clause earns its place and nothing is padded.

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

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

For a raw passthrough GET with no output schema and an undocumented nested query object, the definition should explain the query parameter format and path conventions more fully. It covers the base URL and the key version-selection rationale, but leaves the caller to guess query serialization.

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 'path' is relative to /openapi/v1/{omadacId}, which is genuinely useful, but leaves the 'query' object (nested) entirely unexplained, as well as how omadacId is obtained.

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

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

States a specific verb (GET), resource (arbitrary Open API v1 path), and the base it is relative to (/openapi/v1/{omadacId}). The v1 vs v2 framing makes it clearly distinguishable from the entire v2_* sibling family.

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 when v1 is required: it is the ONLY version returning event and audit logs on controller 6.2+, with measured evidence (88,522 vs 0). It does not explicitly say when to prefer the v2_* siblings instead, so routing is implied rather than fully closed.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered. The description adds useful context that this is the alert-flagged subset of events, but says nothing about pagination, default limits, or the default time window.

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 resource identity before listing filters, with no filler. It is efficient, though the parenthetical clarification slightly interrupts the filter enumeration.

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

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

For a read-only listing tool with no output schema and annotations covering safety, the core identity and most filters are conveyed. Still, the omission of limit and siteId and the absence of default/pagination behavior leave gaps for an agent invoking 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 carries the burden and does name most filter dimensions: archived/unarchived, level, module, time window (hours), and search. However it omits limit and siteId entirely and gives no value formats, enum meanings, or defaults for the filters it does name.

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 ('Site ALERT log') and clarifies its scope as the subset of events flagged as alerts, which distinguishes it from the v2_events sibling. The verb is implicit (a log to be listed/retrieved), so it is clear but not maximally sharp.

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

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

It implies the tool is for browsing alerts but gives no explicit when-to-use guidance, prerequisites, or named alternative such as v2_events for the full unfiltered event stream. An agent must infer the routing decision from the word 'subset' alone.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuine value beyond the schema by clarifying values are returned in 'REAL UNITS' and enumerating the returned payload, which matters since no output schema exists.

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

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

A single dense sentence, front-loaded with the scope ('Per-AP everything') and ending with the one actionable parameter rule. The long enumeration is informative rather than wasteful.

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?

Describes the return payload because no output schema exists, which is important. But it omits any explanation of siteId and does not indicate pagination or defaults, leaving a small but real gap for a two-parameter read tool.

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

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

Schema coverage is 0%, so the description carries the burden. It explains apMac semantics ('omit for all APs') but says nothing about siteId, leaving half the parameters 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 enumerates the per-AP radio facets returned (channel/width/power, load balance, WMM, OFDMA, mesh, etc.), making it clear this is a getter for AP radio configuration. It implicitly contrasts with mutation siblings like v2_set_ap_radio, but never states an explicit verb or sibling differentiation.

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

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

'Omit apMac for all APs' gives a conditional usage rule for one parameter. However, there is no guidance on when to choose this over v2_rf_health, v2_channel_util, or v2_set_ap_radio, so usage 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 declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and closed-world, so the safety profile is covered. The description adds what fields are returned (actor, IP, old/new values), which is useful content context, but it says nothing about pagination, time defaults, rate limits, or volume caps.

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

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

Two tight sentences, front-loaded with the core content and ending with the sibling distinction. 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?

With no output schema and zero parameter description coverage, the definition should at least explain what hours/limit/siteId control. It only explains the return content conceptually, leaving the agent unable to call the tool correctly with non-default arguments.

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% for three parameters (hours, limit, siteId), so the description carries the full burden of explaining them and explains none. There is no hint about what hours window, limit bound, or siteId scoping do or what their defaults are.

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 resource (AUDIT log) and its content precisely: who changed what, source IP, and old/new values. It also explicitly distinguishes itself from the closest sibling, v2_events ('separate from events'), so an agent can route without opening either schema.

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

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

The description names an alternative (v2_events) and asserts this is a different kind of trail, which gives a clear selection rule. It stops short of a full when-to-use statement (e.g., no guidance on when to prefer v2_security_audit or v2_radar_audit), so it lands just below the top band.

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

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

Annotations already declare readOnly, idempotent, and non-destructive, so the safety profile is covered. The description adds genuinely useful behavioral context beyond that: the 30-55 point natural variance and the warning that a single reading or short baseline is unreliable. It does not cover permissions or output shape, but the annotations remove most of the 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?

Two sentences, front-loaded with the core action and output before the usage advice. The phrasing is slightly editorial ('will let you claim any result you like') but each sentence carries actionable 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 3-param read tool with no output schema, the description supplies the return metrics (mean/median/min/max per channel) and the measurement protocol. The only real omission is clarifying the siteId parameter and the odd fact that no parameter is required.

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 67%, with siteId undocumented in both places; samples and intervalSec carry their defaults in the schema. The description says nothing about sampling count, interval, or which site the samples belong to, so it does not compensate for the gap. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('Sample 2.4/5 GHz channel utilisation over time') plus what is returned (mean/median/min/max per channel). It does not name or distinguish itself from close siblings like v2_rf_health, v2_interference_audit, or v2_rf_planning, so an agent must infer the boundary.

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

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

Gives a clear usage condition: run BEFORE and AFTER any RF change. It explains why (band variability) but offers no explicit when-not rules and does not route to an alternative tool for related RF questions.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the burden is lower. The description adds a genuinely useful operational caveat: it relies on the v1 log API and is "the only one that returns events on 6.2+", which flags a data-availability constraint an agent would otherwise not know. No auth or rate-limit detail, hence not a 5.

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

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

Three short sentences, front-loaded with the resource and return contents, then the diagnostic value, then the API constraint. No redundant restatement of the name or 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 read-only tool with no output schema, the description usefully enumerates what comes back (AP, channel, band, disconnect frequency), so an agent knows what to expect. It is light on the one ambiguous parameter (siteId) and gives no pagination or time-window bounds beyond the default.

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 33% (only `days` is described, with its default). The description partially compensates by tying the output to "a given client" (mac) and "over N days" (days), but says nothing about siteId or how mac should be formatted. With low coverage the description should do more, so baseline-plus is not earned.

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: the full association history of a given client over N days, enumerating the returned dimensions (AP, channel, band, disconnect count). This clearly separates it from generic siblings like v2_clients, but it does not explicitly name the closest alternative (e.g. v2_past_connections or v2_client_survival), so an agent must infer the distinction.

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

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

The description gives explicit diagnostic context – "how you tell a band-steering problem from a roaming problem from a device that simply drops" – which tells the agent when this tool is the right choice. It offers no exclusions or named alternatives for cases where another history tool would be better, so it falls short of a 5.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, non-destructive, closed-world). The description adds genuine non-obvious context beyond them: this build's endpoint carries NO RSSI, SSID, AP or rate data, and explicitly says so rather than inventing it. That up-front data-availability caveat prevents an agent from fabricating or requesting fields that won't exist.

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

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

Front-loaded with the returned field list, then the data-availability caveat, then the mac usage note — a logical ordering with no filler. Slightly dense but every sentence carries information.

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

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

With no output schema, the description usefully enumerates returned fields and warns which fields are absent, which is exactly what an agent needs here. The remaining gap is the undocumented limit and siteId parameters, which the description does not cover.

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% — mac has a description, while limit and siteId are bare. The description meaningfully adds to mac (single client's full detail: vendor, OS, device type, IP settings, rate limit), but says nothing about limit (pagination?) or siteId (scoping?), so it only partially compensates for the coverage gap. Baseline 3.

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

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

The description names the resource (known-client list) and enumerates the exact fields returned (name, MAC, vendor, wired/wireless, VLAN, traffic totals, last seen, blocked state), so an agent knows precisely what this returns. It does not explicitly name alternatives like v2_client_history or v2_past_connections, which share the client domain, 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?

Usage guidance is implicitly encoded via the mac conditional: 'Pass a mac to get that one client's full detail.' That tells the agent how to switch between list and single-record modes, but it never states when to prefer this over sibling client-history/connection tools, so context is only partial.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered. The description adds real behavioral context beyond that: the operation is temporally two-phase (snapshot, wait, re-check) and produces a diff-style result, which an agent needs to know to interpret it correctly.

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

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

Two sentences, front-loaded with the mechanism and followed by the use case. Every clause earns its place; no filler.

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

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

For a low-complexity, no-output-schema, read-only diagnostic, the description covers the mechanism and the trigger well. Its one real gap is the undocumented parameters, which slightly undercuts full completeness.

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 33% and the description never explains band, siteId, or waitSec semantics. 'Wait' loosely implies waitSec (whose default 90 is in the schema) but band scoping and which site is targeted are left entirely to inference.

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 two-phase verb sequence (snapshot, wait, re-check) over a specific resource (wireless clients) and names the output (anything that disappeared). This is clearly distinguishable from siblings like v2_clients or v2_client_history, which read state rather than diff it.

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

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

It gives an explicit trigger — 'Run this after any RF or SSID change' — and states the motivating scenario (silent eviction of an IoT device). It does not name a specific alternative tool or a when-not-to-use condition, so it stops short of a 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context – and it does by disclosing that the output flags risky states such as controller NTP being off and plaintext management. That is security-relevant behavioral detail beyond what the structured fields convey.

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

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

A single front-loaded sentence that leads with the resource and then lists the covered settings. The field list is long but each item earns its place by telling the agent what the call 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?

For a zero-parameter read-only tool with no output schema, the description usefully enumerates the returned configuration areas, effectively standing in for the missing return documentation. Nothing essential to invoking it correctly is absent.

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

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

The tool takes zero parameters, so there is nothing for the description to clarify at the argument level; baseline 4 applies. The enumerated fields are return content, not inputs.

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

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

The description names a specific resource (controller-level configuration) and enumerates its contents, and the 'controller-level' framing implicitly distinguishes it from the sibling v2_site_settings. The only gap is that the verb is implied rather than stated – it reads as a getter only because of the readOnly annotation, not the text.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no alternative sibling is named, even though v2_site_settings, v2_services and v2_log_settings overlap in scope. The scope contrast with site-level settings is only implicit.

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

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

Annotations already declare destructiveHint=true and readOnlyHint=false, yet the description adds substantial behavior: the two refusal conditions (self and Owner/root), the confirm:true gate, and the READ-ONLY MODE fallback that returns the payload instead of sending it. This is far beyond what the annotations convey.

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 destructive verb and resource are front-loaded, and the rationale for being the sole account operation is purposeful rather than filler. The bracketed mode note is compact, though the rationale sentence could be tightened slightly.

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 mutation tool with no output schema and 0% schema coverage, it supplies the key prerequisites, refusals, and mode behavior. The one gap is the undocumented dryRun parameter, which the description does not reconcile with the read-only mode note.

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 carry the load. It explains confirm:true and implicitly constrains username (self/Owner/root rejected), but the dryRun parameter is never addressed and its interaction with the read-only mode is left 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?

States a specific verb (DELETE) and resource (controller account) up front, and explicitly distinguishes itself from the rest of the account surface by noting it is 'the only account operation this server has'. An agent can place it relative to v2_users and the v2_set_* siblings without opening any schema.

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

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

Gives concrete usage constraints: it refuses the logged-in account and Owner/root accounts, and requires confirm:true. It does not name an alternative tool, but there is no competing delete/account-mutation sibling, so the routing is unambiguous.

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

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

Annotations already declare readOnly, idempotent, non-destructive, so the safety profile is covered. The description adds real domain context beyond that: the 30-minute vacate behavior after radar detection and the significance of configured != actual. It stops short of describing the return shape or what a siteId omission does.

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

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

Three sentences, each adding distinct information, with the core comparison front-loaded. Slightly dense but no filler to cut.

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

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

There is no output schema, so the description should ideally indicate what the check returns (e.g., per-radio channel pairs or a flagged list), and it should clarify the undocumented siteId. It explains the domain semantics well but leaves the callable mechanics under-specified.

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

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

The single parameter siteId has 0% schema description coverage, so the description carries the full burden — yet it never mentions siteId, its optionality (0 required), or what scope an omitted siteId produces. The schema name alone has to carry all meaning.

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 on a specific resource: comparing each 5 GHz radio's configured channel against its actual operating channel, plus flagging DFS-channel radios and the 5600-5650 MHz weather-radar sub-band. This clearly distinguishes it from siblings like v2_channel_util and v2_radar_audit, which cover utilization and audit trails rather than an in-the-act configured-vs-actual comparison.

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 diagnostic purpose (detecting a radar event 'caught in the act') but never states when to prefer this tool over v2_radar_audit, v2_channel_util, or v2_interference_audit, nor any prerequisites. Usage is inferable but not spelled out.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds genuine context beyond that: it is a composite aggregation ('in one call') covering eleven distinct diagnostic areas, which tells the agent this is a heavy, wide-scope read rather than a narrow query. It does not mention latency cost, auth scope, or result size.

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 content is dense but front-loaded with the headline claim ('The 6.2 diagnostic surface in one call') before the metric inventory, and the routing sentence is placed last where it belongs. The long comma-separated metric list is necessary given there is no output schema, but it is verbose and could be grouped.

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

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

With no output schema, the description's enumeration of returned diagnostics is exactly what the agent needs and it is thorough. Annotations cover the safety profile. The remaining gap is the unexplained siteId parameter and the absence of any note about call cost or result volume for such a broad aggregation.

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

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

There is one parameter, siteId, with 0% schema description coverage, so the description carries the full burden of explaining it. The description never mentions siteId, its format, or whether omitting it (0 required parameters) scopes to a default site or returns everything. With low coverage and no compensating text, this is a real 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 names a specific resource (the diagnostics surface) and enumerates exactly which metrics it returns, so an agent knows precisely what comes back. It also positions itself against configuration tools with the 'healthy vs configured' framing. It stops short of naming the overlapping siblings it must be distinguished from (v2_rf_health, v2_health_audit, v2_channel_util), so it is clear but not fully 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 closing sentence gives an explicit selection heuristic: use this to answer 'is the wireless actually healthy' rather than 'is it configured correctly'. That is a real when-to-use signal tied to the sibling landscape. It does not name a specific alternative tool or state exclusions within the diagnostic space, so it falls short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds valuable context beyond that — the map is derived from the controller's own GUI bundles and probed live, and it explicitly includes what is NOT available and why, which is meaningful for a discovery 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?

One descriptive sentence plus one short imperative, both front-loaded and free of waste. The build version and provenance are packed in without padding.

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

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

For a read-only discovery tool with an optional filter and no output schema, the description adequately conveys what the tool yields (a verified endpoint map that includes unavailable paths and reasons). It does not describe the shape of the returned data, but otherwise nothing critical is missing.

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

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

Schema description coverage is 100%, so the single optional 'filter' parameter is fully documented in the schema. The description adds no syntax or format detail beyond it, which is the expected baseline when the schema carries the burden.

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

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

The description identifies a specific resource — a verified v2 endpoint map for build 6.2.14.11 — and its provenance (GUI bundles, live probes). It is clearly a discovery/reference tool, though it lacks an explicit verb (list/retrieve) and does not name a sibling to distinguish from, e.g., v2_get.

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?

"Read this before guessing a path" gives clear when-to-use guidance: consult this tool before attempting endpoint discovery by trial. It doesn't name alternatives or state when-not-to-use, but the intended usage context is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds real behavioral value: an empty result is treated as a diagnostic signal rather than as evidence of health. That is the kind of platform-specific behavior annotations cannot express. It omits pagination/default-limit behavior, keeping it from a 5.

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

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

Two compact sentences, filter set front-loaded and the distinctive diagnostic behavior placed last. Nothing is wasted, though the terse enumeration reads slightly like a field list.

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

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

For a 6-parameter read tool with no output schema, the description covers the what and the notable empty-result behavior but leaves the agent guessing about paging, the default look-back interaction, and whether siteId is required. Adequate but with visible 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 17%, so the description carries most of the burden, but it only restates the filter set rather than adding meaning. It gives no guidance on 'limit' (paging is mentioned but not its semantics or default), no 'siteId' scoping requirement, and no search syntax, so the low-coverage parameters remain under-documented.

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

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

States a specific resource (site event log) plus its filter dimensions, which is clear enough to distinguish it from siblings like v2_alerts, v2_audit_logs and v2_log_diagnose. It stops short of explicitly naming those siblings, so it doesn't reach 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?

There is no explicit when-to-use vs when-not guidance, and none of the many adjacent log/diagnostic siblings are referenced. The 'diagnoses an empty result' remark is a behavioral note about results, not routing guidance for picking this tool.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world behavior, so the safety profile is covered. The description adds one useful behavioral fact beyond annotations — 'Returns errorCode triage on failure' — but does not explain what that triage contains, how errors are shaped, or whether paging or auth quirks exist.

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

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

Two short sentences, front-loaded with the core capability and followed by the routing rule and a failure note. There is no filler, and 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 generic escape-hatch GET tool with no output schema, the description covers purpose, fallback usage, and a failure-return hint. However, with 0% schema coverage and a nested query object, it omits enough parameter detail that an agent may need to inspect the schema or experiment 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 must carry parameter meaning. It clarifies that 'path' is relative to /api/v2, which is useful, but it says nothing about the nested 'query' object's structure, expected keys, or encoding, leaving half the parameters 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 states a specific verb (GET) and resource scope (any v2 path relative to /api/v2), and explicitly distinguishes itself from the many typed siblings by saying it is for 'anything the typed tools do not cover.' An agent can immediately tell this is a generic fallback GET tool.

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

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

It gives an explicit when-to-use rule: 'Use for anything the typed tools do not cover.' This directly names the alternative (typed tools) and the condition that selects this tool over them, leaving nothing to inference.

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

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description adds meaningful value beyond that: it discloses the return shape (a ranked list of misconfigurations, each paired with the exact fixing tool call and its blast radius), which is the kind of output behavior an agent needs and cannot get from annotations or the absent output schema.

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

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

Two tightly packed sentences with no filler; the scope and the return contract are both front-loaded and every clause carries information.

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

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

For a read-only audit with no output schema, the description adequately covers the return contract (ranked misconfigurations plus remediation call and blast radius). The remaining gap is the unexplained, non-required siteId parameter and the absence of any note on runtime cost or permissions for a call that scans ten subsystems.

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 single parameter (siteId) is not mentioned in the description at all. It is also not required, so the agent gets no guidance on whether omitting it is valid or what scope results. With low coverage, the description is expected to compensate and 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?

Names a specific verb+resource ('health audit') and enumerates the exact config domains it spans (site settings, controller settings, services, switches, ports, VLAN profiles, radios, SSIDs, VLANs, logs), which sets it apart from narrower audits by scope. It stops short of naming which sibling audits it supersedes or complements, so the agent must infer the boundary from the scope list alone.

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

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

'One-shot audit' implies this is a broad first-pass diagnostic rather than a targeted check, which is usable context. However, with several sibling audit tools present (v2_security_audit, v2_radar_audit, v2_interference_audit, v2_diagnostics), the description never states when to pick this one over them or when a narrower audit is 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?

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds meaningful behavior beyond that: it describes which counters are sampled over a time window and discloses a privacy-relevant side effect (sends lat/lon/radius to a public ADS-B service). It does not discuss the result format or latency, but the added context is substantial.

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

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

Dense but front-loaded, leading with the core value proposition. Some phrasing ('makes every other interference claim a guess') is promotional, but each sentence conveys a distinct capability. Slightly over-packed into one paragraph.

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

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

With no output schema, the description usefully names the underlying metrics that constitute the result, which compensates. However, for a 7-parameter tool it leaves the geolocation and band parameters undefined and omits when-to-use guidance, so it is not fully self-contained.

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 43%, and lat/lon/siteId/band carry no description in either place. The description adds context for the flight check (opt-in, external transmission) but does not clarify the geospatial parameters, band selection, or how siteId interacts with lat/lon. Baseline 3 given partial compensation 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?

States a specific verb and resource ('interference detection' via 'the AP's own radio counters') and explicitly names the metrics it reads (interUtil, busyUtil, txUtil/rxUtil, retry/drop deltas). It draws a sharp line between WiFi-busy and non-WiFi emitters, distinguishing it from siblings like v2_channel_util and v2_radar_audit.

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 positions itself implicitly by claiming other interference claims are 'a guess', and flags the flight-correlation as opt-in. But it never states when to prefer this over v2_channel_util, v2_rf_health, or v2_radar_audit, nor any prerequisites. Usage is implied rather than specified.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds one genuine behavioral trait beyond that — 'Flags networks with snooping off' — but says nothing about scoping or 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?

Two terse sentences with the resource and field list front-loaded and the noteworthy flag behavior last; no filler. It leans on fragments, which is efficient but slightly cryptic.

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

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

For a read-only listing tool with annotations covering safety, the enumerated returned fields largely substitute for the absent output schema. However the siteId scoping gap leaves an agent unsure how 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% and the single siteId parameter is not mentioned at all in the description. With low coverage the description is expected to compensate, and it does not clarify whether siteId is required, what form it takes, 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 phrase 'Every VLAN' states the resource and the scope (all of them), and the field enumeration makes clear this is a read/list operation returning network details. It is distinguishable from siblings like v2_vlan_profiles and v2_services, though it never names those alternatives 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?

There is no statement of when to use this tool versus alternatives such as v2_vlan_profiles or v2_set_lan_igmp, and no prerequisites or exclusions. The listing intent is only implied by 'Every VLAN'.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds behavioral value by disclosing that it fans out across every log surface in a single call and includes non-obvious checks (counter-vs-cap, retention, notification catalogues, syslog state), which sets expectations about scope and cost. It stops short of describing return shape or any auth/rate considerations.

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

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

It front-loads the triggering question ('Why is the log empty?'), then answers it in two dense, waste-free sentences. The enumerated surfaces are long but each adds distinct information, and the closing caveat is well-placed.

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

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

For a complex multi-surface diagnostic with no output schema, the description conveys what evidence is gathered and when to invoke it, which is close to sufficient. It does not describe the shape of the response (e.g., per-surface verdicts), so an agent cannot predict the return structure before calling.

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. With 0 required parameters, it is unclear whether omitting siteId yields an all-sites diagnostic or an error. The parameter name is a conventional identifier, so the gap is moderate rather than severe, but the description does not compensate for the absent 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 specific purpose (diagnose why logs are empty) and enumerates the exact evidence surfaces it aggregates: events, alerts, audit, stored-log counter vs. cap, retention policy, notification catalogues, and remote syslog state. The 'in one call' framing implicitly distinguishes it from the individual sibling tools (v2_events, v2_alerts, v2_audit_logs, v2_log_settings, v2_notifications) that cover the same surfaces one at a time.

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

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

It gives clear situational context: 'Use this before concluding a quiet network — an empty log and a healthy network look identical.' This tells the agent exactly when the tool is warranted. It does not, however, explicitly name alternatives or when-not-to-use conditions (e.g., prefer the narrower log tools when you already know which surface to inspect).

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so safety behavior is covered. The description adds useful scope context by enumerating what is included in the response, but says nothing about permissions, rate limits, or whether settings are site-scoped.

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

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

Two tightly written sentences with no filler, and the content enumeration is front-loaded before the rationale. Nothing is wasted, though the inventory is dense.

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

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

With no output schema, the description reasonably substitutes by listing what the response contains, which is genuinely helpful. However, it omits the siteId scoping and any indication of how results are filtered, leaving an agent to guess at invocation semantics.

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

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

Schema coverage is 0% and the single siteId parameter is never mentioned in the description, so there is no indication of whether the call is site-scoped or returns global settings. With one undocumented parameter, the description fails to compensate for the schema 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 names a specific resource (log settings) and enumerates exactly what the payload covers: site alert switch, syslog target, retention policy, log levels, webhook targets, and stored-log count vs cap. It implicitly reads rather than names a verb, but an agent can distinguish it from v2_log_diagnose or v2_audit_logs by the configuration-oriented scope.

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?

"Explains an empty log rather than leaving it mysterious" hints at the diagnostic scenario where this tool is the right choice, but it never names an alternative sibling or states an explicit when-not-to-use condition. Usage is implied rather than prescribed.

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

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

Annotations already cover the safety profile (readOnlyHint=true, idempotentHint=true, destructiveHint=false). The description adds meaningful context beyond that: it reports credential-set presence "never the values", preferred API selection, and transport reachability — useful disclosure for a diagnostic tool, though it doesn't describe response shape or failure 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?

Two sentences, front-loaded with the subject of the report and ending with the actionable call condition. The middle enumeration is slightly list-heavy but every item earns its place by naming what is returned.

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

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

With no output schema and no parameters, the description carries the burden of saying what comes back, and it enumerates four distinct pieces of configuration state plus the failure-diagnosis use case. Adequately complete for a zero-parameter introspection tool, though it could note that all four groupings are returned together.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline for a no-parameter tool applies.

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

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

The description states concretely what this tool reports: read-only vs write-enabled mode, loaded credential sets, preferred API, and v1/v2 transport reachability. It effectively distinguishes itself from data-fetching siblings like v2_status and v2_get, though it uses no explicit verb (e.g., 'Get the server mode') and its opening phrase is somewhat abstract.

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?

'Call this to explain why a write was refused' gives a clear, concrete triggering condition for invocation. It stops short of naming alternatives or when-not-to-call guidance, so it is clear context without full routing rules.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety bar is low. The description usefully adds that controller and site scopes are separate catalogues, but its framing as 'the real alerting control' sits uneasily against a read-only annotation, and it says nothing about the schema's `restoreDefaults`/`confirm` POST 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?

Three dense, front-loaded sentences that lead with what the catalogue is. The editorial phrasing ('This is the real alerting control') is a slight dilution, but overall it earns its 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 4-parameter tool with no output schema, the description covers the conceptual model (separate controller/site catalogues) but leaves the mutating-adjacent parameters (`confirm`, `restoreDefaults`) unexplained, which matters given the readOnlyHint and a POST-based restore command.

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%, so the description should compensate but largely does not. It conceptually explains the scope split (controller vs site), which adds meaning for the `scope` enum, yet `siteId`, `confirm`, and `restoreDefaults` are never addressed 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 gives a specific resource (the notification catalogue) and enumerates what it covers: which events are recorded, which raise alerts, which send mail/webhook. It also explicitly distinguishes itself from the `alert.enable` field in site settings. It stops short of disambiguating against close siblings like v2_alerts, v2_events, or v2_log_settings.

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

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

It implies usage (inspect/control alerting) and gives one negative routing hint – that the site-settings `alert.enable` field is not writable and does not correspond to this page – but it never states plainly when to choose this tool over alternatives, nor prerequisites such as when a siteId is needed.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered structurally. The description adds the returned field set, which is useful context, but says nothing about the default look-back window, result volume, or pagination 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?

Two short sentences with no filler; the field inventory is front-loaded and the usage cue follows. It could arguably compress the field list, but nothing is wasted.

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

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

For a read-only lookup with no output schema, listing the returned fields is the right move and the annotations carry the safety story. Still missing for a 3-parameter tool: meaning of 'siteId' and 'limit' and any hint about default scope, so the definition is adequate but leaves real 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 only 33%: 'hours' is documented in the schema (default 24) but 'limit' and 'siteId' have no description anywhere. The description never mentions any of the three parameters, so it does not compensate for the coverage gap that would tell an agent how to scope site and result size.

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 noun phrase 'Historical client sessions' names the resource and the field list (MAC, SSID/network, AP, duration, traffic, disconnect reason) makes the payload concrete, so an agent knows what data comes back. However, it carries no verb and no differentiation from the near-identical sibling v2_client_history, leaving the boundary between the two ambiguous.

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 quoted trigger '"why did this device drop"' is a real task-level cue that implies when to reach for this tool. It stops there: no when-not condition, no mention of v2_client_history or v2_client_survival as alternatives, and no guidance on choosing this over the general client tools.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered. The description adds the 'live' freshness framing and the contents of the counters, which is useful. It says nothing about auth requirements, rate limits, or how a switch with no live data behaves.

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

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

Two sentences, zero waste. The high-value content list is front-loaded and the use-case tag follows as a scannable closer. Nothing is repeated from the annotations or schema.

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

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

With no output schema, the description correctly enumerates the returned counters, so the return side is reasonably complete. The input side is not: two 0%-documented parameters are left unexplained, and no behavior for missing/ambiguous scope is given. Adequate but with a clear input-side gap.

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

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

Schema description coverage is 0% and the description mentions neither siteId nor switchMac. With both parameters optional and no required field, an agent cannot tell from the description how to scope the query (site-wide vs single switch) or whether switchMac filters within siteId. This is the definition's weakest point.

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 resource (per-port counters) and enumerates the exact payload: link state, tx/rx bytes/packets, errors, drops, and PoE draw/budget. An agent knows what it returns. However, it never names or contrasts with the nearby siblings v2_switch_stats and v2_switch_ports, so the differentiation from those must be inferred.

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 closing line 'is a cable or a device misbehaving' gives a concrete diagnostic scenario, which is a clear when-to-use context. It stops short of explicit alternatives (e.g., use v2_switch_stats for switch-level totals) or any when-not condition, so it lands at 4 rather than 5.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile. The description adds real behavioral context beyond that: it performs a live watch, correlates uptime with radar hits, reads the v1 event log, and explicitly claims to state its own limits. It still does not describe the returned evidence shape or runtime cost of the live watch.

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?

Four sentences, front-loaded with the value proposition and then the mechanics; it is well-sized and every sentence describes a real action. The opening 'settle a DFS argument with evidence rather than opinion' is slightly rhetorical but still functional framing.

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

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

For a read-only audit tool with three parameters and no output schema, the description covers the major behaviors and even flags its own provability limits. It is close to complete, with the remaining gap being the format of the evidence it returns and the undocumented siteId.

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%, and the description itself names no parameters. The schema already explains days (default 7) and watchMinutes (default 5, 0 to skip), so the description adds nothing about parameter behavior, and siteId is undocumented in both places.

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

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

The description gives a specific resource (DFS radar/radio audit) and enumerates the concrete actions: reports DFS-channel radios, live-watches for channel changes, checks AP uptime, sweeps the event log. The purpose is clear, but it never distinguishes itself from the sibling v2_dfs_check, leaving an agent to infer the split.

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

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

Usage is only implied through the narrative framing ('settle a DFS argument') and the schema note that watchMinutes=0 skips the live watch. There is no explicit when-to-use/when-not guidance and no reference to the obvious alternative, v2_dfs_check.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so safety is covered. The description reinforces this ("without touching anything") and usefully discloses the breadth of what is collected, which is real added context. It says nothing, however, about cost/latency of such an aggregate query or any scoping 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?

Two sentences, front-loaded with the concrete data returned, no filler. The metric list is long but each item is informative rather than decorative.

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

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

With no output schema, the description does the necessary work of enumerating return fields, which is a genuine strength. It falls short on the remaining gaps: the undocumented siteId and the absence of any routing among the numerous overlapping diagnostic/audit 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?

One parameter (siteId) with 0% schema description coverage, and the description never mentions it or explains whether omitting it falls back to a default site. With coverage this low the description is expected to compensate, and it 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 names a specific resource (RF health/diagnostics) and enumerates the returned metrics — per-channel AP/client counts, channel utilisation, per-AP interference, client RSSI distribution, and controller wireless experience index history — so an agent knows exactly what data it yields. It does not differentiate from the closely overlapping siblings (v2_channel_util, v2_interference_audit, v2_health_audit, v2_rf_planning), which is what keeps it out of 5 territory.

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 closest thing this build has to a wireless test" implies the usage context — a broad, single-shot RF check-up rather than a targeted audit — but usage is only implied. No explicit when-to-use, when-not-to-use, or named alternatives among the many audit/channel/util siblings 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 adds high-value behavior the annotations omit: a run re-plans channels on every AP, applies them, and overrides manual channel choices. However, this directly conflicts with the declared readOnlyHint=true / destructiveHint=false, so the hint set can no longer be trusted and the agent must treat the metadata as inconsistent.

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: identity, what it reads, how to trigger, then a front-loaded warning. Every sentence carries information and nothing is padded.

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

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

With no output schema, the description usefully enumerates what is returned (current plan settings, run history with before/after experience index, last-run status), which an agent needs. It is only incomplete on the undocumented siteId/confirm parameters.

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 33% (only run is documented). The description adds the trigger semantics of run:true but never explains siteId or the confirm:true requirement that the schema mentions, so it 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?

States a specific verb+resource ('AI RF Planning', reads plan settings/run history/status, can trigger a run) and scopes it precisely as the controller's channel/width/power optimiser, which distinguishes it from adjacent siblings such as v2_rf_health or v2_channel_util.

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?

Makes the branch condition explicit: read by default, or pass run:true to trigger a new planning run. It does not name a competing sibling tool or state when-not-to-use, so it falls short of a full 5.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the bar is lower. The description adds a genuinely valuable behavioral fact beyond annotations: the result set is empty until a scan has run, which affects how an agent should interpret an empty response. It does not describe pagination or result limits.

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

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

Two tight, front-loaded sentences: first the resource and returned fields, then the availability precondition. No filler, and the most important caveat is stated last but still compact.

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

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

For a read-only list tool with no output schema, the description adequately conveys content and the scan precondition. It falls short on the siteId parameter's meaning and any scoping behavior, leaving a gap for an agent deciding whether to pass a site.

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 sole parameter siteId has 0% schema description coverage and is never mentioned in the description, so nothing explains whether it scopes the query to a site or how results behave when it is omitted. With low coverage the description should have compensated, and it 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?

States a specific resource (neighbouring/rogue APs) with a clear scope qualifier ("seen by your own APs") and enumerates the returned fields (SSID, BSSID, channel, signal, security). An agent can tell what it returns, though it does not explicitly contrast with related siblings like v2_security_audit or v2_interference_audit.

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

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

Usage is only implied by the resource name; there is no explicit when-to-use or when-not-to-use guidance and no alternatives named. The one useful usage signal is the precondition "Empty until a scan has run," which tells the agent results depend on a prior scan.

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

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

Annotations already establish this is a safe, idempotent, read-only, closed-world operation, so the bar is lower. The description adds genuine domain value beyond that: it discloses the analysis logic (flagging PMF Mandatory=1 on WPA2-PSK and WPA2/WPA3 transition mode as downgrade-vulnerable), which tells the agent what the output actually means rather than just that it is a read.

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

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

It is front-loaded with the highest-value content: the table's columns come first, then the flagging rules. Two sentences with no filler. The second sentence is dense, but every clause carries concrete technical detail rather than padding.

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

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

There is no output schema, so the description carries the burden of describing returns, and it does so by enumerating the table columns and the flagged conditions. The main remaining gap is the siteId scoping and required-parameter behavior, but for a single-parameter read tool the coverage is otherwise solid.

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 never mentions the sole parameter siteId or its scope (whether it is optional, what happens if omitted, how the table is scoped). The parameter name is fairly self-explanatory, which keeps this from being worse, but the definition adds no semantic value over the schema.

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

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

The description states a specific verb and resource: it audits the security posture of every SSID and returns a defined table of fields (WPA version, PMF mode, 802.11r, guest isolation, band, VLAN, broadcast). This is far more specific than a bare 'audit' name. It does not, however, name or contrast any sibling such as v2_ssids, so an agent gets a clear purpose but no explicit differentiation.

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

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

Usage is implied: you would call this to assess SSID security configuration and find destabilising combinations. But there is no explicit when-to-use, when-not-to-use, or named alternative (e.g., 'use v2_ssids for a plain listing, use this for a security-focused view'). The agent must infer the routing.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world semantics, so the safety profile is covered. The description adds genuinely useful non-obvious behavior: it 'flags insecure or unset services', telling the agent the response carries security annotations rather than raw config alone.

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 scoping statement 'Every site service in one call' is correctly front-loaded, and the second sentence about security flags earns its place. However, the 16-item enumeration is a long run-on list that could be trimmed or organized, inflating length without adding decision-relevant 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?

For a read-only aggregate tool with no output schema, the description adequately conveys what data is bundled and that security flags are included, so an agent can decide to call it. It falls short on the siteId parameter semantics and on any indication of response size or structure.

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

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

The single parameter siteId has 0% schema description coverage and is never mentioned in the description. With one undocumented param the description should compensate by explaining scoping (whether siteId is required, what happens if omitted), and it 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 names the resource (all site services) and enumerates the concrete service types it aggregates, so an agent can tell it apart from narrower siblings like v2_set_service or v2_ssids. The verb is only implied ('in one call') rather than stated, but the intent to retrieve an aggregate snapshot is 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?

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives (e.g. v2_set_service for mutation, v2_security_audit for deeper security posture). The agent must infer usage from the service list alone.

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

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

Annotations already declare non-destructive and idempotent behavior, so the bar is lower, yet the description adds genuine value: the maxClients>=5 validation guard and the force escape hatch, plus a 'READ-ONLY MODE' that returns the payload rather than sending it. The read-only mode is not tied to the dryRun parameter, leaving a small 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?

Three tight fragments with no filler, and the highest-value constraint (the guard) is front-loaded after the purpose statement. Structure is appropriate for a short 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 7-parameter mutation tool with no parameter descriptions at all and no output schema, the description only covers the guardrail behavior. An agent still lacks semantics for four of the seven inputs, so the definition is not complete enough to invoke 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% across 7 parameters, so the description carries the full burden. It only explains maxClients, force, and implicitly dryRun; band, apMac, enable, and siteId remain completely undocumented in both schema and 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?

States a specific verb and resource ('Fix or set per-radio load balancing'), and the 'per-radio' phrasing scopes it against the wider family of v2_set_* tools. It does not, however, name a sibling it overlaps with (e.g. v2_set_ap_radio), so differentiation is left to inference.

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

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

Usage is implied by the guard note ('refuses maxClients under 5 unless force:true'), which tells the agent when force is required, but there is no explicit when-to-use/when-not guidance and no named alternative among the many sibling setters.

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

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

Goes well beyond the annotations: the write silently returns success but reverts on read-back, the field is absent from all 381 GUI modules, and the tool will report 'REVERTED'. It also discloses a read-only mode that returns the payload instead of sending it. The destructiveHint/readOnlyHint annotations describe the nominal capability, which the description does not deny – it only documents that the effect does not persist – so this is added context, not a contradiction.

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

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

Front-loaded with the critical warning in the first clause, and every sentence carries load (failure evidence, field invisibility, alternative, mode note). It is a dense run-on, but no sentence is 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 mutation tool with no output schema and six undocumented parameters, the description compensates unusually well on outcome and behavior – it tells the agent the call will appear to succeed and report REVERTED, and what to do instead. What remains missing is any parameter-level meaning, which matters only if an agent still chooses to invoke it.

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

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

Six parameters with 0% schema description coverage and no explanation of any of them in the description. The 'READ-ONLY MODE: returns the exact payload instead of sending it' note loosely gestures at the dryRun flag but never names it, and apMac/allAps/siteId/enable/broadcast are entirely unexplained, so the description barely 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 never plainly states 'sets the AP management SSID' – the purpose has to be inferred from the tool name plus the mention of 'mgtSsidSetting' and 'no site-level control exists'. It does distinguish this from the regular-SSID siblings by naming a specific read-only field, but a deprecation notice is doing most of the work here rather than a purpose statement.

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

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

Explicit when-not-to-use guidance: 'MEASURED NOT TO WORK on 6.2.14.11', 'no site-level control exists', and 'Kept only so the attempt is recorded honestly rather than repeated'. It also supplies a concrete alternative action ('Settle it with a phone scan instead'), leaving nothing to inference about whether to call it.

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

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

Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds real behavioral context the annotations don't: DFS/weather-radar warnings, read-back verification of the applied change, and the read-only payload-return mode. These are operationally important traits an agent needs before invoking a radio reconfiguration.

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

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

Front-loaded with the action and the most decision-relevant detail (real units), followed by warnings and verification. Sentences are dense and earn their place, though the bracketed read-only note is a bit tacked-on in placement.

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?

No output schema exists, and the description covers behavior, warnings, and verification adequately for a mutation tool, but with 7 parameters at 0% schema coverage the parameter picture is incomplete. It is sufficient to attempt a call but not to fully specify one.

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% across 7 parameters, so the description carries the burden. It usefully clarifies units for channel and widthMHz and implicitly explains the dryRun/read-only behavior, but leaves apMac, band, siteId, and txPowerDbm entirely 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?

States a specific verb (Set) and resource (AP radio) plus the exact fields it controls: channel, width, and tx power. The 'REAL UNITS' framing and the explicit '(channel 100, widthMHz 40)' example make the intent unambiguous and separable from read-only siblings like v2_ap_radios.

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 never says when to reach for this tool versus alternatives (e.g., v2_rf_planning, v2_ap_radios, or the other v2_set_ap_* tools). Usage is only implied by the tool name; there are no prerequisites, exclusions, or routing hints.

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 cover the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavioral context: it does NOT emit MBO/OCE 'cannot handle new STA' frames, and it warns of the disconnect risk. The READ-ONLY MODE note aligns with the dryRun parameter and the non-readOnly annotation rather than contradicting 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?

Purpose and warning are front-loaded and every sentence carries weight, though the TP-Link quotation and the bracketed READ-ONLY note add some flourish that could be trimmed without losing 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 6-parameter mutation tool with no output schema and modest schema coverage, the description supplies the key semantic context (threshold behavior, dry-run, disconnection side effect) and safely routes the agent to a sibling, leaving only minor parameter detail to the schema.

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

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

Schema description coverage is only 33%, so the description should compensate more. It adds real meaning for thresholdDbm (set below the weakest signal to keep) and implicitly for band, and explains the dry-run behavior, but apMac, siteId, and enable are left to the schema.

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

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

States a precise verb+resource: 'Set the RSSI threshold that disassociates a client clinging to a weak AP.' It further grounds the purpose in the concrete problem (sticky clients) and explicitly contrasts its behavior with the sibling nonStickRoaming, so an agent can distinguish it without opening schemas.

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

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

Gives explicit when-to-use (fix for sticky clients), when-to-avoid (⚠ set it BELOW the weakest signal you still want to keep), and a named alternative (nonStickRoaming) with the condition that separates them (frame emission feeding Android's blocklist).

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 cover safety (destructiveHint=false, idempotentHint=true), but the description adds real value beyond them: it locates the state in ssidOverrides[].ssidEnable, clarifies the write is per-AP and on-air-immediate, and documents a read-only/dry-run mode that returns the payload instead of sending it. Permissions and error behavior remain unstated.

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, front-loaded with the core action and scope, then the mechanism, then use cases. No padding, though the bracketed mode note is slightly cramped against the usage sentence.

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

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

With no output schema and annotations that only carry safety hints, the description covers the essential semantics of a per-AP mutation (idempotency implied, dry-run path, where state lives). It is short of complete because multi-param addressing (apMac vs apName vs siteId) is never addressed.

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 17% and six parameters are present, yet the description only alludes to dryRun via the READ-ONLY MODE note and never explains apMac, apName, siteId, or ssidName. It does not compensate for the schema gap; the ssidOverrides[].ssidEnable reference is a data-shape pointer, not parameter guidance.

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 precise verb pair (enable/disable) and a tightly scoped resource (one SSID on ONE access point), and explicitly distinguishes itself from a global toggle by noting there is no global enable field. An agent can separate it from v2_set_ssid and v2_set_ssid_broadcast without opening a schema.

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

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

Gives two concrete use cases (keep an SSID in one room, cut beacon overhead on a busy band) and forecloses the wrong mental model by saying the on-air state is per-AP in ssidOverrides[].ssidEnable. It does not explicitly name the sibling tool to use for global SSID changes, so it falls short of 5.

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

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

Annotations already declare the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), and the description adds genuinely new behavioral context: the failure mode where snooping without a querier halts multicast, plus the dry-run payload behavior. It does not describe permissions or rate limits, but the risk disclosure is valuable beyond the annotations.

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

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

Three short, front-loaded sentences: purpose first, then the risk warning, then the dry-run note. Every sentence carries information, though the bracketed read-only-mode phrasing is slightly awkward and could be tighter.

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 5-parameter mutation tool with no output schema and low schema coverage, the description covers the critical behavioral hazard and the dry-run return behavior well. The remaining gap is siteId and per-toggle semantics, which leaves it slightly 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 coverage is only 20% (networkName is the sole documented param), so the description carries the burden. It maps 'IGMP and MLD snooping' to igmpSnooping/mldSnooping and explains dryRun via the read-only-mode note, but siteId and the toggle semantics remain unexplained in both places.

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 pair (enable/disable) and precise resources (IGMP and MLD snooping) scoped to a VLAN. This is unambiguous and clearly distinct from sibling mutators like v2_set_lan_networks or v2_set_site_feature without needing to name 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?

It gives an important prerequisite (an IGMP querier must exist on the VLAN) and a post-action verification step (test TVs and speakers), which is real usage guidance. However, it never says when to choose this over alternative tools or when not to enable it, so guidance remains implied 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?

Annotations only state readOnly=false, idempotent=true, destructive=false; the description adds genuinely non-derivable behavior: the trunk-port refusal, the force override, and the read-only mode that returns the payload instead of applying it. The blast-radius warning about partitioning the network is exactly the kind of operational context an agent cannot infer from structured fields.

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

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

Front-loaded with capabilities, then safety warning, then behavioral caveats—logical ordering with no filler. The feature enumeration is dense but earns its space; the only minor cost is a long single sentence before the warning.

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 17-parameter mutation tool with no output schema and sparse schema descriptions, the definition covers purpose, safety constraints, and the dry-run/force escape hatches well. Residual gaps: no mention of what a successful response contains and no sibling routing for bulk operations.

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 18% across 17 params, so the description has to compensate, and it does by grouping the params into meaningful feature clusters (loopback detection, STP on/off, edge-port, BPDU/root guard, storm-control thresholds, isolation, PoE, disable). It also explains force and dryRun semantics, though it doesn't add units or validation detail for the storm thresholds—those rely on the schema.

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

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

The description opens with a specific verb and resource ('Set one switch port') and enumerates the exact feature set the tool controls (loopback detection, STP/edge port/BPDU guard, storm control, isolation, PoE, enable/disable). The 'one' scope also implicitly separates it from the bulk sibling v2_set_ports_bulk and from v2_set_port_pvid / v2_set_port_profile.

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

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

It gives a strong when-not-to guidance ('NEVER enable loopback detection on a switch-to-switch trunk') and a precondition for sensitive cases ('refuses trunk ports unless force:true'). What's missing is explicit routing to alternatives such as v2_set_ports_bulk for multi-port changes, so usage context is clear but not comparative.

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?

Adds real behavioral value beyond the annotations: the refusal guard on inter-switch trunks and its consequence ('partitions the network'), plus the fact that dryRun returns the payload instead of sending it. Annotations only cover readOnly/idempotent/non-destructive; the dangerous-edge-case and dry-run semantics are purely from the description. The '[READ-ONLY MODE]' phrasing is slightly ambiguous next to readOnlyHint=false, but it clearly describes the dryRun path rather than the tool itself.

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 clauses with no filler, and the highest-risk information (the network-partitioning trunk guard) is front-loaded after the core action. The heavy em-dash/bracket punctuation makes it slightly dense, but nothing is wasted.

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

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

For a mutating, 6-parameter tool with no output schema, the description covers the risky behavior well but leaves parameter meanings and any return shape unaddressed. An agent can decide whether to call it, but cannot confidently fill in the arguments without guessing.

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% across 6 parameters, so the description must carry the load and it largely does not: switchMac, port, profileName and siteId are entirely unexplained. Only 'force' gets meaning (trunk override), and dryRun is only implied by the bracketed read-only note.

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 ('Bind a switch port to a VLAN port profile') and adds intent ('the real fix for "every port permits every VLAN"'), which separates it conceptually from generic port tools like v2_set_port and v2_set_port_pvid. It does not name any sibling explicitly, so it stops short of the 5 bar.

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 clear context for when this is the right action (fixing permissive VLAN behavior) and a precise condition for the dangerous case ('Refuses to change an inter-switch trunk unless force:true'). It never names an alternative sibling (e.g. v2_set_port_pvid) for the case where a different tool is appropriate.

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

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

Adds genuinely useful behavior beyond the annotations: the tagged VLAN list is preserved unless replaced, trunks are refused without force:true, and read-only mode returns the payload instead of sending it. Annotations only declare idempotent/non-destructive; the description adds the trunk-refusal precondition and preservation semantics. Could go further on what happens to existing untagged membership.

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

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

Front-loaded with the core definition and effect, then progressively adds edge cases (tagged preservation, trunk refusal, read-only mode). Efficient overall, though the parenthetical read-only banner is slightly jarring mid-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 mutation tool with no output schema and incomplete schema coverage, the description covers the important semantics: what changes, what's preserved, when it refuses, and the dry-run behavior. Missing coverage of the siteId/switchMac addressing params is the main gap.

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

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

Schema coverage is low (29%), so the description must compensate, and it does for two key params: it defines pvidNetworkName as a VLAN name or tag ('MGMT' or '40' is in the schema too) and clarifies portName renames the port. It documents force's effect (allow trunks) in prose rather than repeating the boolean, and hints at dryRun via read-only mode. Still, port/siteId/switchMac are 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?

States a specific verb (Set) and resource (switch port's PVID) and explains what PVID actually means ('the VLAN an UNTAGGED frame lands on'), which makes the effect on untagged traffic unambiguous. This distinguishes it from more general siblings like v2_set_port or v2_set_ports_bulk.

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 clear usage context via the concrete scenario of a laptop plugged into a port and the rescue/console port case, plus an explicit restriction: refuses inter-switch trunks unless force:true. It lacks explicit 'when to use this vs v2_set_port_profile / v2_set_ports_bulk' routing, so it falls short of 5.

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

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

Annotations already give the safety profile (readOnlyHint=false, idempotentHint=true, destructiveHint=false), so the bar is lower, yet the description still adds real value: the trunk guard, per-port write-and-verify behavior, the blast-radius concept ('dead' = zero blast radius), and the read-only/dry-run payload behavior. Strong added context beyond structured fields.

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

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

Front-loaded with the core action, followed by selector semantics and the operational rationale. Mostly earns its sentences, though the '30-second convergence outage into no outage' framing is slightly promotional for a tool description.

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 17-param mutation tool with no output schema and near-zero schema coverage, the description covers selection, the STP use case, verification, and dry-run behavior, but leaves many behavioral flags undocumented. Adequate for the headline workflow but incomplete for the full parameter surface.

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 17 parameters and only 6% schema coverage, the description must carry most of the parameter burden. It explains the selector enum values ('access'=non-trunk, 'dead'=link down non-trunk, 'all') and the edgePort workflow, but leaves the many boolean flags (stp, force, disable, bpduProtect, loopProtect, rootProtect, portIsolation, loopbackDetect) and storm-rate params 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 states a specific verb and resource ('Apply one change to many ports at once') and immediately differentiates from the singular sibling by referencing 'the same trunk guard as v2_set_port'. An agent can distinguish this bulk-write tool from v2_set_port without opening a schema.

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

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

It explains the two selection modes (explicit ports vs. the 'access'/'dead'/'all' selectors) and gives a concrete recommended workflow: use with edgePort:true before enabling STP. It stops short of stating when to prefer the singular v2_set_port, so external choice is left implicit.

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

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

Annotations already establish that this is a mutating but idempotent and non-destructive operation. The description adds meaningful behavioral context beyond that: it discloses that each service is read back and diffed, and that a read-only/dry-run mode returns the exact payload instead of sending it.

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

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

The description is front-loaded and compact: the main action and affected services come first, followed by read-back/diff behavior and the dry-run mode note. Every sentence adds distinct information without padding.

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

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

For an 8-parameter mutation tool with no output schema and no schema descriptions, the description covers the main service toggles and dry-run behavior adequately enough for basic invocation, while annotations carry the safety profile. It remains incomplete because key parameters such as siteId, sshPort, and boolean semantics are not explained anywhere.

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 8 parameters and 0% schema description coverage, the description must carry the full explanatory burden, but it only loosely names the service-related booleans. It does not explain boolean true/false semantics, does not identify siteId or sshPort, and refers to the dry-run mode without naming the dryRun 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 states a specific verb ('Toggle') and resource ('site services'), then enumerates the exact services affected: SNMP v1/v2c/v3, SSH access, mDNS repeater, and UPnP. It does not explicitly differentiate itself from the read-oriented sibling v2_services, so it falls short of a 5.

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

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

Usage is implied by 'Toggle site services' and by the bracketed dry-run note, but there is no explicit guidance on when to choose this tool over siblings like v2_services or v2_set_site_feature, nor any stated prerequisites or exclusions.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false, openWorldHint=false, so the safety profile is covered. The description adds real value by disclosing the dry-run behavior (payload returned rather than sent), but it omits partial-update semantics – i.e. whether omitted boolean flags are left untouched or reset – which matters for a 15-param toggle 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?

Two compact sentences, feature list front-loaded, dry-run caveat placed last where it reads as a mode modifier. Minimal waste, though the feature enumeration is long and slightly dense.

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 15-parameter, zero-required mutation tool with no output schema and 13% schema coverage, the description covers the feature surface but not the update contract (partial vs full replacement), the meaning of the threshold parameters, or whether siteId is required. Adequate but with 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 coverage is only 13%, so the description must compensate. It does map feature names to several parameters (airtime fairness per band, alert logging, remote syslog target, LED, LLDP, auto-upgrade, band steering), which helps, but the threshold, port, and server parameters remain undocumented in both schema and 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?

States a clear verb (toggle) and resource (site-wide features) and enumerates the specific feature set – airtime fairness, alert logging, remote syslog, LED, LLDP, auto-upgrade, band steering. It does not, however, differentiate itself from siblings such as v2_site_settings or v2_set_service, which could plausibly overlap on site-level toggles.

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 '[READ-ONLY MODE: returns the exact payload instead of sending it]' note implies the dry-run path, and the feature list implies when to reach for this tool, but there is no explicit when-to-use vs when-not, no mention of v2_site_settings or other setters as alternatives, and no statement about which parameters must be supplied.

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

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

Goes well beyond the annotations by disclosing concrete side effects: nonStickRoaming and forceDisassociation emit MBO/OCE 'cannot handle new STA' which feeds the Android BSSID blocklist. It also explains the READ-ONLY MODE return-payload behavior tied to dryRun. Annotations (idempotent, non-destructive) are extended, not merely repeated.

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

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

Front-loads the purpose, then a critical side-effect warning, then the dryRun/read-only note in one dense but waste-free block. The parameter enumeration reads as a bare list, but every clause conveys 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 output schema and 0% schema coverage, the description supplies the key behavioral risk and the dryRun behavior, which is what an agent most needs. It falls short only on three undocumented parameters (siteId, dualBand11kReport, dryRun naming).

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 carry the burden; it names 5 of 8 parameters and adds a protocol hint (802.11r/k) for fastRoaming, but leaves meanings of siteId, dualBand11kReport, and dryRun (only obliquely implied by READ-ONLY MODE) unexplained, so it only partially compensates.

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 ('Set site roaming') and enumerates the exact knobs it controls (fastRoaming 802.11r/k, aiRoaming, nonStickRoaming, pingPongSuppression, forceDisassociation), which cleanly separates it from siblings like v2_set_site_feature or v2_set_ssid.

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

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

Usage is only implied: the note that nonStickRoaming/forceDisassociation produce the 'phone thinks it is banned' symptom gives a diagnostic context for when these settings matter, but there is no explicit when-to-use/when-not guidance or reference to an alternative tool for related roaming tasks.

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

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

Goes beyond the annotations (readOnlyHint=false, idempotentHint=true) by disclosing that changes are 'Read-back verified' and by flagging that prohibitWifiShare is a TTL clamp that 'breaks VMs and hotspots'. The bracketed READ-ONLY MODE note explains what dryRun actually does, which is real value-add rather than a contradiction.

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

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

Front-loaded with the verb and resource, then a compact enumeration of the affected fields and a bracketed mode note. Nearly every clause carries information; the parentheticals are load-bearing warnings rather than 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 12-parameter mutation tool with no output schema, the description covers the operation, read-back verification, the dry-run/read-only mode, and a key side-effect warning. It lacks permission/failure semantics, but the essential call-time context is present.

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

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

Schema description coverage is only 25%, so the description must carry more weight; it names most config parameters (enable, broadcast, enable11r, pmfMode, guestNetEnable, prohibitWifiShare, vlanId) but gives little semantic detail and omits siteId, band, and dryRun. It adds a meaningful warning for prohibitWifiShare but does not fully compensate 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?

States a specific verb ('Change') and a clearly scoped resource ('one SSID'), then enumerates the configurable attributes (enable/disable, broadcast, 802.11r, PMF, guest isolation, VLAN, rate-limit). An agent can tell it's the SSID setter, though it doesn't explicitly distinguish itself from nearby siblings like v2_set_ap_ssid or v2_ssids.

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 when-to-use, when-not-to-use, or alternative-tool guidance is given. The agent must infer that this tool applies to a single SSID versus the AP-level or site-level setting tools, with no explicit routing.

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

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

Adds real behavioral context beyond the annotations: it pre-warns about clients that would fall below the new floor before sending, discloses the READ-ONLY payload-return mode, and notes the ERP-protection penalty and 6.2.14.11 field verification. Annotations already carry the safety profile (readOnly false, idempotent true), so this is supplementary but valuable.

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

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

Front-loaded with the verb+resource, then dense but purposeful detail in one sentence plus a bracketed mode note. Every clause carries information, though the sentence is packed and requires careful parsing.

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 mutation tool with no output schema and 60% schema coverage, the description supplies the missing behavioral and safety context (dry-run, pre-send warnings, illegal rate combinations). Only the undocumented parameters 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 coverage is only 60% (10 params, several with no description), and the description mostly restates what the schema already documents (CCK, min rate, beacons). It does not compensate for the undocumented parameters (siteId, enable, ssidName, dryRun), so baseline 3 is appropriate.

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

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

States a specific verb+resource with scope: '802.11 rate control per SSID', then enumerates the exact settings it touches (CCK, min rate, beacon rate, client enforcement). An agent can distinguish it from siblings like v2_set_ssid or v2_set_ap_radio without opening the schema.

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

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

It explains what the levers do and mentions the read-only/dry-run mode, but gives no explicit guidance on when to choose this over v2_set_ssid, v2_set_ap_radio, or v2_rf_planning. Usage is implied by the domain 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 only cover idempotency/safety flags; the description adds substantive behavior the annotations cannot convey: the ~30 s convergence window, the concrete blast radius (AP/camera ports drop), the root-bridge rule (lower priority wins, 4096 forces root), and a dry-run/read-only mode that returns the payload instead of sending it. That is exactly the extra context an agent needs for a disruptive network mutation.

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

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

Highly dense: action first, then the disruptive-behavior warning, then the mode note. Almost every clause carries information. The bracketed '[READ-ONLY MODE: ...]' is slightly cryptic and left unexplained relative to the dryRun parameter.

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 6-parameter state-changing tool with no output schema and sparse annotations, the description covers the headline semantics well but leaves half the parameters undocumented (mode enum values, dryRun vs. READ-ONLY MODE, siteId). Adequate but with 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 only 17%, so the description must compensate but only partially does. It adds real meaning for priority (lower wins; 4096 forces root) and implies the on/off semantics of the operation, but says nothing about the mode enum (off/stp/rstp/mstp), dryRun, siteId, or switchMac.

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 specific verbs and resource: enable/disable STP, set bridge priority and timers on a switch. An agent immediately knows the domain of change. It does not contrast itself with any sibling tool, but the sibling list contains no other STP-specific writer, so the lack of differentiation is a minor gap.

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 clear situational guidance: enabling STP causes ~30 s of listening/learning and will drop ports carrying APs/cameras, so it should be run 'when the network is quiet.' This is actionable when-to-use context. It stops short of naming an alternative tool or stating an explicit when-not-to-use rule.

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

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

Annotations already disclose readOnlyHint=true, idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that with 'Flags risky values', telling the agent the response includes risk annotations rather than raw settings only. It doesn't say anything about size, pagination or credential sensitivity, so it stops short of a 5.

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

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

A single sentence, front-loaded with the scope declaration 'FULL site settings decoded'. The long parenthetical enumeration is dense but each item earns its place by delimiting the returned field surface.

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

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

With no output schema, the description usefully enumerates the returned setting groups and notes risk flagging. However it omits the siteId parameter semantics entirely and gives no sense of response shape or volume, leaving a real gap for a two-parameter tool.

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

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

Schema coverage is only 50%: showSecrets is documented in-schema, but siteId has no description anywhere. The description mentions no parameters at all, so it does nothing to compensate for the undocumented siteId — the agent must infer it from the tool name alone.

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 clear resource (site settings) with an explicit scope: 'FULL' and an enumerated list of the exact setting families returned (roaming, band steering, airtime fairness, mesh, etc.). The verb is only implied by 'decoded', and it does not differentiate itself from adjacent readers such as v2_controller_settings or v2_log_settings, which overlap on alerts/syslog territory.

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

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

There is no when-to-use guidance, no mention of prerequisites, and no routing to alternatives. A sibling set full of v2_set_site_roaming / v2_set_site_feature / v2_set_site_* writers exists, and the description never confirms that this is the read-side counterpart or when an agent should pick it over those.

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?

Adds real behavior beyond the annotations: it discloses the exact failure mode (-1600) and that the tool reports the unsupported state rather than hanging, plus a READ-ONLY MODE that returns the payload instead of sending it. That is meaningful operational context an agent cannot derive from readOnlyHint/openWorldHint. The mild tension between the annotation readOnlyHint=false and the description's READ-ONLY MODE note is a dry-run/harness distinction rather than a direct contradiction, but it is not fully reconciled.

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 lead sentence is tight and front-loaded, but the definition then carries a long parenthetical caveat and a bracketed mode note that read more like internal maintenance annotations than agent-facing guidance. It is not bloated, but the caveats crowd out the practical 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?

With no output schema and no parameter documentation, the description compensates partially by explaining the failure path and read-only behavior, which is the most important thing for this currently-broken tool. It still leaves the agent without any information on inputs or what a successful result looks like.

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 or waitSeconds. The phrase 'poll for the result' faintly implies a timeout/interval parameter, but no units, defaults, or polling semantics are given, so the two parameters remain effectively 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?

States a specific verb and resource ('Run the controller WAN speed test and poll for the result'), which is concrete enough to distinguish it from generic siblings like v2_wan or v2_diagnostics. It does not explicitly name an alternative tool, but the purpose itself is unambiguous.

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

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

Gives unusually strong when-not-to-use guidance: the tool is verified unsupported on this build (-1600) because no Omada gateway is present, and is only retained for future ER-series adoption. It lacks an explicit pointer to what to use instead (e.g., v2_wan or v2_diagnostics), which keeps it from 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 description explicitly says the tool can 'change it per-AP' (a mutation, reinforced by a dryRun parameter), while annotations declare readOnlyHint=true. Claiming write capability under a read-only annotation is a direct contradiction. The otherwise-useful ssidEnable vs enable semantics cannot rescue a description that misstates the tool's side-effect profile.

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

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

Three sentences, purpose front-loaded, and the high-value semantic caveat is clearly flagged with 'IMPORTANT SEMANTICS'. Dense but each sentence attempts to earn its place; only the mismatch with the actual parameter set wastes attention.

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

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

A mutation-capable tool with no output schema, 5 largely undocumented parameters, and annotations that are contradicted rather than informative. Critical details such as what dryRun does and how broadcast interacts with ssidName/apName are absent, leaving the 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 coverage is only 20% (just apName documented), so the description must compensate. Instead it discusses ssidOverrides[].ssidEnable and `enable`, which are not among the actual parameters, while key params broadcast and dryRun go unexplained. It adds little meaning to the real input surface.

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 resource and operation: reading which APs broadcast which SSID and changing broadcast per-AP. It is concrete and not tautological. It does not, however, explicitly distinguish itself from close siblings like v2_set_ap_ssid or v2_ssids, so an agent must infer the boundary.

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

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

'Use this to keep an SSID on one AP only' supplies one concrete usage scenario, which is better than nothing. But there is no statement of when NOT to use it and no named alternative, despite a crowded set of ap/ssid write siblings. Usage is implied rather than prescribed.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, but the description adds real behavioral context beyond them: passphrases are redacted unless showSecrets is passed, and it enumerates the config surface returned. It does not mention pagination or response shape, but the redaction note is genuinely valuable for an agent.

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 compact sentences, front-loaded with the scope and ending with the one conditional flag that changes output. The field enumeration is long but each item conveys what the config payload covers.

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

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

With no output schema, the description usefully enumerates the returned config fields and flags the passphrase redaction behavior. The only meaningful gap is the unexplained siteId parameter, which keeps it from being 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% for two parameters. The description explains showSecrets ('Passphrases redacted unless showSecrets'), adding real meaning, but siteId is never mentioned, leaving half the parameters undocumented in both schema and 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?

States a specific resource and verb-scope ('Full config of every SSID') and enumerates the exact fields returned, so an agent knows this is a read of SSID configuration rather than a mutation. It does not explicitly name a sibling like v2_set_ssid or v2_ssid_broadcast, so it stops short of full differentiation.

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

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

There is no statement of when to use this versus v2_set_ssid, v2_ssid_broadcast, or v2_get. Usage is only implied by the read-only nature of the description; no prerequisites or exclusions 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?

Annotations already cover readOnly, idempotent, and non-destructive behavior. The description adds meaningful context beyond them: this is an authentication check, and it discloses the shape of the information returned (version, account, role, temp-account expiry), which is valuable given there is no output schema.

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

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

Two short sentences, front-loaded with what it returns and ending with the imperative 'Call this first.' Every clause earns its place with no redundancy.

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

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

For a zero-parameter diagnostic with no output schema, the description covers purpose, key return fields, and call ordering. It stops short of describing error/not-logged-in states, but is otherwise 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?

The tool takes zero parameters, so the baseline is 4. The description correctly implies no input is needed, and there is no schema detail to misrepresent.

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 purpose (login/authentication status check) and enumerates the returned fields: controller version, account, role, and hours left on a temporary account. It is distinguishable from siblings, though the verb 'Login check' is slightly informal compared to the rest of the v2_ family.

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?

'Call this first' gives explicit sequencing guidance, telling the agent this is a preflight/auth step before other tools. It does not name alternatives or state when-not to call it, but the ordering directive is clear and actionable.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description does add value beyond that by disclosing scope (switch-level vs device-level fields) and the fact that STP-disabled switches are flagged, which is a real behavioral trait. It does not cover result volume, pagination, 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?

A single sentence, front-loaded with the resource ('Switch-level state:'), followed by a compact field enumeration and a short flag note. No filler or redundancy, though the field list is dense enough to be slightly hard 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?

With no output schema, the description does the useful work of enumerating returned fields, which is appropriate. However, it omits the siteId selector semantics, any pagination or result-size expectation, and any indication of how it relates to the adjacent switch tools, leaving real gaps for a data-retrieval tool with ~4 sibling candidates.

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

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

The single parameter siteId has 0% schema description coverage and the description never mentions it, its format, or what the default scope is when it is absent. With one undocumented parameter, the description fails to compensate for the coverage gap, though siteId is a fairly self-evident identifier.

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 enumerates the switch-level fields returned (model, firmware, uptime, STP, jumbo frames, LAGs, LLDP), so the resource is identifiable, but it reads as a noun dump with no verb and makes no attempt to distinguish itself from closely-named siblings such as v2_switch_stats, v2_switch_ports, or v2_switch_stats. An agent cannot tell from this text why it should pick v2_switches over those.

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

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

There is no when-to-use guidance, no prerequisite, and no mention of alternatives despite at least three sibling tools covering switch data. The only implicit signal is 'Flags STP-disabled switches', which hints at a diagnostic use case but is not framed as guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so safety is covered. The description goes beyond that by disclosing derived behavior: it emits warnings for STP-off / loopback-off / all-VLAN / dead ports and marks inter-switch trunks, telling the agent the output contains computed diagnostics rather than raw config.

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?

Very compact: one dense enumeration sentence plus a warning/trunk sentence. The scope ('every port on every switch') is front-loaded. The first sentence is a run-on attribute list that is efficient but slightly hard to parse.

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

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

With no output schema, the description usefully enumerates the returned fields and the derived warnings/anomaly flags, which an agent needs to interpret results. It is complete enough for a read-only per-port report, with siteId semantics the main remaining gap.

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

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

Schema coverage is only 50% (only switchMac carries a description); siteId is undocumented in both schema and description. The description's '(or one switch)' reinforces the switchMac scoping semantics, but it says nothing about siteId's role or whether omitting it changes the result set.

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 makes clear this is a per-port reporting tool on switches, enumerating exactly what gets decoded (link/speed, PVID, VLAN tagging, PoE, STP, etc.). It states a specific resource and scope, but never differentiates itself from close siblings like v2_port_stats, v2_switch_stats, or v2_switches, so an agent must infer the boundary.

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

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

There is no explicit when-to-use guidance, no statement of prerequisites, and no named alternative. The parenthetical '(or one switch)' hints at the scope toggle but does not tell the agent when to prefer this tool over v2_port_stats or v2_switches.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds useful content context by listing the statistic categories returned (per-port operation, speeds, PoE, traffic totals), but it does not cover auth, rate limits, pagination, or 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 a single front-loaded sentence with no wasted wording. It names the view and enumerates the included statistic categories efficiently.

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

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

For a simple read-only statistics tool with annotations covering safety, the description adequately names the returned content. However, it leaves parameter meaning, differentiation from sibling stats tools, and return shape unaddressed, which is a meaningful gap given the absence of an 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, but it does not mention switchMac or siteId directly. 'Per-switch' weakly implies switchMac identifies the target, while siteId is entirely unexplained in both the schema and 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 states a specific resource and scope: 'Per-switch statistics view' with per-port operation, speeds, PoE, and traffic totals. It is clear what the tool returns, but it does not explicitly distinguish itself from sibling stats tools such as v2_port_stats or v2_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?

There is no explicit guidance on when to use this tool versus alternatives, nor any when-not-to-use conditions. The phrase 'as the Statistics page shows them' provides only loose implied context, not actionable usage guidance.

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

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

Annotations already declare readOnly, idempotent, non-destructive and non-open-world, so safety is covered; the description still adds value by disclosing the shape of the returned data. With no output schema, spelling out what comes back (nodes, connections, port, speed) is the key behavioral disclosure.

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

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

Two tight sentences, the resource and returned content front-loaded, followed by a single actionable caution. Nothing is padded or redundant.

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

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

For a low-complexity, single-parameter read tool with no output schema, the description covers what the agent receives and when to reach for it. The only missing piece is any explanation of the siteId scope.

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, so an agent gets no scoping semantics — is the topology global or per-site? The parameter name is suggestive but not explained, which is a real gap for a tool whose whole purpose is scoping a network view.

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

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

Names a concrete resource (physical topology) and enumerates the returned facts — nodes, links, ports, speeds — which is far more specific than a tautology. It is distinguishable from sibling port tools like v2_switch_ports or v2_port_stats, though it never names an alternative 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?

Gives a clear use case with a precondition: confirm inter-switch trunks before touching loopback detection. That is real situational guidance rather than implied usage. It stops short of stating when NOT to use it or naming a competing tool to prefer instead.

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