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

With no annotations, the description carries the full burden and delivers: it discloses that the pagination envelope is verified but the per-row shape is not, that entries contain best-effort guesses plus an untouched `raw` row, and that legacy authentication is required. This is unusually candid behavioral context an agent could not get from the schema.

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

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

The purpose is front-loaded in one line, followed by detail blocks that each add real information (data-shape caveat, auth requirement). It is slightly verbose with parenthetical asides 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?

An output schema exists, so return values needn't be explained, and the description supplies valuable caveats about unverified row shape and auth. The only meaningful omission is the semantics of the site_id parameter, which leaves the definition slightly short for a 1-param tool.

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

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

The single parameter site_id has 0% schema description coverage, so the description is responsible for clarifying it, yet it never mentions site_id at all. It is unclear whether omitting site_id lists alerts across all sites or behaves some other way, leaving a real gap for the only input.

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

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

The opening sentence gives a specific verb and resource ('List active alerts on a site'), making the tool's function immediately clear. Although siblings like list_devices exist, the alerts resource is distinct enough that no explicit differentiation is needed. An agent can identify this tool's job from the first line.

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

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

The description states a prerequisite (legacy OMADA_USER/OMADA_PASS login) but never says when to choose this tool over alternatives or under what conditions alert listing is appropriate. There is no when-to-use or when-not-to-use framing at all.

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

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

With no annotations, the description carries the behavioral burden and does disclose two important traits: the authentication method required (legacy login, no verified Open API path) and the historical/known scope of the data. It omits pagination, rate limits, and how fresh last_seen_ms is, which are secondary for a read 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?

Front-loaded with the core purpose and scope clarification, followed by the auth caveat. The field enumeration is long but informative rather than redundant, and no sentence 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?

The tool is low-complexity (one optional param) and an output schema exists, so return-value explanation isn't required. The auth requirement and scope caveat are the key operational facts and are present; only the site_id default semantics are left uncovered.

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 the single site_id parameter, and the description never mentions it or explains default behavior when omitted. The description adds no parameter meaning beyond the bare schema name, so it fails to 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?

Specific verb (List) plus resource (Insight/known clients on a site), with the return fields enumerated. It explicitly distinguishes itself from a plain 'currently-associated clients' listing, giving the agent a clear mental model of the 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?

The description clarifies when this view applies (historical + known clients, not just currently-associated), which is a meaningful selection cue. It also states the auth prerequisite. It doesn't name a sibling as the alternative for live-only listings, so it stops just short of full routing guidance.

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

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

With no annotations, the description carries the full burden and does disclose the key behavioral trait: this endpoint is unauthenticated and independent of the server's auth mode, plus the underlying route GET /api/info. It omits rate-limit or failure-mode notes, but the safety-relevant auth behavior is covered and an output schema exists for the return shape.

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-loading the identity/fields and then the auth property. Every clause adds information, with no padding.

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

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

For a zero-parameter, read-only identity probe with an output schema already documenting the return values, the description supplies everything needed: what it returns, the underlying route, and that no authentication 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate beyond what the empty schema already shows; the baseline for a no-param 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?

