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

With no annotations, the description carries the full behavioral burden and does so well: non-GET calls are refused in read-only mode, writes return a dry-run preview unless confirm:true, and {omadacId}/{siteId} are auto-injected. It omits pagination behavior, error semantics, and what the response envelope looks like, which matters for a generic dispatcher.

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, zero filler, and the invocation modes are front-loaded ahead of the safety constraints. Every clause adds information an agent needs to call this correctly.

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 generic API dispatcher with no output schema and no annotations, the description covers invocation, path templating, and the write-safety model. It is nearly sufficient, with return shape and pagination left implicit.

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 57% and the description fills the most important gaps: it explains the operationId alternative, that the /openapi/v1/{omadacId} prefix is applied automatically, and the exact approval semantics of confirm. It says nothing about body or query shape, which remain 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?

States a specific verb and resource — 'Invoke any controller Open API endpoint' — and implicitly separates itself from omada_ui_call by scoping to the Open API surface. It also names omada_search_api as the source of operationId, so an agent can route between the search/describe/call trio 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 entry paths ('operationId from omada_search_api' or 'method+path') and states the read-only and confirm-before-write conditions, plus the requirement to show the dry-run preview and get an explicit yes. It stops short of saying when to prefer the purpose-built siblings (omada_clients, omada_sites) over this generic escape hatch.

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?

readOnlyHint=true already tells the agent this is a safe read, and the description adds the pagination behavior plus a signal that results are a live snapshot ('currently connected'). It does not disclose rate limits, maximum result set, or how pagination terminates, so it adds moderate value over the annotation.

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

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

Two terse sentences/fragments with the resource and fields front-loaded and no wasted words. The telegraphic field list is dense but appropriate for a list tool.

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

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

With no output schema and minimal annotations, the description carries the burden of describing returns, and it does so by naming the client fields, plus noting pagination. It is nearly complete for a simple list tool, missing only pagination limits and the site-scoping requirement.

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 75% (page, pageSize, and searchKey are documented; siteId is not). The description only echoes pagination, which the schema's page/pageSize already convey, and does not clarify whether siteId is needed to scope 'a site' — no real value beyond the schema's baseline.

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

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

States a specific verb+resource ('Clients currently connected to a site') and enumerates the returned fields (name, MAC, IP, wired/wireless, SSID, signal, traffic), which makes the scope clear. It does not explicitly differentiate itself from siblings like omada_devices or omada_search_api, but the 'connected clients' framing is distinct enough to infer.

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, no when-not-to-use, and no named alternative. The phrase 'currently connected' implies a live-inventory use case, but an agent gets no guidance on choosing this over omada_devices or omada_search_api.

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?

readOnlyHint=true is consistent with a describe/read tool. Since there is no output schema, the description usefully discloses what the response contains (parameters, request-body schema, response shape), which is behavioral context beyond the annotation.

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

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

Two compact sentences, front-loaded with what the tool returns and finished with the accepted input forms. 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?

With no output schema, the description covers the return content well and fully documents the single input's accepted forms. Minor gap: it doesn't mention error behavior for invalid operationIds/paths, but nothing essential to correct invocation is missing.

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

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

Schema coverage is 100% with a single parameter whose description already spells out the operationId or "METHOD /path" format, so the description largely restates the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb+resource: returns full detail for a single API operation, enumerating path/query parameters, request-body schema, and response shape. It explicitly distinguishes itself from the sibling omada_search_api by naming it as the source of the operationId.

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: use it after omada_search_api, and tells the agent the accepted input forms (operationId or "METHOD /path"). It does not state when NOT to use it or contrast with omada_call, but the workflow placement 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?

readOnlyHint=true already tells the agent this is a safe read with no side effects, so the description does not need to carry the safety burden. It adds the useful fact that only *adopted* devices are returned and lists the fields exposed, but says nothing about scoping, pagination, or behavior when siteId is omitted (the schema covers that default).

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

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

A single tight sentence that front-loads the resource and then the returned fields. It is efficient with no filler, though the missing verb makes it a fragment rather than a fully self-contained statement.

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, single-parameter read tool with no output schema, enumerating the returned device fields (model, MAC, IP, status, uptime, firmware) gives the agent enough to know what it will get and when it is the right call. Nothing essential is missing given the tool's low complexity.

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

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

Schema description coverage is 100% and there is only one optional parameter, whose default behavior (OMADA_SITE_ID or the only site) is documented in the schema itself. The description adds no parameter detail beyond that, so the baseline 3 applies.

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

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

States the specific resource (adopted Omada devices for a site) and enumerates the device families and fields returned, which distinguishes it from siblings like omada_clients and omada_ssids. It reads as a noun phrase rather than a verb, so the action ('list/retrieve') is only implied, but the resource is unambiguous.

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

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

There is no statement of when to use this tool versus alternatives such as omada_status or omada_clients, and no conditions or prerequisites are given. Usage must be inferred entirely from the resource description.

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

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

The readOnlyHint annotation already covers the safety profile, and the description adds useful scoping context (searching the controller's own spec). However, it does not describe the result format, pagination, or how the returned endpoints should be consumed by omada_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?

The description is two sentences with no wasted words. The core behavior is front-loaded, and the follow-up usage guidance with examples earns its place.

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

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

For a read-only search tool, the description covers what it searches and when to use it, while the schema handles parameter details. It does not describe the shape of the search result or how to map results into an omada_call, which would be useful given there is no output schema.

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

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

Schema description coverage is 75%, and the schema already documents query matching, group restriction, and limit behavior; the method enum is self-explanatory. The tool description adds example query terms but no additional parameter semantics beyond the schema.

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

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

The description uses a specific verb and resource: 'Search this controller's own OpenAPI spec for endpoints.' It clearly distinguishes itself from the sibling omada_call by positioning itself as the lookup step before an exact operation is known.

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

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

It explicitly states when to use the tool: 'Use it before omada_call whenever the exact operation is not already known,' with concrete example queries. It lacks an explicit when-not-to-use statement or direct comparison to omada_describe_api, but the intended context is clear.

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

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

readOnlyHint=true already tells the agent this is a safe read. The description adds genuinely useful context beyond the annotation: the returned shape (siteId + name) and the fact that other calls depend on it. It says nothing about auth, pagination, or errors, but for a trivial zero-arg read that gap is minor.

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 compact sentence with the resource front-loaded and the return fields plus dependency hint packed into a parenthetical. Every clause 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 correctly takes on the job of describing what comes back (siteId + name) and why it matters, which fully covers a zero-parameter list call. Marginally incomplete only in not noting ordering, pagination, or emptiness 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?

There are zero parameters, so the baseline is 4 and there is no parameter semantics to explain. The description's mention of return fields is output information rather than a substitute for parameter documentation.

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

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

States a specific verb and resource ('List the sites on this controller') and even names the fields returned (siteId + name), so the agent knows what it gets. It is distinguishable from siblings like omada_devices/omada_clients by resource, but it never explicitly contrasts itself with any of them, so it falls short of a 5.

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

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

The phrase 'which most other calls need' implies this is a prerequisite/lookup call agents should run before site-scoped operations, which is useful implied guidance. However, it gives no explicit when-to-use/when-not statement or named alternative, so usage remains inferred 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?

The readOnlyHint=true annotation already establishes this is a non-destructive read, lowering the bar. The description adds the shape of the returned data (grouped WLAN groups with per-SSID attributes), which is real context since no output schema exists, but it says nothing about pagination, permissions, or whether an omitted/default site scope is applied.

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 compact clause with zero filler; the returned-field inventory is front-loaded immediately after the resource. It is efficient, though the sentence is a noun fragment rather than a complete statement of action.

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 usefully enumerates what comes back and how it is grouped. It still leaves the optional siteId's semantics and any usage routing unexplained, which is a meaningful but not fatal gap at this complexity.

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

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

There is one parameter (siteId, optional) with 0% schema description coverage, so the description must compensate. The phrase 'on the site' gestures at site scoping but never names siteId, explains its format, or states what happens when it is omitted — the optional/default behavior is 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?

Identifies a specific resource pair — WLAN groups and the SSIDs nested inside them — along with the fields of interest (name, band, security, guest-network, VLAN). The verb is carried only implicitly by the title 'List WLANs and SSIDs'; the resource itself is distinct from omada_devices, omada_clients, and omada_sites, so no sibling confusion. Clear, though not a full verb+resource statement in the description body.

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 conditions, and no mention of any alternative tool. An agent must infer from the name alone that this is the SSID/WLAN-configuration listing tool rather than, say, omada_devices or a generic omada_call.

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; the description goes beyond that by signaling this is a non-mutating diagnostic ('health and wiring check') and listing what it inspects. It does not contradict annotations and adds context about scope without claiming a destructive 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, zero waste. The first sentence front-loads the purpose and enumerates the checks in a compact list; the second sentence provides a clear recommendation. Every phrase adds value, and the structure makes it easy to scan.

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

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

For a 0-parameter read-only diagnostic, the description adequately covers when to call it and what information it surfaces. It does not mention the exact output shape, but no output schema exists and the enumerated checks imply the expected data. It is not fully exhaustive, but is complete enough for safe 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 has zero parameters and the schema is empty, so no parameter explanation is needed. The description still implicitly explains that no inputs are required by focusing entirely on the status of the controller environment. Baseline of 4 applies for zero-parameter tools.

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

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

Description gives a specific verb and resource: it is a 'health and wiring check' for the Omada controller, enumerating exactly what it reports (version, API token state, write-mode, deny-list, API index freshness, legacy sessions, site list). This clearly distinguishes it from sibling tools, which target specific entities like sites, devices, or API discovery.

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

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

Provides a clear trigger: 'Run this first when anything looks off.' This tells the agent when to invoke the tool, but it does not mention when not to use it or explicitly reference alternatives beyond the general first-step guidance. It gives actionable context but 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?

With no annotations, the description carries the full burden and does disclose two real traits: it requires OMADA_WEB_USER/PASS credentials and it follows the same write rules as omada_call (i.e. it can mutate). It does not explain the undocumented `confirm` gate, session/cookie handling or expiry, or what happens on auth failure, which matters for a 6-param transport that can issue DELETE.

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 fallback role and immediately followed by the credential requirement and path-discovery tip. No filler; only the missing `confirm` explanation keeps it from a 5.

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

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

For a low-coverage schema, no annotations, and no output schema, the description omits too much: the meaning and necessity of `confirm`, how `body`/`query`/`pathParams` are composed, and what a response looks like. An agent could construct an unintended mutating call from this definition.

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% across 6 parameters, yet the description adds nothing about `body`, `query`, `pathParams`, `method` defaulting, or `confirm`. The one detail it does give (the /{omadacId} prefix being added) is already stated in the path parameter's schema description, so the description 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?

States a specific resource (the session API the Omada web UI itself uses, /{omadacId}/api/v2/...) and its role as a fallback transport for settings the Open API does not expose. This cleanly separates it from omada_call (Open API) and omada_describe_api/omada_search_api, 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?

Explicitly frames itself as a fallback for settings the Open API does not expose, which implies the alternative (use omada_call first), and gives concrete guidance on discovering paths (browser network tab, community API notes). No explicit 'do not use for X' exclusion, so 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.