States a specific verb and resource ('Get the Omada controller's own identity') and enumerates the returned fields (controller_version, omadac_id, configured), which cleanly separates it from siblings like list_sites and get_clients. An agent can distinguish it 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 gives a clear usage condition: the call is unauthenticated and works regardless of the server's configured auth mode, which tells the agent it is safe to call at any time. It stops short of naming alternatives or explicit exclusions, but the 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?

With no annotations, the description carries the full burden and does well: it discloses that output depth varies by auth mode (legacy full detail for AP/EAP, summary rows otherwise, reduced fields on Open API), that fields are normalized plus a raw passthrough, and that MAC separators are normalized. It stops short of permission/rate-limit or error behavior, so it is strong but not exhaustive.

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 purpose and the MAC-format detail in the first sentence, then auth-mode behavior, then return shape. Dense and mostly waste-free, though the parenthetical asides and trailing 'so nothing the controller returned is lost' add mild length.

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

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

An output schema exists, yet the description still usefully characterizes the return shape (normalized fields plus raw), and it documents the auth-dependent behavioral split, which the schema cannot convey. The unaddressed `site_id` parameter is the notable gap preventing a 5.

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

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

Schema coverage is 0%, so the description must compensate for both parameters. It compensates excellently for `mac` (accepted separators: colon, hyphen, Cisco-dotted, bare; normalized), but `site_id` 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 verb and resource ('get the richest available detail for one device') plus the keying mechanism (MAC address), which sharply distinguishes it from the sibling list_devices. An agent can tell what the tool returns and how it is identified 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?

Usage is implied by the contrast with list_devices (one device vs. a list) and by the noted fallback behavior, but there is no explicit 'use this when / not when' statement or named alternative. The auth-mode caveat hints at when richer data is available, which is useful but not a routing 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?

With no annotations, the description carries the full burden and does so well: it discloses that legacy login (OMADA_USER/OMADA_PASS) is required, explains why (the Open API device list has no per-radio fields, verified against real hardware), and warns that actualChannel is irregularly formatted and must be parsed. These are exactly the operational caveats an agent needs before calling.

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 payload, followed by scope and then the auth caveat; every clause carries information. The parenthetical on the parser and the README reference are slightly verbose but justified.

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

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

An output schema exists, so return-value documentation is unnecessary, and the description covers the data source, auth path, and scoping. The only real gap is the unaddressed `site_id` parameter and its default behavior.

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

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

Schema description coverage is 0% for two parameters, so the description must compensate. It clarifies `mac` as an optional single-AP filter, but says nothing about `site_id` or what a null/default value implies, leaving half the parameters 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 names a specific resource and enumerates the exact fields returned (2.4/5GHz channel, per-band client counts, radio utilization), so an agent knows precisely what it gets. It doesn't explicitly contrast itself with siblings like get_device_detail or get_clients, which keeps it 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?

It states the scoping behavior clearly — one entry per AP on the site, or a single AP when `mac` is given — and notes the legacy-login prerequisite. However, it never says when to prefer this over the sibling get_device_detail or list_devices, so usage routing 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?

With no annotations, the description carries the burden and does so well for return-shape behavior: fields unavailable under the active auth mode appear as null rather than being omitted, so callers never branch on auth mode. It omits read-only/pagination/rate-limit disclosure, which is a gap for a list tool, but the null-filling contract is genuinely non-obvious behavioral information.

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

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

Front-loaded with the purpose, then the normalization contract, then the parameter default. Two short paragraphs, no filler sentences. The detail on return shape is somewhat long for a one-parameter tool but each 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?

An output schema exists, so raw return values need not be explained, yet the description usefully adds the null-semantics contract that the schema likely cannot express. It leaves out pagination/result-size behavior and any explicit read-only statement, which are the only notable gaps for a zero-required-arg list tool.

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

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

Schema coverage is 0% (the schema only says 'Site Id', default null), so the description must compensate — and it does: site_id falls back to OMADA_SITE_ID or auto-selects when the controller manages exactly one site (legacy auth only). That is real added meaning beyond the schema, including an auth-mode caveat.

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

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

States a specific verb and resource ('List devices on a site') and immediately qualifies the scope with the normalization guarantee. It does not name or contrast with any sibling (e.g. get_device_detail or get_clients), so the agent must infer boundaries itself, but the core purpose 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?

Usage is implied rather than stated: the site_id defaulting rules (OMADA_SITE_ID, single-site auto-select) tell the agent it can call this with no arguments, which is useful context. However, there is no explicit when-to-use-this vs get_device_detail/get_clients guidance and no 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?

No annotations exist, so the description carries the full burden and does so well. It discloses a critical behavioral trait: this endpoint requires legacy login (OMADA_USER/OMADA_PASS) and the Open API path cannot serve it in v0.1, pointing to README for the auth x endpoint matrix. This is exactly the kind of context an agent needs to know before attempting the call.

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 what it does and what it returns, then immediately covers the auth caveat. Every part earns its place; no fluff.

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

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

Despite no output schema details needed (output schema exists), the description covers the key gaps: no annotations means it must disclose auth requirements, which it does thoroughly. For a zero-param list tool, this is complete – it tells the agent what to expect and what's required to call 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?

Zero parameters, so baseline is 4. The description correctly adds no parameter details, but the auth prerequisite is effectively an implicit input requirement (needs OMADA_USER/OMADA_PASS credentials), which is useful semantic context.

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

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

States a specific verb ('List') and resource ('sites') and even specifies the exact output fields ('id + name'). An agent can immediately distinguish this from siblings like list_devices or get_controller_info, which target different resources.

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

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

The description implies usage ('List sites managed by this controller') but provides no explicit when-to-use vs alternatives guidance. There's no sibling differentiation or condition named. The auth note is a prerequisite, not 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?

No annotations are present, so the description carries the full burden and does so: it discloses the write guard, the preview/apply flow, that applied=True requires a post-write re-read of freq, the applied=False outcome with an explanatory message, the legacy-auth requirement, and the warning that changing a channel briefly drops clients on that band.

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 operation, then the guard, then confirm semantics, then return/warning details in a logical order. It is dense with implementation references to guard docstrings and docs/api-notes.md that could be trimmed, but little of the content is truly 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 guarded mutation with an output schema, the description covers the guard, the confirmation protocol, what applied/message mean, and the side effects. Returns are already documented by the output schema, so nothing an agent needs to invoke this correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does for the two non-obvious params: channel is the operator-facing number (11 on 2.4GHz, 149 on 5GHz) with freq derived internally, and confirm's preview-vs-apply semantics are spelled out. mac and site_id are left unexplained, and band only gains the '2g'/'5g' hint, so the coverage is strong but not complete.

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

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

States a specific verb (Set) plus the exact resource (an AP's 2.4GHz or 5GHz radio channel) and names the band tokens '2g'/'5g' that the agent must supply. All siblings are read-only tools, so this write tool is unambiguously distinguished.

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

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

Explicitly states the write guard (blocked unless OMADA_ALLOW_WRITE=true) and the two-step flow: call with confirm=False for a preview, then with confirm=True to apply. This is exactly the when-and-how guidance an agent needs before invoking.

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