Which integrations are available for this server?

Provides tools for managing TP-Link Omada controller devices, sites, clients, and other network resources via the Omada API.

How do I use tplink-omada-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tplink-omada-mcp list all network devices" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tplink-omada-mcp

by MiguelTVMS

Overview Schema Source Related Servers Score Discussions Admin

TypeScript

Remote

TP-Link Omada MCP server

🤖 AI-Developed Repository
Since March 2, 2026, this repository contains no human-written code.
All planning, development, and code review is performed by AI agents. Humans remain in the loop for direction, decisions, and final approval — but every line of code, every test, every commit, and every PR is the work of AI.
This is not an experiment. This is how it works now. Know more

A Model Context Protocol (MCP) server implemented in TypeScript that exposes the TP-Link Omada controller APIs to AI copilots and automation workflows. The server authenticates against a controller, lists sites, devices, and connected clients, and offers a generic tool to invoke arbitrary Omada API endpoints.

Compatibility: Tested with Omada Controller versions 5.x and 6.x

Related MCP server: safe-omada-mcp

Quick Start

Using with Claude Desktop (stdio)

Pull the Docker image (or build it locally with npm run docker:build):
```
docker pull jmtvms/tplink-omada-mcp:latest
```
Add the MCP server to Claude Desktop configuration. Edit your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "tplink-omada": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "OMADA_BASE_URL=https://your-omada-controller.local",
        "-e", "OMADA_CLIENT_ID=your-client-id",
        "-e", "OMADA_CLIENT_SECRET=your-client-secret",
        "-e", "OMADA_OMADAC_ID=your-omadac-id",
        "-e", "OMADA_SITE_ID=your-site-id",
        "-e", "OMADA_STRICT_SSL=false",
        "jmtvms/tplink-omada-mcp:latest"
      ]
    }
  }
}

Replace the environment variable values with your actual Omada controller credentials.

Restart Claude Desktop to load the new MCP server configuration.
Verify the connection by asking Claude to list your Omada sites or devices.

Using Docker Containers

CLI/stdio Container

docker run -it --rm \
  --env-file .env \
  jmtvms/tplink-omada-mcp:latest

HTTP Server Container

docker run -d \
  --env-file .env \
  -e MCP_SERVER_USE_HTTP=true \
  -e MCP_HTTP_BIND_ADDR=0.0.0.0 \
  -p 3000:3000 \
  jmtvms/tplink-omada-mcp:latest

The HTTP server will be available at http://localhost:3000/mcp.

Features

OAuth client-credentials authentication with automatic token refresh
Tools for retrieving sites, network devices, and connected clients
Generic Omada API invoker for advanced automation scenarios
Environment-driven configuration
Per-tag Omada OpenAPI references stored under docs/openapi
Ready-to-use devcontainer with a companion Omada controller service

Getting started

Prerequisites

Docker (for running pre-built containers) or Node.js 24+ (for local development)
Access to a TP-Link Omada controller (for example using the mbentley/omada-controller Docker image)

Configuration

The MCP server reads its configuration from environment variables. See .env.example for a complete reference.

Tool Category Filtering

Variable	Required	Default	Description
`OMADA_TOOL_CATEGORIES`	No	`dashboard:r,client-insights:r,clients:r,devices-all:r`	Comma-separated categories to enable at startup
Each token is `<category>[:<suffix>]`. Permission suffixes:

Suffix	Effect
`:r`	Read tools only
`:w`	Write tools only
`:rw`	Read and write tools
(none)	Same as `:rw`

Category Reference

Categories marked with * are reserved for upcoming phases and have no tool implementations yet. Specifying them will produce a startup warning and they will be skipped. Write tools are currently limited to the clients category.

Group	Categories
Dashboard & Insights	`dashboard`, `client-insights`, `insights`*
Clients	`clients`
Devices	`devices-general`, `devices-ap`, `devices-switch`, `devices-gateway`
Wireless	`wireless-ssid`, `wireless-radio`, `wireless-auth`
Network	`network-wan`, `network-sim-lte`*, `network-lan`, `network-routing`, `network-nat`, `network-services`
Firewall & Security	`firewall-acl`, `firewall-traffic`, `firewall-ids`, `security-threat`, `security-wids`
VPN	`vpn`
Profiles & Schedules	`profiles`, `schedules`, `auth-profiles`
Logs	`logs`
Controller & Org	`controller`, `sites`, `maintenance`, `account-users`, `account-sso`*, `account-cloud`
Hotspot	`hotspot-portal`, `hotspot-vouchers`, `hotspot-users`*
Niche	`site-templates`, `voip`, `olt`, `msp`

Group aliases expand to all categories in their group:

Alias	Expands to
`all`	Every category
`devices-all`	`devices-general`, `devices-ap`, `devices-switch`, `devices-gateway`
`wireless-all`	`wireless-ssid`, `wireless-radio`, `wireless-auth`
`network-all`	`network-wan`, `network-lan`, `network-routing`, `network-nat`, `network-services`
`firewall-all`	`firewall-acl`, `firewall-traffic`, `firewall-ids`
`security-all`	`security-threat`, `security-wids`

Examples:

# Read-only access to everything
OMADA_TOOL_CATEGORIES=all:r

# Default safe subset (read only)
OMADA_TOOL_CATEGORIES=dashboard:r,client-insights:r,clients:r,devices-all:r

# Full access including write operations
OMADA_TOOL_CATEGORIES=all:rw

# Network read + client write operations
OMADA_TOOL_CATEGORIES=network-all:r,clients:rw

Omada Client Configuration

Variable	Required	Default	Description
`OMADA_BASE_URL`	Yes	-	Base URL of the Omada controller (e.g., `https://omada-controller.local`)
`OMADA_CLIENT_ID`	Yes	-	OAuth client ID generated under Omada Platform Integration
`OMADA_CLIENT_SECRET`	Yes	-	OAuth client secret associated with the client ID
`OMADA_OMADAC_ID`	Yes	-	Omada controller ID (omadacId) to target
`OMADA_SITE_ID`	No	-	Optional default site ID; if omitted, each MCP call must pass a siteId
`OMADA_STRICT_SSL`	No	`true`	Enforce strict SSL certificate validation (set to `false` for self-signed)
`OMADA_TIMEOUT`	No	`30000`	HTTP request timeout in milliseconds

MCP Generic Server Configuration

Variable	Required	Default	Description
`MCP_SERVER_LOG_LEVEL`	No	`info`	Logging verbosity (`debug`, `info`, `warn`, `error`, `silent`)
`MCP_SERVER_LOG_FORMAT`	No	`plain`	Log output format (`plain`, `json`, or `gcp-json`)
`MCP_SERVER_USE_HTTP`	No	`false`	Start HTTP server instead of stdio

Session IDs and authentication: When OMADA_CLIENT_ID, OMADA_CLIENT_SECRET, and OMADA_OMADAC_ID are provided (the default client-credentials mode), the server runs statelessly and treats the Mcp-Session-Id header as optional. A future OAuth-based user authentication mode will require this header again.

MCP Server HTTP Configuration

These variables are only used when MCP_SERVER_USE_HTTP=true:

Variable	Required	Default	Description
`MCP_HTTP_PORT`	No	`3000`	Port for the HTTP server
`MCP_HTTP_BIND_ADDR`	No	`127.0.0.1`	Bind address (IPv4/IPv6). Use atapter IP address to expose to the network.
`MCP_HTTP_PATH`	No	`/mcp`	Base path for MCP endpoints
`MCP_HTTP_ENABLE_HEALTHCHECK`	No	`true`	Enable a healthcheck endpoint
`MCP_HTTP_HEALTHCHECK_PATH`	No	`/healthz`	Path for the healthcheck endpoint
`MCP_HTTP_ALLOW_CORS`	No	`true`	Enable CORS for the HTTP server
`MCP_HTTP_ALLOWED_ORIGINS`	No	`127.0.0.1, localhost`	Comma-separated list of allowed origins. Use `*` to allow all (dev only)
`MCP_HTTP_NGROK_ENABLED`	No	`false`	Use ngrok to expose the HTTP server publicly
`MCP_HTTP_NGROK_AUTH_TOKEN`	No	-	Ngrok auth token (required if `MCP_HTTP_NGROK_ENABLED=true`)
Create a `.env` file (ignored by git) or export the variables before launching the server.

Development

npm run dev

The dev mode keeps the TypeScript server running with live reload support via tsx.

Building

npm run build

Linting

npm run check

Testing

Unit tests

npm test               # run all unit tests
npm run test:watch     # watch mode
npm run test:coverage  # with coverage report

Coverage thresholds:

Level	Metric	Threshold
Per-file	Lines, Statements, Functions	90%
Global	Branches	70%

Integration tests (Docker)

Not implemented yet — this section documents the planned integration test strategy tracked in #57 and #58.

Integration tests will run against a real Omada Software Controller in a Docker container. They are not planned to run on every PR — they serve as a milestone release gate and a test harness for write tools.

Planned layout:

test/docker/ (compose + snapshot/seed tooling)
tests/integration/
npm run test:integration

⚠️ Phase 2 write tools must only be tested against the Docker controller — never against a production controller.

Running the MCP server

npm start

The MCP server communicates over standard input and output. Integrate it with MCP-compatible clients by referencing the npm start command and providing the required environment variables.

Docker image

A container image is provided for running the MCP server:

npm run docker:build  # Build the Docker image (tag: jmtvms/tplink-omada-mcp:latest)
npm run docker:run    # Launch the container with your .env file
npm run docker:push   # Push the image to Docker Hub

You can also pull the pre-built image directly from Docker Hub:

docker pull jmtvms/tplink-omada-mcp:latest

The same image supports both stdio and HTTP transports - configure the desired mode using environment variables (e.g., set MCP_SERVER_USE_HTTP=true for HTTP mode).

Debugging with MCP Inspector

Use the MCP Inspector to interactively test tools, resources, and prompts without leaving your browser. The inspector automatically adapts to your .env configuration:

npm run inspector — Launches the inspector based on your .env settings:
- If MCP_SERVER_USE_HTTP=false (or unset): Runs the server in stdio mode with tsx src/index.ts for live reload debugging
- If MCP_SERVER_USE_HTTP=true: Connects to an already-running HTTP server at the configured port/transport (start the server first with npm run dev)
npm run inspector:build — Compiles the project first, then launches the inspector against the production build (dist/index.js) to verify release parity. Also adapts to stdio or HTTP mode based on .env.

Requirements: The inspector requires a .env file at the repository root. It will load both .env and .env.local (if present) to determine the server mode, port, transport, and path.

The MCP Inspector tool automatically binds to localhost and generates a session token for authentication (printed to the console and auto-filled in the browser URL).

Transport Protocols

The MCP server uses the Streamable HTTP transport, which implements the MCP protocol version 2025-03-26.

export MCP_SERVER_USE_HTTP=true
npm run dev

Features:

Single endpoint for all operations (GET, POST, DELETE)
Server-Sent Events for streaming responses
Built-in session management with cryptographic session IDs (the server currently operates statelessly when using client credentials)

The endpoint defaults to /mcp and handles:

GET /mcp - Establish SSE stream and initialize session
POST /mcp - Send JSON-RPC messages
DELETE /mcp - Terminate session

Security Considerations

DNS rebinding protection is enabled by default:

Origin Validation: The server validates the Origin header on all incoming connections. Configure allowed origins with MCP_HTTP_ALLOWED_ORIGINS (default: 127.0.0.1, localhost). Use * to allow all origins (development only, not recommended for production).
Network Binding: The server binds to 127.0.0.1 by default, restricting access to localhost only. Set MCP_HTTP_BIND_ADDR=0.0.0.0 to expose the server to your network (not recommended for production without additional security measures).

For more information on the MCP protocol and transports, see the Model Context Protocol documentation.

HTTP transport usage

Start the HTTP transport with:

# Start with HTTP enabled
export MCP_SERVER_USE_HTTP=true
npm run dev    # live reload during development
npm run start  # run the compiled output

By default, the server listens on 127.0.0.1:3000 and exposes the MCP endpoint at /mcp with a health check on /healthz. Configure the bind address, port, and path using the optional MCP_HTTP_* environment variables documented in .env.example. The npm run docker:run:http helper wraps the HTTP image and publishes the port automatically.

Using ngrok

To share the local server with remote tooling, you can use ngrok to expose the HTTP server publicly.

Option 1: Built-in ngrok support (recommended)

Set the following environment variables:

export MCP_HTTP_NGROK_ENABLED=true
export MCP_HTTP_NGROK_AUTH_TOKEN=your-ngrok-auth-token
npm run dev

The server will automatically establish an ngrok tunnel and log the public URL.

Option 2: Manual ngrok setup

Run ngrok in a separate terminal after starting the server:

ngrok http 3000

This forwards a public HTTPS URL to http://localhost:3000 and prints the tunnel address in the console.

In client-credentials mode the server already treats Mcp-Session-Id as optional; if the header is removed in transit, requests will still succeed.

Tools

Site & Client

Tool	Description
`listSites`	Lists all sites configured on the controller.
`getSiteCapacity`	Get site capacity settings including maximum device and client counts.
`getSiteDetail`	Get detailed information about a site, including name, region, timezone, and configuration.
`getSiteDeviceAccount`	Get device account settings for a site.
`getSiteNtpStatus`	Get NTP server status and configuration for a site.
`getSiteRememberSetting`	Get the remember device setting for a site.
`getSiteSpecification`	Get site specification including device limits and feature capabilities.
`getSiteUrl`	Get the URL associated with a site for OpenAPI access.
`getSiteTemplateConfig`	Get configuration settings for a site template. Requires `siteTemplateId`.
`getSiteTemplateDetail`	Get detailed information about a site template. Requires `siteTemplateId`.
`getSiteTemplateList`	List all site templates configured on the controller.
`listClients`	Lists active client devices for a site.
`getClient`	[DEPRECATED] Use `listClients` instead. When you have a client MAC, `getClientDetail` is also available. This tool filters the site client list in-process.
`listMostActiveClients`	Gets the most active clients sorted by traffic usage.
`listClientsActivity`	Gets client activity statistics over time.
`listClientsPastConnections`	Gets past connection history for clients.
`setClientRateLimit`	Sets custom bandwidth limits (download/upload) for a specific client.
`setClientRateLimitProfile`	Applies a predefined rate limit profile to a specific client.
`disableClientRateLimit`	Disables bandwidth rate limiting for a specific client.

Device

Tool	Description
`listDevices`	Lists provisioned devices for a given site.
`getDevice`	[DEPRECATED] Use `listDevices` instead and filter results client-side. This tool filters the site device list in-process; there is no dedicated device-detail endpoint.
`searchDevices`	Searches for devices globally across all sites the user has access to.
`listDevicesStats`	Queries statistics for global adopted devices with pagination and filtering.
`getSwitchStackDetail`	Retrieves detailed configuration and status for a switch stack.
`getSwitchDetail`	Fetches detailed configuration and status for a specific switch.
`getGatewayDetail`	Fetches detailed configuration and status for a specific gateway.
`getGatewayWanStatus`	Gets WAN port status for a specific gateway.
`getGatewayLanStatus`	Gets LAN port status for a specific gateway.
`getGatewayPorts`	Gets port information for a specific gateway.
`getApDetail`	Fetches detailed configuration and status for a specific access point.
`getApRadios`	Gets radio information for a specific access point.
`getStackPorts`	Gets port information for a switch stack.
`listPendingDevices`	Lists devices pending adoption in a site.
`getAllDeviceBySite`	Gets all devices in a site including offline and disconnected devices.
`getFirmwareInfo`	Gets the latest available firmware info for a device. Use `listDevices` for MACs.
`getGridAutoCheckUpgrade`	Gets the auto-check firmware upgrade plan list (paginated).
`listSwitchNetworks`	Lists VLAN network assignments for a switch (paginated). Requires `switchMac`.
`getSwitchGeneralConfig`	Gets general configuration for a switch. Requires `switchMac`.
`getCableTestLogs`	Gets cable test history for a switch. Requires `switchMac`.
`getCableTestFullResults`	Gets full per-port cable diagnostics for a switch. Requires `switchMac`.
`getOswStackLagList`	Gets Link Aggregation Group (LAG) list for a switch stack. Requires `stackId`.
`getStackNetworkList`	Gets VLAN network list for a switch stack (paginated). Requires `stackId`.
`getApUplinkConfig`	Gets uplink configuration for an AP (wired/mesh mode). Requires `apMac`.
`getRadiosConfig`	Gets per-radio configuration for an AP (channel, power, width). Requires `apMac`.
`getApVlanConfig`	Get VLAN configuration for an access point, including management VLAN and per-SSID VLAN tagging settings.
`getMeshStatistics`	Gets mesh link statistics for an AP. Requires `apMac`.
`getRFScanResult`	Gets last RF scan results for an AP. Requires `apMac`.
`getSpeedTestResults`	Gets last speed test results for an AP. Requires `apMac`.
`getApSnmpConfig`	Gets SNMP configuration for an AP. Requires `apMac`.
`getApLldpConfig`	Gets LLDP configuration for an AP. Requires `apMac`.
`getApGeneralConfig`	Gets general configuration for an AP (name, LED, country). Requires `apMac`.
`getUplinkWiredDetail`	Get wired uplink detail for an access point: uplink switch, port number, link speed, and PoE status.
`getDownlinkWiredDevices`	Gets wired downlink devices on an AP's LAN ports. Requires `apMac`.
`getFirmwareUpgradePlan`	Get the firmware upgrade plan list for devices managed by the controller.
`getUpgradeLogs`	Get firmware upgrade logs showing the history of upgrade operations performed on devices.
`getDeviceTagList`	Get the list of device tags defined in a site.
`getApQosConfig`	Get QoS configuration for a specific access point. Requires `apMac`.
`getApIpv6Config`	Get IPv6 configuration for a specific access point. Requires `apMac`.
`getSitesApsIpSetting`	Get IP settings for an AP. Requires `apMac`.
`getSitesApsChannelLimit`	Get channel limit configuration for an AP. Requires `apMac`.
`getSitesApsAvailableChannel`	Get list of available channels for an AP. Requires `apMac`.
`getSitesApsLoadBalance`	Get load balance configuration for an AP. Requires `apMac`.
`getSitesApsOfdma`	Get OFDMA configuration for an AP. Requires `apMac`.
`getSitesApsPowerSaving`	Get power saving configuration for an AP. Requires `apMac`.
`getSitesApsTrunkSetting`	Get trunk port setting for an AP. Requires `apMac`.
`getSitesApsBridge`	Get bridge configuration for an AP. Requires `apMac`.
`listSitesApsPorts`	List ports for an AP. Requires `apMac`.
`getSitesSwitchesEs`	Get ES switch details. Requires `switchMac`.
`getSitesSwitchesEsGeneralConfig`	Get ES switch general configuration. Requires `switchMac`.
`listSitesCableTestSwitchesPorts`	List cable test port info for a switch. Requires `switchMac`.
`listSitesCableTestSwitchesIncrementResults`	Get incremental cable test results for a switch. Requires `switchMac`.
`getUpgradeOverviewCritical`	Get the number of critical models available for upgrade.
`getUpgradeOverviewTryBeta`	Get the current status of the try-beta firmware upgrade switch.
`listUpgradeFirmwares`	List available firmware packages for upgrade (paginated).
`listUpgradeOverviewFirmwares`	List firmware overview for upgradeable devices (paginated).
`listSitesStacks`	List switch stacks in a site (paginated).
`getSitesDeviceWhiteList`	Get the device adoption whitelist for a site (paginated).
`getSitesGatewaysGeneralConfig`	Get general configuration for a gateway. Requires `gatewayMac`.
`getSitesGatewaysPin`	Get PIN information for a gateway. Requires `gatewayMac`.
`getSitesGatewaysSimCardUsed`	Get SIM card usage info for a gateway. Requires `gatewayMac`.
`getSitesHealthGatewaysWansDetails`	Get gateway WAN health details. Requires `gatewayMac`.

Network

Tool	Description
`getInternetInfo`	Gets internet configuration information for a site.
`getInternet`	[DEPRECATED] Use `getInternetInfo` instead. Gets full WAN/Internet configuration for the site gateway.
`getInternetBasicPortInfo`	Gets WAN port summary/basic info for the site gateway.
`getInternetLoadBalance`	Gets WAN load balancing configuration (failover/load balance).
`getWanPortsConfig`	Gets per-port WAN configuration including connection type and IP settings.
`getWanLanStatus`	Gets WAN-LAN connectivity status for a site.
`getGridVirtualWan`	Gets virtual WAN list (paginated).
`getIspBandScan`	Gets ISP band scan results for a WAN port. Requires `portUuid`.
`getDisableNatList`	Gets the list of wired networks with NAT disabled (paginated).
`getLtePortConfig`	Gets LTE/cellular WAN port configuration.
`getWanPortDetail`	[DEPRECATED] Use `getWanPortsConfig` instead. Gets detailed WAN port configuration for all gateway WAN ports.
`getWanIspProfile`	Gets ISP scan profile result for a WAN port. Requires `portUuid`.
`getWanQosConfig`	Gets QoS configuration for gateway WAN ports.
`getWanHealthDetail`	[DEPRECATED] Alias for the WAN health tool; kept for backward compatibility. Requires `gatewayMac`.
`getWanUsageStats`	[DEPRECATED] Use `getDashboardTrafficActivities` instead. Gets WAN traffic usage statistics for the site.
`getWanNatConfig`	Gets one-to-one NAT rules (paginated).
`getPortForwardingStatus`	Gets port forwarding status and rules. Required: `type` (`user` or `upnp`). Optional pagination: `page` (default 1), `pageSize` (default 10).
`getLanNetworkList`	[DEPRECATED] Use `getLanNetworkListV2` instead. This tool aggregates all pages; getLanNetworkListV2 is explicitly paginated.
`getLanNetworkListV2`	Get the LAN network list using the v2 API, with richer VLAN and DHCP data (paginated).
`getInterfaceLanNetwork`	Gets interface-level LAN network bindings. Optional type filter (0=WAN, 1=LAN).
`getInterfaceLanNetworkV2`	Get interface-level LAN network bindings (v2 API). Returns richer per-interface VLAN and network data.
`getLanProfileList`	Gets the list of LAN profiles configured in a site.
`getApLoadBalance`	[DEPRECATED] Use `getSitesApsLoadBalance` instead. Same endpoint, retained for backward compatibility. getSitesApsLoadBalance is the canonical tool name.
`getApOfdmaConfig`	[DEPRECATED] Use `getSitesApsOfdma` instead. Same endpoint, retained for backward compatibility. getSitesApsOfdma is the canonical tool name.
`getMulticastRateLimit`	Get multicast rate limit settings for a site.
`getWlanGroupList`	Gets the list of WLAN groups configured in a site.
`getSsidList`	Gets the list of SSIDs in a WLAN group.
`getSsidDetail`	Gets detailed information for a specific SSID. Required: `wlanId` and `ssidId`.
`listAllSsids`	Lists wireless SSIDs across all WLAN groups.
`getFirewallSetting`	Gets firewall configuration and rules for a site.
`getVpnSettings`	Gets VPN settings for a site.
`listSiteToSiteVpns`	Lists site-to-site VPN configurations.
`listPortForwardingRules`	[DEPRECATED] Use `getPortForwardingList` instead. Lists NAT port forwarding rules.
`listOsgAcls`	Lists gateway (OSG) ACL rules.
`listEapAcls`	Lists access point (EAP) ACL rules.
`listStaticRoutes`	[DEPRECATED] Use `getGridStaticRouting` instead. This tool aggregates all pages; getGridStaticRouting returns a single paginated page.
`getStaticRoutingInterfaceList`	Gets available interfaces for static routing.
`listPolicyRoutes`	[DEPRECATED] Use `getGridPolicyRouting` instead. This tool aggregates all pages; getGridPolicyRouting is paginated.
`getGridPolicyRouting`	Gets policy routing rules (paginated).
`getOspfProcess`	Gets OSPF process configuration for the site gateway.
`getOspfInterface`	Gets OSPF interface configuration for the site gateway.
`getVrrpConfig`	Gets VRRP configuration for OSW devices.
`getOspfNeighbors`	Gets OSPF neighbor devices for the site gateway.
`getGridOtoNats`	Gets 1:1 NAT rules (paginated).
`getAlg`	Gets ALG (Application Layer Gateway) configuration.
`getUpnpSetting`	Gets UPnP setting for the site gateway.
`getDdnsGrid`	Gets DDNS entries (paginated).
`getDhcpReservationGrid`	Gets DHCP reservations (paginated).
`getGridIpMacBinding`	Gets IP-MAC binding entries (paginated).
`getIpMacBindingGeneralSetting`	Gets IP-MAC binding global toggle setting.
`getBandwidthControl`	Gets global bandwidth control configuration.
`getGridBandwidthCtrlRule`	Gets bandwidth control rules (paginated).
`getSessionLimit`	Gets session limit global setting.
`getGridSessionLimitRule`	Gets per-rule session limit rules (paginated).
`getSnmpSetting`	Gets SNMP configuration (version, community string).
`getLldpSetting`	Gets LLDP global setting.
`getRemoteLoggingSetting`	Gets remote logging (syslog) configuration.
`getDnsCacheDataList`	Gets the DNS cache data list (paginated).
`getIptvSetting`	Gets IPTV service configuration for the site.
`getNtpSetting`	Gets NTP server configuration and synchronisation status.
`getSyslogConfig`	Deprecated; alias of `getRemoteLoggingSetting` for controller syslog configuration.
`getAccessControl`	Gets controller access control configuration.
`getDnsCacheSetting`	Gets DNS cache setting.
`getDnsProxy`	Gets DNS proxy configuration.
`getIgmp`	Gets IGMP snooping and proxy setting.
`getSwitchVlanInterface`	Gets VLAN interface configuration for a specific switch. Requires `switchMac`.
`getLanDnsRules`	Gets LAN DNS rules for the site (paginated).
`getLanProfileEsUsage`	Gets EAP/switch device usage for a LAN profile. Requires `profileId`.
`getLanClientCount`	Gets client distribution breakdown across LAN segments.
`listRadiusProfiles`	Lists RADIUS authentication profiles.
`listGroupProfiles`	Lists group profiles (IP, MAC, or port groups).
`getApplicationControlStatus`	Gets application control status for a site.
`getSshSetting`	Gets SSH settings for a site.
`listTimeRangeProfiles`	Lists time range profiles.
`getRateLimitProfiles`	Gets the list of available rate limit profiles for bandwidth control.

Firewall & ACL

Tool	Description
`getDot1xConfig`	Get 802.1X switch port authentication setting. Alias for `getSwitchDot1xSetting`.
`getRadiusProxyConfig`	Get global RADIUS proxy configuration (controller-level, no siteId).
`getApplicationAcl`	[DEPRECATED] Get application control rules. Alias for `getAppControlRules`.

Firewall Traffic & QoS

Tool	Description
`getGatewayQosClassRules`	Get gateway QoS class rules (paginated).
`getBandwidthCtrlDetail`	Get bandwidth control details for a site.
`getAppControlRules`	Get application control rules (paginated).
`getAppControlCategories`	Get application control category list.
`getUrlFilterRules`	Get URL filter gateway rules. Alias for `getGridGatewayRule`.
`getUrlFilterBlacklist`	Get URL filter MAC deny list. Alias for `getGridDenyMacFiltering`.
`getUrlFilterWhitelist`	Get URL filter MAC allow list. Alias for `getGridAllowMacFiltering`.
`getMacFilterDetail`	Get MAC filter general setting. Alias for `getMacFilteringGeneralSetting`.
`getQosPolicy`	Get QoS policy configuration for a site.
`getTrafficPriority`	Get traffic priority rules for a site.
`getTrafficStats`	[DEPRECATED] Use `getDashboardTrafficActivities` instead. Get WAN usage statistics. Alias for `getWanUsageStats`.
`getQosPolicyRule`	[DEPRECATED] Alias for `getQosPolicy`.
`getQosMarkingRule`	[DEPRECATED] Alias for `getQosPolicy`.
`getDscpConfig`	[DEPRECATED] Alias for `getQosPolicy`.

Firewall IDS / IPS

Tool	Description
`getGlobalSecuritySetting`	[DEPRECATED] Use `getThreatList` instead. Get global security/threat management list. Alias for `getThreatList`.

Security & Threat Management

Tool	Description
`getThreatList`	Gets global threat management list. Required: `archived` (bool). Optional: `startTime`/`endTime` (seconds since epoch), `severity` (0=Critical, 1=Major, 2=Moderate/Concerning, 3=Minor, 4=Low), `page`, `pageSize`.
`getTopThreats`	Gets top threats from the global threat management view.

Dashboard / Monitor

Tool	Description
`getDashboardWifiSummary`	Gets WiFi summary from the site dashboard.
`getDashboardSwitchSummary`	Gets switch summary from the site dashboard.
`getDashboardTrafficActivities`	Gets traffic activity data from the site dashboard.
`getDashboardPoEUsage`	Gets PoE usage data from the site dashboard.
`getDashboardTopCpuUsage`	Gets top CPU usage data from the site dashboard.
`getDashboardTopMemoryUsage`	Gets top memory usage data from the site dashboard.
`getDashboardMostActiveSwitches`	Gets most active switches from the site dashboard.
`getDashboardMostActiveEaps`	Gets most active access points from the site dashboard.
`getDashboardOverview`	Get the site overview: device counts, client counts, connectivity graph, and overall health status.
`getTrafficDistribution`	Gets traffic distribution by protocol/app type over a time range. Requires `start` and `end` timestamps (seconds).
`getRetryAndDroppedRate`	Gets wireless retry rate and dropped packet rate over a time range. Requires `start` and `end` timestamps (seconds).
`getIspLoad`	Gets per-WAN ISP link load over a time range. Requires `start` and `end` timestamps (seconds).
`getChannels`	Gets channel distribution and utilization across all APs.
`getInterference`	Gets top RF interference sources detected by APs.
`getGridDashboardTunnelStats`	Gets VPN tunnel statistics. Required: `type` (0 = Server, 1 = Client).
`getGridDashboardIpsecTunnelStats`	Gets IPsec tunnel statistics.
`getGridDashboardOpenVpnTunnelStats`	Gets OpenVPN tunnel statistics by type. Requires `type` parameter.

Insight

Tool	Description
`listSiteThreatManagement`	Lists site-level threat management events.
`getWids`	Gets WIDS (Wireless Intrusion Detection) information for a site.
`getRogueAps`	Gets rogue access points detected in a site.
`getVpnTunnelStats`	Gets VPN tunnel statistics for a site.

VPN

Tool	Description
`getIpsecTunnelList`	List all site-to-site VPN (IPsec) tunnels. Alias for `listSiteToSiteVpns`.
`getIpsecTunnelDetail`	Get detailed config for a specific IPsec tunnel by ID. Alias for `getSiteToSiteVpnInfo`.
`getAdvancedVpnSetting`	Get advanced VPN configuration settings for a site. Alias for `getVpnSettings`.
`getVpnUserList`	Get VPN users for a site (paginated).
`getVpnUserDetail`	Get users for a specific client-to-site VPN server.
`getVpnClientStatus`	Get status of client-to-site VPN clients. Alias for `listClientToSiteVpnClients`.
`getVpnRouteConfig`	[DEPRECATED] Use `getGridPolicyRouting` instead. This tool aggregates all pages; getGridPolicyRouting is paginated.

Profiles

Tool	Description
`getGoogleLdapProfile`	Get Google LDAP profile configuration for a site.
`getBuiltinRadiusUsers`	Get built-in RADIUS server user list (paginated).
`getRadiusUserDetail`	[DEPRECATED] Alias for `getBuiltinRadiusUsers`.
`getPpskNetworkProfile`	List PPSK network profiles for a site by type.
`getPpskUserGroup`	Get PPSK user group details for a specific profile.
`getPpskUserList`	[DEPRECATED] Alias for `getPpskUserGroup`.
`getServiceProfile`	Get service type profiles (paginated). Alias for `listServiceType`.
`getQosProfile`	Get rate limit profiles. Alias for `getRateLimitProfiles`.
`getScheduleProfile`	Get time range profiles. Alias for `listTimeRangeProfiles`.
`getGroupPolicyDetail`	Get group policy profiles filtered by group type.
`getIpGroupProfile`	[DEPRECATED] Get IP group profiles. Alias for `getGroupPolicyDetail` with groupType="0".
`getUrlGroupProfile`	[DEPRECATED] Get URL/port group profiles. Alias for `getGroupPolicyDetail` with groupType="1".
`getAppGroupProfile`	[DEPRECATED] Get MAC group profiles. Alias for `getGroupPolicyDetail` with groupType="2".
`getVlanProfile`	Get LAN/VLAN profiles. Alias for `getLanProfileList`.
`getUserRoleProfile`	Get user role profiles from the controller (global, no siteId).
`getPortalProfile`	Get captive portal profiles for a site.

Logs

Tool	Description
`listSiteEvents`	Lists site event logs.
`listSiteAlerts`	Lists site alert logs.
`listSiteAuditLogs`	Lists site audit logs.
`listGlobalEvents`	Lists global event logs across all sites.
`listGlobalAlerts`	Lists global alert logs across all sites.

Controller

Tool	Description
`getCertificate`	Get SSL/TLS certificate configuration for the controller.
`getClientHistoryDataEnable`	Get the client history data collection enable setting.
`getControllerPort`	Get the controller port configuration for device adoption.
`getDataRetention`	Get data retention settings for the controller.
`getExperienceImprovement`	Get the experience improvement program setting (telemetry).
`getGlobalDashboardOverview`	Get global controller dashboard overview without client data.
`getPortalPort`	Get portal port configuration for the controller web interface.

Maintenance

Tool	Description
`getBackupFileList`	List available controller backup files.
`getBackupResult`	Get the result of the most recent controller backup operation.
`getRestoreResult`	Get the result of the most recent controller restore operation.
`getSiteBackupFileList`	List available backup files for a site.
`getSiteBackupResult`	Get the backup result for a site.

Account Users

Tool	Description
`getAllCloudUsers`	List all cloud users on the controller, excluding the root account.
`getAllLocalUsers`	List all local users on the controller, excluding the root account.
`getAllRoles`	[DEPRECATED] Use `getUserRoleProfile` instead. List all user roles configured on the controller.
`getAllUsersApp`	List all users (cloud and local) in grid view.
`getAvailableRoles`	List roles available for user assignment.
`getRoleDetail`	Get detailed information about a specific role. Requires `roleId`.

Account Cloud

Tool	Description
`getCloudAccessStatus`	Get cloud access status for the controller.
`getCloudUserInfo`	Get cloud user account information.
`getMfaStatus`	Get global MFA (multi-factor authentication) status.
`getRemoteBindingStatus`	Get remote binding status between controller and cloud.

Schedules

Tool	Description
`getPoeScheduleList`	List PoE schedules for a site.
`getPortScheduleList`	List port schedules for a site.
`getPortSchedulePorts`	List ports with port schedule assignments for a site.
`getRebootScheduleList`	List device reboot schedules for a site template. Requires `siteTemplateId`.
`getUpgradeScheduleList`	List firmware upgrade schedules for a site.

Supported Omada API Operations

Operation ID	Description	Tool
`getSiteList`	List controller sites.	`listSites`
`getDeviceList`	List devices assigned to a site.	`listDevices`, `getDevice` [DEPRECATED]
`searchGlobalDevice`	Search for devices across all accessible sites.	`searchDevices`
`getGridAdoptedDevicesStatByGlobal`	Query statistics for global adopted devices.	`listDevicesStats`
`getOswStackDetail`	Retrieve details for a switch stack.	`getSwitchStackDetail`
`getSwitch`	Get detailed info for a specific switch.	`getSwitchDetail`
`getGateway`	Get detailed info for a specific gateway.	`getGatewayDetail`
`getGatewayWanPortStatus`	Get WAN port status for a specific gateway.	`getGatewayWanStatus`
`getGatewayLanPortStatus`	Get LAN port status for a specific gateway.	`getGatewayLanStatus`
`getGatewayPorts`	Get port info for a specific gateway.	`getGatewayPorts`
`getAp`	Get detailed info for a specific access point.	`getApDetail`
`getApRadios`	Get radio info for a specific access point.	`getApRadios`
`getStackPorts`	Get port info for a switch stack.	`getStackPorts`
`getGridPendingDevices`	List devices pending adoption in a site.	`listPendingDevices`
`getGridActiveClients`	List active clients connected to a site.	`listClients`, `getClient` [DEPRECATED]
`getMostActiveClients`	Get most active clients sorted by traffic.	`listMostActiveClients`
`getClientActivity`	Get client activity statistics over time.	`listClientsActivity`
`getGridPastConnections`	Get client past connection history.	`listClientsPastConnections`
`updateClientRateLimitSetting`	Set rate limit setting for a client.	`setClientRateLimit`, `setClientRateLimitProfile`, `disableClientRateLimit`
`getRateLimitProfileList`	Get rate limit profile list.	`getRateLimitProfiles`
`getGlobalThreatList`	Get global view threat management list.	`getThreatList`
`getTopThreatList`	Get top threats from global threat management.	`getTopThreats`
`getInternet`	[DEPRECATED] Use `getInternetInfo` instead. Get internet configuration info for a site.	`getInternetInfo`
`getPortForwardStatus`	Get port forwarding status by type.	`getPortForwardingStatus`
`getLanProfileList`	Get LAN profile list.	`getLanProfileList`
`getWlanGroupList`	Get WLAN group list.	`getWlanGroupList`
`getSsidList`	Get SSID list for a WLAN group.	`getSsidList`
`getSsidDetail`	Get detailed SSID configuration.	`getSsidDetail`
`getSsidListAll`	List SSIDs across all WLAN groups.	`listAllSsids`
`getFirewallSetting`	Get firewall configuration for a site.	`getFirewallSetting`
`getVpn`	Get VPN settings for a site.	`getVpnSettings`
`getSiteToSiteVpnList`	List site-to-site VPN configurations.	`listSiteToSiteVpns`
`getPortForwardingList`	List NAT port forwarding rules.	`getPortForwardingList` (prefer); `listPortForwardingRules` [DEPRECATED]
`getOsgAclList`	List gateway ACL rules.	`listOsgAcls`
`getEapAclList`	List access point ACL rules.	`listEapAcls`
`getStaticRoutingList`	List static routing rules.	`getGridStaticRouting` (prefer); `listStaticRoutes` [DEPRECATED]
`getRadiusProfileList`	List RADIUS authentication profiles.	`listRadiusProfiles`
`getGroupProfileList`	List group profiles (IP, MAC, port groups).	`listGroupProfiles`
`getApplicationControlStatus`	Get application control status for a site.	`getApplicationControlStatus`
`getSshSetting`	Get SSH settings for a site.	`getSshSetting`
`getTimeRangeProfileList`	List time range profiles.	`listTimeRangeProfiles`
`getWanLanStatus`	Get WAN-LAN connectivity status for a site.	`getWanLanStatus`
`getSiteThreatManagementList`	List site-level threat management events.	`listSiteThreatManagement`
`getWids`	Get WIDS information for a site.	`getWids`
`getRogueAps`	Get rogue access points detected in a site.	`getRogueAps`
`getVpnTunnelStats`	Get VPN tunnel statistics for a site.	`getVpnTunnelStats`
`getSiteEvents`	List site event logs.	`listSiteEvents`
`getSiteAlerts`	List site alert logs.	`listSiteAlerts`
`getSiteAuditLogs`	List site audit logs.	`listSiteAuditLogs`
`getEvents`	List global event logs across all sites.	`listGlobalEvents`
`getAlerts`	List global alert logs across all sites.	`listGlobalAlerts`
`disableClientRateLimit`	Disable rate limiting for a specific client, removing any bandwidth....	`disableClientRateLimit`
`getAccessControl`	Get controller access control configuration.	`getAccessControl`
`getAlg`	Get ALG (Application Layer Gateway) configuration for the site gateway.	`getAlg`
`getAllDeviceBySite`	Get all devices in a site including offline and disconnected devices.	`getAllDeviceBySite`
`getApDetail`	Fetch full configuration and status for a specific access point: mo....	`getApDetail`
`getApGeneralConfig`	Get general configuration for an access point.	`getApGeneralConfig`
`getApLldpConfig`	Get LLDP (Link Layer Discovery Protocol) configuration for an acces....	`getApLldpConfig`
`getApRadios`	Get radio status for a specific access point: 2.4GHz and 5GHz band ....	`getApRadios`
`getApSnmpConfig`	Get SNMP configuration for an access point.	`getApSnmpConfig`
`getApUplinkConfig`	Get the uplink configuration for an access point.	`getApUplinkConfig`
`getBandwidthControl`	Get the global bandwidth control configuration for the site.	`getBandwidthControl`
`getCableTestLogs`	Get cable test logs for a switch.	`getCableTestLogs`
`getChannels`	Get channel distribution and utilization across all APs.	`getChannels`
`getClient`	[DEPRECATED] Use `listClients` instead. When you have a client MAC, `getClientDetail` is also available. This tool filters the site client list in-process.	`getClient`
`getDashboardPoEUsage`	Get PoE (Power over Ethernet) usage statistics for a site, showing ....	`getDashboardPoEUsage`
`getDashboardSwitchSummary`	Get switch summary for a site dashboard: total switch count, total ....	`getDashboardSwitchSummary`
`getDashboardTopCpuUsage`	Get the top devices by CPU usage for a site, useful for identifying....	`getDashboardTopCpuUsage`
`getDashboardWifiSummary`	Get WiFi summary for a site dashboard: total APs, connected AP coun....	`getDashboardWifiSummary`
`getDdnsGrid`	Get DDNS (Dynamic DNS) entries for the site gateway.	`getDdnsGrid`
`getDevice`	[DEPRECATED] Use `listDevices` instead. This alias filters the device list in-process to return a single device; there is no separate device-detail API.	`getDevice`
`getDhcpReservationGrid`	Get DHCP reservations for the site.	`getDhcpReservationGrid`
`getDnsCacheSetting`	Get DNS cache setting for the site gateway.	`getDnsCacheSetting`
`getDnsProxy`	Get DNS proxy configuration for the site gateway.	`getDnsProxy`
`getFirewallSetting`	Get firewall configuration and rules for a site, including ACL rule....	`getFirewallSetting`
`getFirmwareInfo`	Get the latest available firmware information for a device.	`getFirmwareInfo`
`getGatewayDetail`	Fetch full configuration and status for a specific gateway: model, ....	`getGatewayDetail`
`getGatewayLanStatus`	Get LAN port status for a specific gateway: port link state, speed,....	`getGatewayLanStatus`
`getGatewayPorts`	Get all WAN and LAN port details for a specific gateway: link statu....	`getGatewayPorts`
`getGatewayWanStatus`	Get the WAN port status and connectivity information for a specific....	`getGatewayWanStatus`
`getGridBandwidthCtrlRule`	Get bandwidth control rules for the site gateway.	`getGridBandwidthCtrlRule`
`getGridIpMacBinding`	Get IP-MAC binding entries for the site.	`getGridIpMacBinding`
`getGridOtoNats`	Get 1:1 NAT rules for the site gateway.	`getGridOtoNats`
`getGridPolicyRouting`	Get policy routing rules for the site gateway.	`getGridPolicyRouting`
`getGridSessionLimitRule`	Get per-rule session limit rules for the site gateway.	`getGridSessionLimitRule`
`getGridVirtualWan`	Get virtual WAN list for the site gateway.	`getGridVirtualWan`
`getIgmp`	Get IGMP (Internet Group Management Protocol) setting for the site.	`getIgmp`
`getInterfaceLanNetwork`	Get interface-level LAN network bindings.	`getInterfaceLanNetwork`
`getInterference`	Get top RF interference sources detected by APs.	`getInterference`
`getInternet`	[DEPRECATED] Use `getInternetInfo` instead. Get full WAN/Internet configuration for the site gateway.	`getInternet`
`getInternetBasicPortInfo`	Get WAN port summary / basic info for the site gateway.	`getInternetBasicPortInfo`
`getInternetInfo`	Get internet configuration information for a site, including WAN se....	`getInternetInfo`
`getInternetLoadBalance`	Get WAN load balancing configuration for the site gateway.	`getInternetLoadBalance`
`getIspBandScan`	Get ISP band scan results for a WAN port. Requires `portUuid`.	`getIspBandScan`
`getIspLoad`	Get per-WAN ISP link load over a time range.	`getIspLoad`
`getLanClientCount`	Get client distribution breakdown across LAN segments (wired, wireless, guest).	`getLanClientCount`
`getLanDnsRules`	Get LAN DNS rules configured for the site (paginated).	`getLanDnsRules`
`getLanNetworkList`	[DEPRECATED] Use `getLanNetworkListV2` instead. This tool aggregates all pages; getLanNetworkListV2 is explicitly paginated.	`getLanNetworkList`
`getLanProfileEsUsage`	Get EAP/switch device usage for a specific LAN profile. Requires `profileId`.	`getLanProfileEsUsage`
`getLanProfileList`	Get the list of LAN profiles configured in a site.	`getLanProfileList`
`getLtePortConfig`	Get LTE/cellular WAN port configuration for the site gateway.	`getLtePortConfig`
`getLldpSetting`	Get LLDP (Link Layer Discovery Protocol) global setting for the site.	`getLldpSetting`
`getMeshStatistics`	Get mesh link statistics for an access point.	`getMeshStatistics`
`getOswStackLagList`	Get Link Aggregation Group (LAG) list for a switch stack.	`getOswStackLagList`
`getPortForwardingList`	Get a paginated page of NAT port forwarding rules for the site gateway.	`getPortForwardingListPage`
`getPortForwardingStatus`	Get port forwarding status and rules for a site.	`getPortForwardingStatus`
`getRFScanResult`	[DEPRECATED] Get the last RF scan results for an access point.	`getRFScanResult`
`getRadiosConfig`	Get per-radio configuration for an access point.	`getRadiosConfig`
`getRateLimitProfiles`	Get the list of available rate limit profiles for a site.	`getRateLimitProfiles`
`getRemoteLoggingSetting`	Get remote logging (syslog) configuration for the site.	`getRemoteLoggingSetting`
`getDnsCacheDataList`	Get the DNS cache data list for the site (paginated).	`getDnsCacheDataList`
`getDisableNatList`	Get the list of wired networks with NAT disabled (paginated).	`getDisableNatList`
`getIptvSetting`	Get IPTV service configuration for the site.	`getIptvSetting`
`getNtpSetting`	Get NTP server configuration and synchronisation status for the site.	`getNtpSetting`
`getOspfInterface`	Get OSPF interface configuration for the site gateway.	`getOspfInterface`
`getOspfNeighbors`	Get OSPF neighbor devices for the site gateway.	`getOspfNeighbors`
`getOspfProcess`	Get OSPF process configuration for the site gateway.	`getOspfProcess`
`getSwitchVlanInterface`	Get VLAN interface configuration for a specific switch. Requires `switchMac`.	`getSwitchVlanInterface`
`getSyslogConfig`	[DEPRECATED] Alias of `getRemoteLogging` for controller syslog configuration.	`getSyslogConfig`
`getVrrpConfig`	Get VRRP configuration for OSW devices on the site.	`getVrrpConfig`
`getWanHealthDetail`	[DEPRECATED] Alias for the WAN health tool; kept for backward compatibility. Requires `gatewayMac`.	`getWanHealthDetail`
`getWanIspProfile`	Get ISP scan profile result for a WAN port. Requires `portUuid`.	`getWanIspProfile`
`getWanNatConfig`	Get one-to-one NAT configuration (WAN NAT rules) for the site gateway (paginated).	`getWanNatConfig`
`getWanPortDetail`	[DEPRECATED] Use `getWanPortsConfig` instead. Get detailed WAN port configuration for all gateway WAN ports on the site.	`getWanPortDetail`
`getWanQosConfig`	Get QoS configuration for gateway WAN ports on the site.	`getWanQosConfig`
`getWanUsageStats`	[DEPRECATED] Use `getDashboardTrafficActivities` instead. Get WAN traffic usage statistics and activity data for the site.	`getWanUsageStats`
`getRetryAndDroppedRate`	Get wireless retry rate and dropped packet rate over a time range.	`getRetryAndDroppedRate`
`getRogueAps`	Get the list of rogue (unauthorized) access points detected by WIDS....	`getRogueAps`
`getSessionLimit`	Get the session limit global setting for the site gateway.	`getSessionLimit`
`getSnmpSetting`	Get SNMP configuration for the site.	`getSnmpSetting`
`getSpeedTestResults`	Get the last speed test results for an access point.	`getSpeedTestResults`
`getSshSetting`	Get SSH access settings for a site.	`getSshSetting`
`getSsidDetail`	Get detailed information for a specific SSID (wireless network), in....	`getSsidDetail`
`getSsidList`	Get the list of SSIDs (wireless networks) configured in a WLAN group.	`getSsidList`
`getStackNetworkList`	Get the VLAN network list for a switch stack.	`getStackNetworkList`
`getStackPorts`	Get all port information for a switch stack.	`getStackPorts`
`getSwitchDetail`	Fetch full configuration and status for a specific switch: model, f....	`getSwitchDetail`
`getSwitchStackDetail`	Fetch detailed information for a specific switch stack.	`getSwitchStackDetail`
`getThreatList`	Get the global view threat management list.	`getThreatList`
`getTopThreats`	Get the top threats from the global threat management view across a....	`getTopThreats`
`getTrafficDistribution`	Get traffic distribution by protocol and application type over a ti....	`getTrafficDistribution`
`getUpnpSetting`	Get UPnP (Universal Plug and Play) setting for the site.	`getUpnpSetting`
`getVpnSettings`	Get VPN configuration settings for a site.	`getVpnSettings`
`getVpnTunnelStats`	Get VPN tunnel statistics for a site (paginated), including active ....	`getVpnTunnelStats`
`getWanLanStatus`	Get the WAN and LAN connectivity status for a site.	`getWanLanStatus`
`getWanPortsConfig`	Get WAN port settings for the site gateway.	`getWanPortsConfig`
`getWids`	Get Wireless Intrusion Detection System (WIDS) information for a si....	`getWids`
`getWlanGroupList`	Get the list of WLAN groups configured in a site.	`getWlanGroupList`
`listAllSsids`	List all wireless SSIDs across all WLAN groups in a site: SSID name....	`listAllSsids`
`listClients`	List all network clients (wired and wireless) connected to a site.	`listClients`
`listClientsActivity`	Get client activity statistics over time from the dashboard.	`listClientsActivity`
`listClientsPastConnections`	Get client past connection list with historical connection data.	`listClientsPastConnections`
`listDevices`	List all provisioned (adopted) network devices in a site: gateways,....	`listDevices`
`listEapAcls`	List EAP (access point) ACL rules for a site: wireless client acces....	`listEapAcls`
`listGlobalAlerts`	List alert logs across all sites on the controller: threshold breac....	`listGlobalAlerts`
`listGlobalEvents`	List system event logs across all sites on the controller.	`listGlobalEvents`
`listGroupProfiles`	List group profiles (IP groups, MAC groups, port groups) configured....	`listGroupProfiles`
`listMostActiveClients`	Get the most active clients in a site, sorted by total traffic.	`listMostActiveClients`
`listOsgAcls`	List gateway (OSG) ACL rules for a site: firewall rules controlling....	`listOsgAcls`
`listPendingDevices`	List devices discovered on the network but not yet adopted into thi....	`listPendingDevices`
`listPolicyRoutes`	[DEPRECATED] Use `getGridPolicyRouting` instead. This tool aggregates all pages; getGridPolicyRouting is paginated.	`listPolicyRoutes`
`listPortForwardingRules`	[DEPRECATED] Use `getPortForwardingList` instead. List all NAT port forwarding rules for a site: external port, inter....	`listPortForwardingRules`
`listRadiusProfiles`	List RADIUS authentication profiles configured for a site: server I....	`listRadiusProfiles`
`listSiteAlerts`	List alert logs for a site: threshold breaches, device failures, se....	`listSiteAlerts`
`listSiteAuditLogs`	List admin audit logs for a site: who made what configuration chang....	`listSiteAuditLogs`
`listSiteEvents`	List system event logs for a site: device online/offline, client co....	`listSiteEvents`
`listSiteThreatManagement`	List site-level threat management events detected by IPS, with opti....	`listSiteThreatManagement`
`listSiteToSiteVpns`	List site-to-site VPN configurations: tunnel name, remote IP, statu....	`listSiteToSiteVpns`
`listSites`	List all sites configured on the Omada controller.	`listSites`
`listStaticRoutes`	[DEPRECATED] Use `getGridStaticRouting` instead. This tool aggregates all pages; getGridStaticRouting returns a single paginated page.	`listStaticRoutes`
`listSwitchNetworks`	List VLAN network assignments for a switch.	`listSwitchNetworks`
`listTimeRangeProfiles`	List time range profiles configured for a site.	`listTimeRangeProfiles`
`searchDevices`	Search for devices globally across all sites the user has access to.	`searchDevices`
`setClientRateLimit`	Set custom rate limit (bandwidth control) for a specific client.	`setClientRateLimit`
`getAclConfigTypeSetting`	Get the ACL configuration type setting for the site gateway (L2 or ....	`getAclConfigTypeSetting`
`getAttackDefenseSetting`	Get the DDoS and attack defense configuration, including flood prot....	`getAttackDefenseSetting`
`getAuditLogSettingForGlobal`	Get global audit log notification settings for the controller.	`getAuditLogSettingForGlobal`
`getAuditLogSettingForSite`	Get site-level audit log notification settings, including audit eve....	`getAuditLogSettingForSite`
`getAuditLogsForGlobal`	Get global audit logs (paginated).	`getAuditLogsForGlobal`
`getBandSteeringSetting`	Get the band steering configuration.	`getBandSteeringSetting`
`getBandwidthCtrl`	[DEPRECATED] Use `getBandwidthControl` instead. Get the global bandwidth control configuration for the site.	`getBandwidthControl`
`getBeaconControlSetting`	Get the beacon control setting, which manages 802.11 beacon transmi....	`getBeaconControlSetting`
`getChannelLimitSetting`	[DEPRECATED] Get the channel limit setting that restricts which cha....	`getChannelLimitSetting`
`getClientActiveTimeout`	Get the client inactivity timeout setting.	`getClientActiveTimeout`
`getClientDetail`	Get full detail for a specific client by MAC address, including con....	`getClientDetail`
`getClientToSiteVpnServerInfo`	Get detailed configuration for a specific client-to-site VPN server....	`getClientToSiteVpnServerInfo`
`getClientsDistribution`	Get client count distribution by connection type and band (wired, 2....	`getClientsDistribution`
`getControllerStatus`	Get the Omada controller health and status, including running state....	`getControllerStatus`
`getDeviceAccessManagement`	Get the device access management settings, controlling which device....	`getDeviceAccessManagement`
`getEapDot1xSetting`	Get the 802.1X EAP setting for access points, controlling port-base....	`—`
`getGeneralSettings`	Get the global general settings for the Omada controller, including....	`getGeneralSettings`
`getGridAllowList`	Get the IPS allow list (paginated).	`getGridAllowList`
`getGridAllowMacFiltering`	Get the MAC address allow-list entries (paginated).	`getGridAllowMacFiltering`
`getGridBlockList`	Get the IPS block list (paginated).	`getGridBlockList`
`getGridClientHistory`	Get per-client connection history (paginated).	`getGridClientHistory`
`getGridDenyMacFiltering`	Get the MAC address deny-list entries (paginated).	`getGridDenyMacFiltering`
`getGridEapRule`	Get the URL filter AP rules (paginated).	`getGridEapRule`
`getGridGatewayRule`	Get the URL filter gateway rules (paginated).	`getGridGatewayRule`
`getGridIpsecFailover`	Get IPsec failover configuration (paginated).	`getGridIpsecFailover`
`getGridKnownClients`	Get historical known clients list (paginated).	`getGridKnownClients`
`getGridSignature`	Get the IPS signature list (paginated).	`getGridSignature`
`getGridStaticRouting`	Get static routing rules for the site gateway with explicit pagination.	`getGridStaticRouting`
`getGroupProfilesByType`	Get group profiles filtered by type (e.g.	`getGroupProfilesByType`
`getIpsConfig`	Get the IPS (Intrusion Prevention System) global configuration, inc....	`getIpsConfig`
`getIpsecVpnStats`	Get IPsec VPN tunnel statistics for a site (paginated), including a....	`getIpsecVpnStats`
`getLdapProfileList`	List all LDAP authentication profiles configured on the site.	`getLdapProfileList`
`getLogSettingForGlobal`	Get global log notification settings (v1), including global alert r....	`getLogSettingForGlobal`
`getLogSettingForGlobalV2`	Get global log notification settings (v2), with extended notificati....	`—`
`getLogSettingForSite`	Get site-level log notification settings (v1), including alert reci....	`getLogSettingForSite`
`getLogSettingForSiteV2`	Get site-level log notification settings (v2), with extended notifi....	`—`
`getLogging`	Get the controller logging configuration, including log levels and ....	`getLogging`
`getMacAuthSetting`	Get the MAC authentication global setting.	`getMacAuthSetting`
`getMacAuthSsids`	Get per-SSID MAC authentication settings showing which SSIDs have M....	`getMacAuthSsids`
`getMacFilteringGeneralSetting`	Get the MAC filtering global setting.	`getMacFilteringGeneralSetting`
`getMailServerStatus`	Get the mail server connection status for the controller.	`getMailServerStatus`
`getMeshSetting`	Get the mesh networking configuration including mesh topology mode ....	`getMeshSetting`
`getOsgCustomAclList`	Get the custom gateway ACL rules list (paginated).	`getOsgCustomAclList`
`getOswAclList`	Get the switch ACL list (paginated).	`getOswAclList`
`getOuiProfileList`	Get the OUI-based device profile list (paginated).	`getOuiProfileList`
`getPPSKProfiles`	List Private PSK (PPSK) profiles for the site by type.	`getPPSKProfiles`
`getPastClientNum`	Get historical client count trend over a time range.	`getPastClientNum`
`getRadioFrequencyPlanningConfig`	Get the RF planning configuration for the site, including frequency....	`getRadioFrequencyPlanningConfig`
`getRadioFrequencyPlanningResult`	Get the RF planning result for the site.	`getRadioFrequencyPlanningResult`
`getRadiusServer`	Get the global RADIUS server configuration for the controller.	`getRadiusServer`
`getRadiusUserList`	List local RADIUS server users (paginated).	`getRadiusUserList`
`getRemoteLogging`	Get the global syslog/remote logging configuration, including syslo....	`getRemoteLogging`
`getRetention`	Get the data retention configuration for the controller, including ....	`getRetention`
`getRoamingSetting`	Get the client roaming configuration, including 802.11r/k/v setting....	`getRoamingSetting`
`getRoutingTable`	Get the live routing table for a site filtered by type.	`getRoutingTable`
`getServiceTypeSummary`	Get a summary of service type profiles for the site, including pred....	`getServiceTypeSummary`
`getSiteToSiteVpnInfo`	Get detailed information about a specific site-to-site VPN by ID, i....	`getSiteToSiteVpnInfo`
`getSsidsBySite`	Get a flat SSID list filtered by device type.	`getSsidsBySite`
`getSslVpnServerSetting`	Get the SSL VPN server configuration, including port, protocol, and....	`getSslVpnServerSetting`
`getSwitchDot1xSetting`	Get the 802.1X switch port authentication setting.	`—`
`getThreatCount`	Get the global threat count grouped by severity level (critical, hi....	`getThreatSeverity`
`getThreatDetail`	Get detailed information about a specific IPS threat event by its ID.	`getThreatDetail`
`getUiInterface`	Get the UI interface settings for the controller, including timeout....	`getUiInterface`
`getUrlFilterGeneral`	Get the URL filter global setting, including whether URL filtering ....	`getUrlFilterGeneral`
`getWebhookForGlobal`	Get the global webhook notification settings, including webhook URL....	`getWebhookForGlobal`
`getWebhookLogsForGlobal`	Get webhook dispatch logs (paginated).	`getWebhookLogsForGlobal`
`getWidsBlacklist`	Get the WIPS (Wireless Intrusion Prevention System) rogue AP blackl....	`getWidsBlacklist`
`getWireguardSummary`	Get a summary of WireGuard VPN configurations for the site, includi....	`getWireguardSummary`
`listClientToSiteVpnClients`	List all client-to-site VPN client configurations on the site.	`listClientToSiteVpnClients`
`listClientToSiteVpnServers`	List all client-to-site VPN server configurations on the site, incl....	`listClientToSiteVpnServers`
`listDevicesStats`	Query statistics for global adopted devices with pagination and fil....	`listDevicesStats`
`listMdnsProfile`	List all Bonjour/mDNS service profiles configured on the site for c....	`listMdnsProfile`
`listServiceType`	List service type profiles (paginated).	`listServiceType`
`listWireguard`	List WireGuard VPN tunnels (paginated).	`listWireguard`
`listWireguardPeers`	List WireGuard peers (paginated).	`listWireguardPeers`
`getDashboardMostActiveEaps`	Get the most active access points from the site dashboard by traffic.	`getDashboardMostActiveEaps`
`getDashboardTopMemoryUsage`	Get top memory usage data for devices from the site dashboard.	`getDashboardTopMemoryUsage`
`getDashboardTrafficActivities`	Get traffic activity data and throughput summary from the site dashboard.	`getDashboardTrafficActivities`
`getGridDashboardTunnelStats`	Get VPN tunnel statistics for the grid dashboard view.	`getGridDashboardTunnelStats`
`setClientRateLimitProfile`	Apply a predefined rate limit profile to a specific client.	`setClientRateLimitProfile`
`getGatewayQosClassRules`	Get gateway QoS class rules (paginated).	`getGatewayQosClassRules`
`getBandwidthCtrlDetail`	Get bandwidth control details for a site.	`getBandwidthCtrlDetail`
`getAppControlRules`	Get application control rules (paginated).	`getAppControlRules`
`getAppControlCategories`	Get application control category list.	`getAppControlCategories`
`getQosPolicy`	Get QoS policy configuration for a site.	`getQosPolicy`
`getTrafficPriority`	Get traffic priority rules for a site.	`getTrafficPriority`
`getVpnUserList`	Get VPN users for a site (paginated).	`getVpnUserList`
`getVpnUserDetail`	Get users for a specific client-to-site VPN server by ID.	`getVpnUserDetail`
`getGoogleLdapProfile`	Get Google LDAP profile configuration for a site.	`getGoogleLdapProfile`
`getPpskUserGroup`	Get PPSK user group details for a specific profile ID.	`getPpskUserGroup`
`getPortalProfile`	Get captive portal profiles for a site.	`getPortalProfile`
`getUserRoleProfile`	Get user role profiles from the controller (global).	`getUserRoleProfile`
`getRadiusProxyConfig`	Get global RADIUS proxy configuration (controller-level).	`getRadiusProxyConfig`
`getSiteEntity`	Get site detail.	`getSiteDetail`
`getSiteUrlByOpenApi`	Get site URL.	`getSiteUrl`
`getNtpServerStatus`	Get NTP server status for a site.	`getSiteNtpStatus`
`getSiteSpecification`	Get site specification.	`getSiteSpecification`
`getSiteRememberSettingByOpenApi`	Get site remember device setting.	`getSiteRememberSetting`
`getSiteDeviceAccountSetting`	Get site device account setting.	`getSiteDeviceAccount`
`getSiteSettingCap`	Get site capacity setting.	`getSiteCapacity`
`getSiteTemplateList`	List site templates.	`getSiteTemplateList`
`getSiteTemplateEntity`	Get site template detail.	`getSiteTemplateDetail`
`getSiteTemplateConfiguration`	Get site template configuration.	`getSiteTemplateConfig`
`getDataRetention`	Get data retention settings.	`getDataRetention`
`getControllerPort`	Get controller port setting.	`getControllerPort`
`getPortalPort`	Get portal port setting.	`getPortalPort`
`getCertificate`	Get certificate configuration.	`getCertificate`
`getExpImprove`	Get experience improvement setting.	`getExperienceImprovement`
`getGernalSettings_1`	Get global dashboard overview without client data.	`getGlobalDashboardOverview`
`getClientHistoryDataEnable`	Get client history data enable setting.	`getClientHistoryDataEnable`
`getSelfServerFileList`	List controller backup files.	`getBackupFileList`
`getBackupResult`	Get controller backup result.	`getBackupResult`
`getRestoreResult`	Get controller restore result.	`getRestoreResult`
`getSiteBackupResult`	Get site backup result.	`getSiteBackupResult`
`getSelfServerSiteFileList`	List site backup files.	`getSiteBackupFileList`
`getAllCloudUsersExcludeRoot`	List all cloud users excluding root.	`getAllCloudUsers`
`getAllLocalUsersExcludeRoot`	List all local users excluding root.	`getAllLocalUsers`
`getAllRoles`	[DEPRECATED] Use `getUserRoleProfile` instead. List all roles.	`getAllRoles`
`getRole`	Get role detail.	`getRoleDetail`
`getAvailableRole`	List available roles.	`getAvailableRoles`
`getAppGridUsers`	List all users in app grid view.	`getAllUsersApp`
`getCloudAccessStatus`	Get cloud access status.	`getCloudAccessStatus`
`getCloudUserInfo`	Get cloud user info.	`getCloudUserInfo`
`getGlobalMFAStatus`	Get global MFA status.	`getMfaStatus`
`getRemoteBindingStatus`	Get remote binding status.	`getRemoteBindingStatus`
`getUpgradeScheduleList`	List upgrade schedules for a site.	`getUpgradeScheduleList`
`getRebootScheduleList_1`	List reboot schedules for a site template.	`getRebootScheduleList`
`getPoeScheduleList`	List PoE schedules for a site.	`getPoeScheduleList`
`getPortScheduleList`	List port schedules for a site.	`getPortScheduleList`
`getPortSchedulePorts`	List ports with port schedules.	`getPortSchedulePorts`
`getMulticastRateLimitByOpenApi`	Get multicast rate limit setting.	`getMulticastRateLimit`
`getApLoadBalanceConfig`	Get AP load balance configuration.	`getApLoadBalance`
`getApOfdmaConfig`	[DEPRECATED] Use `getSitesApsOfdma` instead. Same endpoint, retained for backward compatibility. getSitesApsOfdma is the canonical tool name.	`getApOfdmaConfig`

Devcontainer support

The repository includes a ready-to-use devcontainer configuration with a dedicated Omada controller sidecar for local development and testing. See .devcontainer/README.md for details.

License

This project is licensed under the MIT License.

Available Tools

84 tools

getAllDeviceBySiteA

Get all devices in a site including offline and disconnected devices. Unlike listDevices which may filter to active-only, this returns the full device inventory. Useful for auditing what hardware is registered to a site.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.6/5.0

Behavior4/5

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

No annotations, but description honestly discloses the inclusive behavior. Lacks discussion of potential performance or rate limits.

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

Conciseness5/5

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

Two efficient sentences, front-loaded with purpose and key differentiator. No fluff.

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

Completeness4/5

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

No output schema, but description is sufficient for a list-all tool. Could add note on pagination but not necessary given sibling tools.

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

Parameters4/5

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

Schema has 100% coverage; description adds useful context like default siteId behavior and customHeaders rarity.

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

Purpose5/5

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

Clearly states it gets all devices in a site including offline/disconnected, and explicitly differentiates from listDevices.

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

Usage Guidelines5/5

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

Explicitly says when to use (auditing full inventory) and contrasts with listDevices for active-only.

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

getApDetailA

Fetch full configuration and status for a specific access point: model, firmware, CPU/memory, connected clients count, SSIDs, uptime, and mesh status. Use listDevices to get the apMac.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description must disclose behavioral traits. It implies a read-only operation by saying 'Fetch', but does not mention authorization, rate limits, side effects, or response volume. This is adequate but not thorough.

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

Conciseness5/5

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

The description is two sentences: the first lists what the tool fetches (front-loaded purpose), the second provides a key usage hint. No wasted words.

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

Completeness4/5

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

Without an output schema, the description lists the expected return fields (model, firmware, etc.), which is sufficient for a fetch operation. It also covers prerequisite steps for parameters. Minor gap: no mention of response format (e.g., JSON).

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3. The description adds value by explaining how to obtain the apMac (via listDevices) and siteId (via listSites, with default fallback), going beyond the schema's raw descriptions.

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

Purpose5/5

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

The description uses a specific verb ('Fetch') and resource ('full configuration and status for a specific access point'), and lists concrete fields (model, firmware, etc.). This clearly distinguishes it from sibling tools like getApGeneralConfig or getApRadios, which fetch only partial data.

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

Usage Guidelines4/5

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

The description explicitly guides the user to 'Use listDevices to get the apMac', which is a prerequisite. However, it does not contrast with alternatives or state exclusions (e.g., when not to use).

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

getApGeneralConfigA

Get general configuration for an access point. Returns device name, LED settings, country/region, management VLAN, bandwidth limits, and other global AP parameters. Use getApDetail for runtime status; this returns stored configuration.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.2/5.0

Behavior3/5

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

Discloses that the tool returns stored configuration (not runtime), but lacks details on error handling, authentication requirements, or rate limits. With no annotations, the description carries full burden; more behavioral cues would improve transparency.

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

Conciseness5/5

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

Two sentences: first defines purpose and contents, second provides usage guidance. No redundant phrases, efficiently communicates key information.

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

Completeness4/5

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

Lists several returned fields, enough to understand scope. No output schema exists, but the description gives a reasonable overview. Could mention error cases or that return is a JSON object with nested parameters.

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

Parameters4/5

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

Schema covers all 3 parameters (100% coverage). Description adds value by referencing help tools for apMac (listDevices) and siteId (listSites), going beyond the schema's format descriptions.

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

Purpose5/5

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

Clearly states the verb 'Get' and resource 'general configuration for an access point', listing specific returned fields. Distinguishes from siblings like getApDetail by noting it returns stored configuration vs runtime status.

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

Usage Guidelines4/5

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

Explicitly advises using getApDetail for runtime status, providing a direct alternative. While it doesn't list exhaustive when-not-to-use scenarios, the single contrast is sufficient for clear differentiation.

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

getApIpv6ConfigB

Get IPv6 configuration for a specific access point.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3/5.0

Behavior2/5

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

No annotations provided, so description bears full burden. Only states 'Get' implying read-only, but fails to disclose error behavior (e.g., AP not found), rate limits, or required permissions. Lacks details on what 'IPv6 configuration' entails.

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

Conciseness3/5

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

Single sentence is concise, but under-specified. Could be improved by adding usage context without significant length increase.

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

Completeness2/5

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

No output schema, so description should explain return value or clarify scope. Lacks information on site dependency, return format, or relationship with other AP config getters. Incomplete for a tool with 3 parameters and nested objects.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are fully documented in schema. Description adds no additional meaning beyond schema fields. Baseline score of 3 applies.

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

Purpose5/5

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

Description clearly states verb 'Get' and resource 'IPv6 configuration' for a specific access point. Distinguishes from siblings like getApGeneralConfig, getApLldpConfig, etc., which target different configuration types.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. Does not mention prerequisites (e.g., AP must be adopted), context for IPv6 vs IPv4, or when to prefer sibling tools like getApGeneralConfig.

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

getApLldpConfigB

Get LLDP (Link Layer Discovery Protocol) configuration for an access point. Returns enabled state and advertised TLVs. LLDP allows network devices to advertise identity and capabilities to neighbours.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.3/5.0

Behavior3/5

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

No annotations provided, so description carries the burden. It indicates a read operation with no side effects, but lacks details on prerequisites (e.g., AP must be adopted, needed permissions). Adequate but minimal.

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

Conciseness3/5

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

Two sentences; the first is concise and informative. The second sentence ('LLDP allows...') is generic and may not be necessary for an AI agent, slightly reducing efficiency.

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

Completeness3/5

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

Given no output schema and simple parameters, the description covers the basic purpose and return. But it omits potential error conditions or state dependencies (e.g., AP offline). Moderately complete.

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

Parameters3/5

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

Schema covers 100% of parameters with descriptions, including format and defaults. The tool description adds no extra semantic value beyond the schema. Baseline 3 is appropriate.

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

Purpose5/5

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

Description explicitly states 'Get LLDP configuration for an access point' and specifies the return values ('enabled state and advertised TLVs'), clearly distinguishing it from sibling tools like getApGeneralConfig or getApSnmpConfig.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as getApGeneralConfig or getApSnmpConfig. The description does not provide context for when LLDP configuration is relevant or when not to use it.

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

getApQosConfigA

Get QoS configuration for a specific access point.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. However, it only states the purpose and does not mention that the operation is read-only, requires no special permissions, or any other behavioral aspects. The lack of transparency is significant for a tool with no annotations.

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

Conciseness5/5

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

The description is a single, well-structured sentence with only 10 words. Every word earns its place, and there is no redundant or extraneous information.

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

Completeness3/5

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

Given no output schema and a simple read operation, the description is minimally viable but lacks context about return format, error handling, or any side effects. It could be more helpful by stating that the QoS configuration is returned, but it does not.

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

Parameters3/5

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

Schema description coverage is 100%—all parameters have descriptions in the schema. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline for this dimension.

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

Purpose5/5

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

The description 'Get QoS configuration for a specific access point' clearly specifies the verb 'Get', the resource 'QoS configuration', and the scope 'for a specific access point'. It effectively distinguishes from sibling tools like getApGeneralConfig or getApIpv6Config.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives (e.g., other getAp* tools). The usage is implied by the tool name and description, but there is no mention of when not to use it or alternative tools for similar tasks.

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

getApRadiosA

Get radio status for a specific access point: 2.4GHz and 5GHz band config, channel, TX power, channel utilization, and associated client count per radio. Use listDevices to get the apMac.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose any behavioral traits like side effects, authorization requirements, or rate limits. It only describes the output content without addressing potential impacts or constraints.

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

Conciseness5/5

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

Two sentences: first provides a dense, informative overview of the output; second offers a practical prerequisite tip. No superfluous words. Well-structured and front-loaded.

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

Completeness4/5

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

Given the tool has no output schema, the description adequately enumerates key return fields. However, it omits structural details (e.g., whether the response is an object or array) and error scenarios. Slightly incomplete for a tool with 3 parameters.

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

Parameters3/5

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

Schema coverage is 100%, and the description adds minimal value beyond the schema descriptions. The note about using listDevices for apMac is helpful but not parameter-specific semantics. Baseline 3 is appropriate.

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

Purpose5/5

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

The description specifies the exact verb 'Get', the resource 'radio status', and lists the specific data fields (band config, channel, TX power, channel utilization, client count). It also distinguishes from sibling tools by focusing on radio status rather than general AP detail or config.

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

Usage Guidelines3/5

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

The description mentions a prerequisite ('Use listDevices to get the apMac') but does not provide guidance on when to use this tool versus alternatives such as getApDetail or getRadiosConfig. No explicit when-not or exclusion criteria.

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

getApSnmpConfigA

Get SNMP configuration for an access point. Returns SNMP version, community strings, trap settings, and enabled state. Useful for auditing SNMP-based monitoring configurations on wireless infrastructure.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations, the description must disclose behavioral traits. It implies a non-destructive read operation but does not explicitly state read-only status, auth requirements, or potential side effects. The listed return fields provide some transparency.

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

Conciseness5/5

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

The description is very concise: two sentences that front-load the purpose and provide immediate value. No redundant or unnecessary information.

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

Completeness4/5

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

For a simple query tool, the description adequately explains what the tool returns and its purpose. No output schema is present, but the description compensates by listing return fields. Could be improved by noting required permissions or rate limits.

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

Parameters3/5

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

Schema coverage is 100%, and the description does not add any parameter-level meaning beyond what the schema already provides. Baseline score of 3 is appropriate.

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

Purpose4/5

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

Description clearly states the verb ('Get') and the resource ('SNMP configuration for an access point'), and lists what is returned. However, it does not explicitly distinguish from sibling tools like getApDetail or getApGeneralConfig, which limits differentiation.

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

Usage Guidelines3/5

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

The description provides a use case ('auditing SNMP-based monitoring configurations') but lacks explicit guidance on when to use this tool versus alternatives, and does not mention when not to use it.

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

getApUplinkConfigA

Get the uplink configuration for an access point. Returns uplink mode (wired/wireless mesh), preferred uplink settings, and failover configuration. Useful for understanding mesh topology and wired uplink assignments.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior4/5

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

With no annotations, the description clearly indicates a read-only operation via 'Get' and describes the return information. It does not disclose permissions or rate limits, but for a simple read operation this is sufficient.

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

Conciseness5/5

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

Two concise sentences that front-load the main action and return data. No unnecessary words or repetition.

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

Completeness4/5

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

No output schema exists, but the description lists the key return fields. Parameters are well-documented in the schema. For a simple get operation, the description is complete enough.

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

Parameters3/5

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

Schema coverage is 100%, so the baseline is 3. The description does not add additional meaning to the parameters beyond what the schema already provides (e.g., apMac pattern and examples).

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

Purpose5/5

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

The description clearly states the verb 'Get' and the specific resource 'uplink configuration for an access point'. It lists the three types of data returned, which distinguishes it from sibling tools that focus on other aspects like general config, radios, etc.

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

Usage Guidelines3/5

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

The description does not explicitly state when to use this tool versus alternatives, nor does it provide exclusions. The context of 'uplink configuration' implies its scope, but no direct comparison with sibling tools is given.

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

getApVlanConfigA

Get VLAN configuration for an access point. Returns the AP's management VLAN and per-SSID VLAN tagging settings. Useful for verifying network segmentation on wireless infrastructure.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior2/5

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

No annotations provided, and the description only states the tool is read-only and returns specific data. It lacks disclosure of error handling, authentication requirements, or other behavioral traits.

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

Conciseness5/5

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

Two concise sentences that front-load the purpose and add a use case. No unnecessary words or repetition.

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

Completeness4/5

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

Given no output schema, the description adequately explains the return values (management VLAN and per-SSID settings). Lacks error case details but is sufficient for a simple read operation.

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

Parameters3/5

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

Schema coverage is 100% with detailed descriptions for all parameters. The description adds no new information beyond what the schema already provides, so baseline score of 3 is appropriate.

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

Purpose5/5

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

Description clearly states it retrieves VLAN configuration for an access point, specifying the resource (VLAN config) and the scope (per-SSID). Distinguishes well from sibling tools like getApGeneralConfig or getApRadios.

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

Usage Guidelines3/5

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

Mentions a use case (verifying network segmentation) but does not explicitly state when to use this tool over alternatives like getApDetail or when not to use it.

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

getCableTestFullResultsA

Get full cable test results for all ports on a switch. Returns detailed per-port diagnostic data including cable status (OK/open/short), estimated cable length, and fault location. More detailed than getCableTestLogs.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior2/5

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

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states what data is returned but does not mention whether the operation is read-only, requires special permissions, or has any side effects, leaving a significant gap for a tool with no safety annotations.

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

Conciseness5/5

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

The description is extremely concise with two sentences, front-loads the verb and resource, includes a sibling comparison, and contains no superfluous information.

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

Completeness4/5

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

Given the absence of an output schema, the description offers a reasonable overview of return fields (cable status, length, fault location) and implies an array structure per port, which is sufficient for an agent to understand the nature of the output, though full completeness would require more structural detail.

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

Parameters3/5

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

The input schema covers all three parameters with descriptions, achieving 100% schema description coverage. The description does not add extra meaning or usage details beyond what the schema already provides, meeting the baseline but not exceeding it.

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

Purpose5/5

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

The description clearly states it retrieves full cable test results for all ports on a switch, and distinguishes itself from the sibling tool getCableTestLogs by noting it provides more detailed data including cable status, length, and fault location.

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

Usage Guidelines4/5

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

The description explains when to use the tool (for detailed per-port diagnostics) and compares it to getCableTestLogs as a less detailed alternative, but does not explicitly state when not to use it or mention other alternatives among the many sibling tools.

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

getCableTestLogsB

Get cable test logs for a switch. Returns history of cable diagnostics including per-port test results, cable length estimates, and fault detection. Useful for diagnosing physical layer connectivity issues.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are present, so the description bears full responsibility for behavioral disclosure. It does not mention side effects, permissions, rate limits, or whether the operation is read-only, leaving uncertainty.

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

Conciseness5/5

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

Two concise sentences with no wasted words. The first sentence immediately specifies the action and resource, making it easy for an agent to parse.

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

Completeness4/5

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

Given no output schema or annotations, the description adequately explains the return content (history, per-port results, length estimates, fault detection). It covers the core need but lacks details on pagination or sorting.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter-level context, meeting the baseline expectation.

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

Purpose4/5

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

The description clearly states it retrieves cable test logs for a switch, including specific details like per-port results and fault detection. It differentiates from sibling 'getCableTestFullResults' by focusing on 'logs' (history) versus full results, though not explicit.

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

Usage Guidelines3/5

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

The description provides a use case ('diagnosing physical layer connectivity issues') but lacks explicit when-to-use or when-not-to-use guidance compared to sibling tools. No alternatives are mentioned.

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

getClientA

[DEPRECATED] Use listClients instead. When you have a client MAC, getClientDetail is also available. This tool filters the site client list in-process to emulate a per-client lookup. Fetch details for a specific Omada client.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`clientId`	Yes
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It discloses that the tool filters the site client list in-process to emulate a per-client lookup, implying potential inefficiency. However, it does not mention authentication requirements, rate limits, or behavior when clientId is not found. The deprecation notice is a positive disclosure.

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

Conciseness4/5

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

Two sentences: first covers deprecation and alternatives, second explains the mechanism and purpose. No wasted words, but could be more structured with bullet points. Efficient for the content.

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

Completeness3/5

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

Given no output schema and moderate parameter count, the description explains the basic behavior and usage context (deprecation, alternative methods). However, it lacks details on return values, error states, or specific behavior differences from alternatives. Adequate but not fully comprehensive.

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

Parameters3/5

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

Schema description coverage is 67% (siteId and customHeaders have descriptions, clientId does not). The description does not add meaning for clientId beyond what the schema lacks. It references client MAC but does not reinforce that clientId is required. Baseline score due to moderate coverage without additional value.

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

Purpose4/5

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

The description clearly states it fetches details for a specific Omada client, using verb 'Fetch' and resource 'specific Omada client'. It also adds that it filters the site client list in-process, which clarifies its scope. The deprecation notice does not confuse the purpose.

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

Usage Guidelines5/5

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

Explicitly guides to use listClients instead of this deprecated tool, and mentions getClientDetail when a client MAC is available. This provides clear when-to-use and when-not-to-use guidance relative to alternatives.

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

getClientDetailA

Get full detail for a specific client by MAC address, including connection info, IP, VLAN, signal strength, and traffic stats.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`clientMac`	Yes	MAC address of the client to retrieve details for.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior3/5

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

With no annotations, the description carries full burden. It states what data is returned but omits behavioral traits such as whether the client must be online, if the tool is rate-limited, or that siteId defaults to a configured site (not mentioned). Adequate but not fully transparent.

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

Conciseness5/5

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

A single sentence that is concise, front-loaded with key information, and contains no extraneous content.

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

Completeness4/5

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

For a tool with 3 parameters, no output schema, and no annotations, the description is fairly complete. It explains the tool's purpose and returned fields. However, it could improve by noting that the client must be currently connected (likely) or any other contextual limitations.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific details beyond what the schema provides; it focuses on the output. Schema already documents clientMac as required and siteId with default behavior.

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

Purpose5/5

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

The description specifies a clear action ('Get full detail') and resource ('specific client by MAC address'), listing key data fields (connection info, IP, VLAN, signal strength, traffic stats). This distinguishes it from sibling tools like 'getClient' (likely simpler) and 'listClients' (list all).

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

Usage Guidelines3/5

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

The description implicitly indicates usage when full client details are needed by MAC, but lacks explicit guidance on when to prefer this tool over alternatives (e.g., 'getClient' for summary, 'listClients' for all clients). No prerequisites or exclusions are mentioned.

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

getClientsDistributionA

Get client count distribution by connection type and band (wired, 2.4GHz, 5GHz, 6GHz). Useful for understanding the network composition at a glance.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as side effects, required permissions, or rate limits. The read-only nature is implied but not explicitly stated.

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

Conciseness5/5

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

The description is two concise sentences. The main purpose is front-loaded, and every word adds value without unnecessary detail.

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

Completeness4/5

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

Given moderate complexity with nested objects and no output schema, the description adequately explains the tool's output conceptually. However, it could benefit from mentioning the return format (e.g., 'returns an object with bands as keys').

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

Parameters3/5

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

With 100% schema description coverage, the description adds no additional meaning beyond what the input schema already provides for siteId and customHeaders. Baseline 3 applies.

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

Purpose5/5

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

The description clearly states the verb 'Get' and the resource 'client count distribution', specifying grouping by connection type and band. It effectively distinguishes from sibling tools that focus on devices, APs, or traffic.

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

Usage Guidelines3/5

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

The description provides a use case ('useful for understanding network composition at a glance') but does not offer explicit guidance on when to use this tool versus alternatives like listClients or getTrafficDistribution.

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

getDashboardMostActiveEapsA

Get the most active access points (EAPs) in a site, sorted by traffic volume.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It states the tool retrieves data sorted by traffic volume, but doesn't disclose read-only nature, pagination, or response format. Adequate for a simple retrieval.

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

Conciseness5/5

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

A single, well-structured sentence that conveys the tool's purpose efficiently with no extraneous words.

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

Completeness4/5

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

The tool is simple, and the description covers its core function. Lacks details about output structure, but given no output schema, the description provides a reasonable overview.

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

Parameters3/5

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

Schema coverage is 100% with good field descriptions. The description adds 'sorted by traffic volume' but that pertains to output, not parameters. No additional parameter meaning is added.

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

Purpose5/5

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

The description clearly states the verb ('Get'), resource ('most active access points'), and scope ('in a site, sorted by traffic volume'), distinguishing it from siblings like getDashboardMostActiveSwitches.

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

Usage Guidelines3/5

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

No explicit when-to-use or when-not-to-use guidance is provided. The siteId parameter description hints at default behavior, but there is no comparison with alternative tools.

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

getDashboardMostActiveSwitchesA

Get the most active switches in a site, sorted by traffic volume.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior2/5

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

With no annotations provided, the description carries full burden for behavioral transparency. However, it adds minimal behavioral context: it does not state that the tool is read-only, what happens when a site has no switches, or any rate limits. The description essentially repeats the tool name's implication without enriching the agent's understanding of side effects or constraints.

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

Conciseness5/5

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

A single sentence of 10 words that captures the tool's core purpose without redundancy. Every word earns its place. The structure is front-loaded and efficient.

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

Completeness4/5

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

For a simple list-retrieval tool with two parameters and no output schema, the description is largely complete: it states what is returned (most active switches) and how it's sorted (by traffic volume). The parameter descriptions in the schema handle parameter semantics. Additional details about return format (e.g., list of switch IDs/names with traffic metrics) are not critical but could slightly improve completeness for agents.

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

Parameters3/5

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

Schema description coverage is 100%: both parameters have descriptions. The tool description does not add any information beyond what the schema already provides for parameters. Baseline is 3, and no extra value is contributed by the description.

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

Purpose5/5

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

The description 'Get the most active switches in a site, sorted by traffic volume' clearly specifies a verb ('Get'), resource ('most active switches'), scope ('in a site'), and ordering ('sorted by traffic volume'). It distinguishes itself from siblings like getSitesSwitchesEs (which lists all switches) and getDashboardMostActiveEaps (which targets EAPs, not switches), effectively conveying its unique purpose.

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

Usage Guidelines3/5

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

Usage is implied ('get the most active switches'), but there is no explicit guidance on when to use this tool over alternatives, such as when a full list of switches is needed or when switch details are required. The schema description for siteId provides helpful context about default site and discovery via listSites, but this pertains to parameter usage rather than tool-level guidelines.

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

getDashboardOverviewA

Get the site overview topology: device counts (gateways, switches, APs), client counts (wired, wireless, guest), connectivity graph, and overall health status. Good first call to understand what's in the network.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It does not explicitly state the operation is read-only, mention authentication needs, or disclose any side effects. The parameter description in schema mentions default site fallback, but the tool description itself lacks 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.

Conciseness5/5

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

Two sentences that are front-loaded with the core purpose. Every word adds value, and there is no unnecessary repetition or filler.

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

Completeness4/5

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

Given no output schema and simple parameters, the description sufficiently conveys the return value structure. The mention of 'connectivity graph' is slightly vague but acceptable for a high-level overview tool. No critical gaps.

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

Parameters3/5

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

Schema coverage is 100% with both parameters (siteId, customHeaders) having descriptions. The tool description adds no new parameter meaning beyond what the schema provides, so baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the tool retrieves the site overview topology, listing specific components (device counts, client counts, connectivity graph, health status). It distinguishes from sibling dashboard tools by being a general overview, reinforced by 'Good first call'.

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

Usage Guidelines4/5

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

The description implies usage as an initial overview ('good first call to understand what's in the network'), providing context. However, it does not explicitly exclude scenarios or mention alternatives, though the sibling list makes differentiation possible.

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

getDashboardPoEUsageA

Get PoE (Power over Ethernet) usage statistics for a site, showing power consumption per switch.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior3/5

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

With no annotations, the description carries the burden. It indicates a read-only operation without side effects, but does not disclose authentication requirements, potential rate limits, or behavior when no PoE data exists. It is adequate but could be more explicit.

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

Conciseness5/5

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

A single sentence of 17 words that efficiently conveys the tool's purpose and output. It is front-loaded with the action and resource, leaving no wasted words.

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

Completeness4/5

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

Given the simplicity of the tool (2 parameters, no output schema), the description provides sufficient context about the data returned. It explains the granularity (per switch) but could mention aggregation or time scope. Still, it is more complete than minimal.

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

Parameters3/5

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

Schema coverage is 100% with descriptions for both parameters. The description adds the output context (per switch) but does not enhance parameter understanding beyond the schema. Baseline 3 applies as schema already documents parameters.

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

Purpose5/5

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

The description clearly states the tool retrieves PoE usage statistics for a site, specifically showing power consumption per switch. This is distinct from sibling dashboard tools like getDashboardOverview or getDashboardMostActiveSwitches, as it focuses on PoE metrics.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives, such as other dashboard tools or device-level PoE queries. The description lacks context about prerequisites or scenarios where this tool is preferred.

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

getDashboardSwitchSummaryB

Get switch summary for a site dashboard: total switch count, total ports, active ports, PoE budget used vs available, and aggregate bandwidth.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavior. It does not mention that the operation is read-only, whether authentication is required, or how errors (e.g., missing site) are handled. This leaves significant behavioral ambiguity for the agent.

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

Conciseness4/5

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

The description is a single, front-loaded sentence that efficiently conveys the tool's purpose and its key output metrics. No extraneous words, making it concise and easy to parse.

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

Completeness2/5

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

With no output schema, the description should clarify the return format and structure. It lists metrics but doesn't indicate whether they are returned as individual fields or aggregated. Missing details on error handling, pagination, or performance implications for the agent.

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

Parameters3/5

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

Both parameters (siteId, customHeaders) are fully described in the input schema with 100% coverage. The description adds no further meaning beyond the schema, so a baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool retrieves a switch summary for a site dashboard and lists specific metrics (switch count, ports, PoE budget, bandwidth). This distinguishes it from other dashboard tools like getDashboardPoEUsage, though it could more explicitly contrast with siblings.

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

Usage Guidelines3/5

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

The description implies usage for getting a site's switch summary but offers no guidance on when to choose this tool over alternatives like getDashboardMostActiveSwitches or getDashboardOverview. No exclusion criteria or preconditions mentioned.

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

getDashboardTopCpuUsageA

Get the top devices by CPU usage for a site, useful for identifying overloaded devices.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only states it retrieves top devices by CPU usage, but does not mention whether the operation is read-only, if it requires special permissions, or if there are any side effects. The safety profile is unclear, and missing details like pagination or response format reduce transparency.

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

Conciseness5/5

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

The description is a single sentence that is front-loaded with the primary action ('Get the top devices by CPU usage for a site') and adds a brief purpose. No extraneous words; every part earns its place.

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

Completeness3/5

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

The tool has 2 optional parameters and no output schema. The description provides the key functionality but does not explain the return format (e.g., is it a list, sorted, limited count?). For a simple read tool, it is mostly complete but lacks output details that could affect agent understanding.

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

Parameters3/5

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

The input schema has 100% description coverage, so the schema already explains both parameters. The tool description adds no additional meaning or context for the parameters (e.g., what constitutes 'top' or how siteId default works). Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

Purpose5/5

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

The description clearly states the verb 'get', the resource 'top devices by CPU usage', and the scope 'for a site'. It distinguishes from sibling tools like getDashboardTopMemoryUsage by focusing specifically on CPU usage, making it easy for an agent to select this tool over alternatives.

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

Usage Guidelines3/5

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

The description mentions it is 'useful for identifying overloaded devices', which implies a use case. However, it does not explicitly state when not to use this tool or provide direct comparisons to sibling tools (e.g., getDashboardTopMemoryUsage). The guidance is adequate but lacks exclusions or alternative suggestions.

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

getDashboardTopMemoryUsageA

Get the top devices by memory usage for a site, useful for identifying memory-constrained devices.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.8/5.0

Behavior3/5

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

No annotations are provided, so the description bears full burden. It states the tool retrieves top devices by memory usage, but does not disclose behavioral traits like read-only nature, sorting, limit, or response structure. It is adequate but not detailed.

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

Conciseness5/5

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

The description is a single sentence that is clear and front-loaded. It contains no redundant or wasteful information, earning its place efficiently.

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

Completeness4/5

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

Given the tool has two optional parameters, no output schema, and low complexity, the description provides sufficient context for an agent to understand the tool's purpose. It could mention output format but is not strictly necessary.

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

Parameters3/5

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

Schema coverage is 100%, so the input schema already documents both parameters (siteId, customHeaders) with descriptions. The tool description adds no additional parameter context beyond the schema, achieving the baseline of 3.

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

Purpose5/5

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

The description uses a specific verb ('Get'), a clear resource ('top devices by memory usage'), and a context ('for a site'). It also provides a use case ('identifying memory-constrained devices'), which distinguishes it from sibling tools like getDashboardTopCpuUsage.

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

Usage Guidelines3/5

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

The description implies when to use it (memory constraint identification) but does not explicitly state when not to use it or provide alternatives among siblings. The context of sibling tools helps, but the description itself lacks explicit guidance.

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

getDashboardTrafficActivitiesB

Get traffic activity time-series data for a site, showing upload and download trends over time.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations provided; description only states basic function. Lacks info on read-only nature, pagination, rate limits, or historical data range. Minimal 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.

Conciseness5/5

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

Single sentence, no unnecessary words, directly states what the tool does. Efficient and front-loaded.

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

Completeness2/5

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

Tool has no output schema and no annotations; description does not summarize return format, data range, or usage constraints. Incomplete for agents needing to understand output or limitations.

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

Parameters3/5

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

Schema covers all parameters with detailed descriptions (siteId and customHeaders). Description adds no extra meaning beyond the schema. Baseline 3 maintained.

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

Purpose5/5

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

Description clearly states the tool retrieves time-series traffic activity data for a site, with upload/download trends. Distinguishes from siblings like getDashboardOverview by specifying traffic focus.

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

Usage Guidelines3/5

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

Implies usage for traffic trends but no explicit guidance on when to use versus alternatives or when not to use. No exclusion criteria provided.

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

getDashboardWifiSummaryB

Get WiFi summary for a site dashboard: total APs, connected AP count, wireless client count, channel utilization per band (2.4GHz/5GHz), and SSID count.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.3/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It only names the return fields, omitting details such as whether the data is real-time or cached, required permissions, or any side effects. While the tool is likely read-only, the description does not explicitly state this.

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

Conciseness5/5

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

The description is a single sentence of 20 words that immediately states the tool's purpose and lists the fields. There is no redundant information, and the structure is perfectly front-loaded.

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

Completeness3/5

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

With no output schema, the description should explain the response structure. It lists the fields but does not clarify how they are organized (e.g., whether channel utilization is a nested object). The description is adequate for basic understanding but lacks detail on the output format, which is needed given the lack of an output schema.

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

Parameters3/5

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

Schema description coverage is 100% (both siteId and customHeaders have descriptions in the schema). The tool description adds no additional parameter information beyond what is already in the schema, so it does not enhance understanding beyond the structured input.

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

Purpose5/5

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

The description clearly states the tool retrieves a WiFi summary for a site dashboard and lists the exact fields returned: total APs, connected AP count, wireless client count, channel utilization per band, and SSID count. It uses a specific verb ('Get') and resource ('WiFi summary for a site dashboard'), and the listed fields distinguish it from sibling dashboard summaries like getDashboardOverview.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, context, or exclusion criteria, leaving the agent to infer appropriateness solely from the tool name and field list.

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

getDeviceC

[DEPRECATED] Use listDevices instead. Filters the site device list in-process. No dedicated per-device detail endpoint exists in the spec. Fetch detailed information for a specific Omada device.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`deviceId`	Yes
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior3/5

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

The description discloses that the tool is deprecated and that no dedicated per-device endpoint exists in the spec, which provides some behavioral context. However, with no annotations provided, it lacks details on side effects, safety, or what happens when the device is not found.

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

Conciseness4/5

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

The description is short with two sentences, no redundancy, and the deprecation warning is front-loaded. It is efficient but could be more structured by separating the deprecation from the functional description.

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

Completeness2/5

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

For a tool with 3 parameters, no output schema, and nested objects, the description is too brief. It does not explain the return value format, behavior when the device is not found, or how the 'filtering' works. More context is needed for an agent to use it correctly.

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

Parameters3/5

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

Schema description coverage is 67%, so the schema already documents two of three parameters (siteId, customHeaders). The description adds no additional meaning for the required deviceId parameter, which remains underdocumented. Score at baseline as description does not compensate.

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

Purpose2/5

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

The description is self-contradictory: it first says 'Filters the site device list in-process' implying a list, then says 'Fetch detailed information for a specific Omada device' implying a single item. The purpose is vague and confusing, especially with the deprecation note to use listDevices instead.

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

Usage Guidelines3/5

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

The deprecation warning explicitly tells the agent to use listDevices instead, which is clear guidance for when not to use this tool. However, it does not clarify when it would be appropriate to use this tool over alternatives, nor does it explain the trade-offs between this and listDevices.

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

getDeviceTagListB

Get the list of device tags defined in a site.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.2/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavior. It only states the core function without mentioning read-only nature, authorization requirements, default site behavior, or any side effects.

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

Conciseness4/5

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

The description is a single, concise sentence that is front-loaded with the purpose. It efficiently uses words but could include more detail without being verbose.

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

Completeness3/5

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

For a simple list tool with full schema coverage, the description is minimally adequate. However, it lacks context about the return format, error handling, or what constitutes a device tag, and fails to leverage the absence of output schema.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already describes both parameters. The description adds no additional meaning beyond what is in the schema, which is adequate but not enhanced.

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

Purpose5/5

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

The description clearly states the verb 'Get', the resource 'device tags', and the scope 'in a site'. It is specific and distinguishes this tool from sibling tools that deal with devices, clients, or other entities.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives, nor does it mention any prerequisites or exclusions. The sibling list is large but no differentiation is offered.

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

getDownlinkWiredDevicesA

Get wired downlink devices connected to an access point's LAN port. Returns a list of devices using the AP as a wired switch, including their MAC addresses and connection details. Useful for APs with built-in switch ports (e.g. EAP615-Wall).

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It indicates a read operation by returning a list of devices with MAC addresses and connection details, but it does not explicitly state read-only nature, permissions required, or other behavioral traits like rate limits or side effects. The description is adequate but lacks depth.

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

Conciseness5/5

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

The description is two sentences, front-loading the purpose and adding a brief example use case. Every sentence is informative and concise, with no fluff or redundancy.

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

Completeness3/5

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

The tool has 3 parameters and no output schema. The description mentions return values (MAC addresses and connection details) but does not fully specify the output structure. It also omits error conditions, prerequisites (e.g., AP must have switch ports), or how connection details are formatted. For a moderate complexity tool, it is adequate but not fully complete.

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

Parameters3/5

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

Schema description coverage is 100%, with each parameter having a clear description. The tool description does not add significant value beyond the schema; it only mentions MAC addresses and connection details, which are implied by the parameters. With full schema coverage, a baseline of 3 is appropriate.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Get wired downlink devices connected to an access point's LAN port.' It specifies the resource (wired downlink devices) and action (get), and it distinguishes well from sibling tools like getApUplinkConfig or getUplinkWiredDetail, which serve different functions.

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

Usage Guidelines4/5

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

The description provides context on when to use the tool: 'Useful for APs with built-in switch ports (e.g. EAP615-Wall).' It implies that the tool is for APs with LAN ports acting as a switch, but it does not explicitly state when not to use it or mention alternative tools, leaving some ambiguity.

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

getFirmwareInfoB

Get the latest available firmware information for a device. Returns current firmware version, latest available version, and whether an upgrade is available. Use listDevices to get deviceMac values.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`deviceMac`	Yes	MAC address of the device (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find device MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description must fully convey behavioral traits. It states the tool returns firmware information, implying read-only behavior, but does not explicitly confirm no side effects, authorization needs, or potential errors. For a tool with zero annotation coverage, this is insufficient.

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

Conciseness5/5

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

The description is two sentences with no waste: the first sentence states purpose and output, the second gives a concrete prerequisite. Every word earns its place.

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

Completeness3/5

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

The description adequately covers the tool's purpose and key parameters but lacks details on the return format (no output schema) and possible error conditions. Given the simplicity of the tool, this is minimally adequate.

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

Parameters4/5

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

Schema coverage is 100%, and the description adds value beyond the schema by explaining the purpose of deviceMac and siteId, noting how to obtain valid values (listDevices, listSites), and describing the default behavior for siteId. The customHeaders parameter is also well explained.

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

Purpose4/5

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

The description clearly states the tool retrieves the latest available firmware information for a device and lists specific return fields (current version, latest available, upgrade availability). However, it does not explicitly distinguish itself from many firmware-related sibling tools (e.g., getFirmwareUpgradePlan, listUpgradeFirmwares).

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

Usage Guidelines3/5

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

The description provides a prerequisite ('Use listDevices to get deviceMac values') but offers no guidance on when to use this tool versus alternatives like getFirmwareUpgradePlan or listUpgradeFirmwares. Usage context is only implied.

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

getFirmwareUpgradePlanC

Get the firmware upgrade plan list for devices managed by the controller.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits. It does not mention whether the tool is read-only, requires authentication, or how pagination works. The schema implies pagination, but the description does not confirm or elaborate.

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

Conciseness5/5

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

Single sentence that is front-loaded with the verb 'Get'. No extraneous words. Efficiently communicates the core purpose.

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

Completeness2/5

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

Given the lack of output schema and annotations, the description is too brief. It fails to explain the return format, pagination behavior, or what constitutes a firmware upgrade plan, leaving gaps for the agent.

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

Parameters3/5

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

Schema description coverage is 67% (page and pageSize described, customHeaders missing). The description does not add any parameter-specific meaning beyond the schema. Baseline set at 3 due to moderate coverage.

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

Purpose4/5

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

Description clearly states it retrieves a list of firmware upgrade plans for devices managed by the controller. However, it does not distinguish from sibling tools like getFirmwareInfo or listUpgradeFirmwares, which may have overlapping functionality.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool over alternatives, such as getFirmwareInfo or listUpgradeFirmwares. There is no mention of prerequisites or context for use.

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

getGatewayDetailA

Fetch full configuration and status for a specific gateway: model, firmware, CPU/memory, WAN/LAN ports, routing mode, and feature flags. Use listDevices to get the gatewayMac.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries full behavioral burden. It does not mention permissions, side effects (likely safe as a read operation), or potential performance impact. The description is straightforward but lacks depth.

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

Conciseness5/5

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

Two highly focused sentences: first lists data returned, second gives prerequisite. No filler or redundancy.

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

Completeness4/5

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

The description accounts for the tool's 3 parameters, prerequisite, and return scope (configuration and status fields). Without an output schema, it adequately informs the agent of what to expect.

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

Parameters3/5

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

Schema coverage is 100%, so the baseline is 3. The description adds minimal value beyond the schema; it reiterates the gatewayMac prerequisite already in the schema description. No parameter details beyond schema are provided.

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

Purpose5/5

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

The description clearly states the tool's purpose: 'Fetch full configuration and status for a specific gateway' and lists key data elements (model, firmware, CPU/memory, etc.). It differentiates from sibling tools (e.g., getApDetail, getSwitchDetail) by specifying it's for gateways.

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

Usage Guidelines4/5

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

The description explicitly mentions a prerequisite: 'Use listDevices to get the gatewayMac.' While it doesn't specify when not to use this tool, the sibling context provides clear distinction.

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

getGatewayLanStatusB

Get LAN port status for a specific gateway: port link state, speed, duplex, connected device, and VLAN assignment. Use listDevices to get the gatewayMac.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It describes the returned data but does not disclose side effects, authorization needs, rate limits, or whether the operation is read-only. For a gateway status tool, this is insufficient.

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

Conciseness5/5

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

Two concise sentences, front-loaded with the primary purpose and a clear prerequisite. No unnecessary words or redundancy.

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

Completeness4/5

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

The description provides a good overview of the tool's output and a prerequisite step. Without an output schema, it explains the returned attributes adequately, though it could be more explicit about the output structure (e.g., list of ports).

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

Parameters3/5

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

Schema documentation covers 100% of parameters, so the description adds minimal value beyond reiterating the prerequisite. The baseline of 3 is appropriate as the description does not highlight additional constraints or format details.

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

Purpose4/5

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

The description clearly states it retrieves LAN port status for a specific gateway and lists the specific attributes (link state, speed, duplex, connected device, VLAN). However, it does not explicitly distinguish itself from sibling tools like getGatewayPorts or getGatewayWanStatus.

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

Usage Guidelines3/5

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

It provides a prerequisite instruction (use listDevices to get gatewayMac) but lacks guidance on when to use this tool versus alternatives. No comparison to related tools is given.

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

getGatewayPortsA

Get all WAN and LAN port details for a specific gateway: link status, speed, IP address, bytes in/out, and port profile. More detailed than getGatewayWanStatus or getGatewayLanStatus. Use listDevices to get the gatewayMac.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It lists the specific data returned (link status, speed, IP, bytes, port profile) and implies it is a read operation (get). It does not disclose any side effects, authentication requirements, or rate limits, but for a straightforward read tool, this is adequate. The description does not contradict any annotations.

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

Conciseness5/5

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

The description is only two sentences long and front-loads the main purpose and output fields in the first sentence. The second sentence provides valuable sibling comparison and a usage prerequisite. Every word earns its place with zero redundancy.

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

Completeness3/5

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

No output schema exists, so the description should hint at return structure. It lists the kinds of fields returned but does not specify whether the response is an array or object, nor does it mention nested objects (context signal indicates nested objects). This is a moderate gap, but the description is still informative enough for most use cases.

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

Parameters3/5

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

The input schema has 100% description coverage for all three parameters. The description adds value by advising to use listDevices to obtain gatewayMac, which helps the agent understand the prerequisite. The schema already explains siteId and customHeaders semantics, so the description adds marginal but useful context.

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

Purpose5/5

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

The description explicitly states it retrieves all WAN and LAN port details for a specific gateway and lists the specific fields (link status, speed, IP address, bytes, port profile). It distinguishes this tool from less detailed siblings (getGatewayWanStatus, getGatewayLanStatus), making the purpose crystal clear.

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

Usage Guidelines4/5

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

The description provides clear context for when to use this tool (when detailed port info is needed) and points to less detailed alternatives. It also advises to use listDevices to get the gatewayMac. However, it does not explicitly state when not to use it (e.g., if only wan status is needed), but the comparison to siblings implicitly covers that.

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

getGatewayWanStatusA

Get the WAN port status and connectivity information for a specific gateway. Returns WAN IP, DNS, uptime, link speed, TX/RX rates, and connection type for each WAN port. Use listDevices to find the gatewayMac.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.2/5.0

Behavior4/5

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

Lists specific return values (WAN IP, DNS, uptime, etc.) indicating read-only nature. No annotations present, so description carries full burden; missing details on errors or rate limits but sufficient for typical use.

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

Conciseness5/5

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

Two sentences: first defines purpose, second provides actionable prerequisite. No redundancy, front-loaded with key info.

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

Completeness4/5

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

No output schema, but description lists key return fields. Implies multiple WAN ports but doesn't specify output format (list vs object). Adequate for the tool's simplicity.

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

Parameters3/5

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

Schema covers 100% of parameters with descriptions; description adds no new param meaning beyond schema (e.g., the prerequisite is already in gatewayMac description).

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

Purpose5/5

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

Clear verb 'Get' and resource 'WAN port status and connectivity information'. Distinguishes from siblings like getGatewayLanStatus and getGatewayDetail by specifying WAN focus.

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

Usage Guidelines4/5

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

Provides explicit prerequisite 'Use listDevices to find the gatewayMac.', but lacks when-not-to-use guidance or comparison with alternative tools.

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

getGridAutoCheckUpgradeC

Get the auto-check upgrade plan list showing scheduled firmware upgrade checks across devices. Useful for auditing upgrade schedules and identifying devices due for automatic firmware updates.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No

TDQS

C2.9/5.0

Behavior3/5

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

No annotations provided, so the description carries full burden. It describes the tool as retrieving a list, which implies a read operation, but does not disclose behavioral details such as pagination behavior (despite params for page/pageSize), response structure, or whether it is read-only. Basic transparency is present.

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

Conciseness4/5

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

The description is two sentences, concise and front-loaded with the main purpose. Every sentence adds value, though it could be slightly more efficient by combining the second sentence with the first.

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

Completeness2/5

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

Given no output schema and no annotations, the description is incomplete. It does not specify what fields the response contains, how pagination is handled, or any potential cost (e.g., rate limits). For a list tool, more detail is needed for complete contextual understanding.

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

Parameters2/5

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

Schema coverage is 67% (page and pageSize described in schema). The description does not mention any parameters or provide additional meaning beyond what the schema already offers. 'customHeaders' is undocumented in both schema and description, leaving a gap.

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

Purpose4/5

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

The description clearly states it retrieves the auto-check upgrade plan list showing scheduled firmware upgrade checks. It uses a specific verb ('Get') and resource ('auto-check upgrade plan list'). It is distinct from sibling tools like getFirmwareUpgradePlan, though not explicitly differentiated.

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

Usage Guidelines2/5

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

The description implies usage for auditing schedules but provides no explicit guidance on when to use this tool versus alternatives (e.g., getFirmwareUpgradePlan, getUpgradeLogs). No when-not or exclusion criteria are given.

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

getGridClientHistoryB

Get per-client connection history (paginated). Returns past connection sessions for a specific client including timestamps, SSID/network, traffic, and authentication type.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`clientMac`	Yes	MAC address of the client to retrieve history for.
`searchKey`	No	Search keyword to filter history entries.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations provided, so description must fully disclose behavioral traits. It describes return fields but omits permissions, rate limits, side effects, or data freshness. For a read operation, more context on authorization and data stability is needed.

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

Conciseness5/5

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

Two sentences with no fluff: first states purpose and pagination, second lists return fields. Every word serves a purpose.

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

Completeness4/5

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

Tool has 6 parameters, no output schema, and no annotations. Description covers purpose, fields returned, and pagination (implied), but could explicitly explain pagination behavior (e.g., total results, navigation). Still, it is sufficiently complete for basic usage.

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

Parameters3/5

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

Schema coverage is 100% with detailed parameter descriptions. The tool description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

Purpose5/5

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

Description uses a clear verb-resource structure ('Get per-client connection history') and specifies pagination. It distinguishes from sibling tools like 'getClient' (current info) and 'listClientsPastConnections' (likely similar but description adds detail on fields returned).

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

Usage Guidelines2/5

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

No explicit guidance on when to use this tool versus alternatives such as 'listClientsPastConnections' or 'getClientDetail'. The description lacks context for appropriate selection among similar history/activity tools.

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

getGridKnownClientsB

Get historical known clients list (paginated). Returns clients that have previously connected to the site, with optional time range and search filtering.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`guest`	No	Filter by guest status ("true" or "false").
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`timeEnd`	No	Filter end time (Unix epoch milliseconds as string).
`pageSize`	No	Number of entries per page. Range: 1-1000.
`searchKey`	No	Search keyword to filter clients by name, MAC, or IP.
`timeStart`	No	Filter start time (Unix epoch milliseconds as string).
`sortLastSeen`	No	Sort direction for lastSeen field (e.g. "asc" or "desc").
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior3/5

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

Describes pagination and filtering, but lacks details on pagination behavior, rate limits, or data range limits.

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

Conciseness5/5

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

Two sentences, no fluff, front-loaded with action verb and resource.

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

Completeness2/5

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

No output schema provided, and description does not hint at return fields or structure, leaving gap for a tool with 9 parameters.

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

Parameters3/5

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

Schema covers 100% of parameters with descriptions; description only adds context about time range and search, not enough to raise above baseline.

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

Purpose4/5

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

Clearly states it retrieves a paginated list of historical known clients with optional filters. Distinguishes from current clients tools but not from similar 'getGridClientHistory' sibling.

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

Usage Guidelines3/5

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

Implies historical data retrieval but does not explicitly state when to use over siblings or provide exclusions.

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

getIspLoadA

Get per-WAN ISP link load over a time range. Shows traffic volume and utilization per internet uplink. Useful for understanding load balancing behaviour, identifying saturated WAN links, and analysing failover events. start and end are Unix timestamps in seconds.

ParametersJSON Schema

Name	Required	Description
`end`	Yes	End of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000)). Must be paired with start.
`start`	Yes	Start of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000) - 3600 for the last hour). Must be paired with end.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.9/5.0

Behavior3/5

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

No annotations are provided, so the description carries full burden. It describes the tool as read-only ('Get') and mentions the time range, but does not explicitly state it is non-destructive, nor does it disclose authentication or rate limits. Adequate for a read tool but minimal.

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

Conciseness4/5

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

Three sentences: first states purpose, second adds detail, third lists use cases. The timestamp note is redundant with schema but not wasteful. Could be slightly more structured but is efficient overall.

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

Completeness4/5

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

Given no output schema, the description hints at return values ('traffic volume and utilization per internet uplink'). It covers purpose, usage, and output expectation. Lacks details on pagination or time range limits, but is fairly complete for a straightforward read tool.

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

Parameters3/5

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

Schema coverage is 100%, so the schema already documents all parameters. The description adds 'start and end are Unix timestamps in seconds,' which reiterates the schema. No additional meaning beyond the schema is provided.

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

Purpose5/5

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

Specific verb 'Get' and resource 'per-WAN ISP link load' clearly define the tool's purpose. The description distinguishes it from sibling tools like getGatewayWanStatus by focusing on load over a time range and mentioning traffic volume and utilization.

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

Usage Guidelines4/5

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

Explicit use cases are given ('understanding load balancing behaviour, identifying saturated WAN links, and analysing failover events'), but no explicit alternative tools or when-not-to-use guidance is provided. The context is clear but lacks exclusions.

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

getMeshStatisticsA

Get mesh link statistics for an access point. Returns wireless backhaul link quality, signal strength, throughput, and hop count for mesh-connected APs. Useful for diagnosing mesh network performance.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It clearly states this is a read operation returning specific statistics, with no mention of destructive actions. However, it does not disclose potential rate limits, authentication requirements, or performance impact, which would improve transparency.

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

Conciseness5/5

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

The description is two sentences, front-loaded with the core purpose, and wastes no words. It efficiently conveys the tool's function and use case.

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

Completeness4/5

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

Given no output schema, the description adequately lists the returned statistics (link quality, signal strength, throughput, hop count). It covers the main purpose and parameter discovery via schema comments. Minor gaps include lack of error conditions or edge cases, but overall it is complete for a read-only diagnostic tool.

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

Parameters3/5

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

Schema description coverage is 100%, and the schema includes meaningful descriptions for apMac (including a usage hint) and siteId (referring to listSites and default config). The tool description adds no additional parameter details beyond what the schema already provides, so baseline 3 is appropriate.

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

Purpose5/5

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

The description clearly states the verb ('Get'), the resource ('mesh link statistics for an access point'), and the specific output fields (backhaul link quality, signal strength, throughput, hop count). It distinguishes itself from sibling tools like getApDetail and getClient by focusing specifically on mesh statistics.

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

Usage Guidelines3/5

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

The description says 'Useful for diagnosing mesh network performance,' which implies a usage context but does not explicitly state when to use this tool versus alternatives or provide when-not conditions. The schema hints at using listDevices and listSites for parameter discovery, but no explicit usage guidance is given.

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

getOswStackLagListA

Get Link Aggregation Group (LAG) list for a switch stack. Returns configured LAG/trunk groups including member ports, load balancing mode, and status. Use getSwitchStackDetail to get the stackId.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`stackId`	Yes	Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. It correctly implies a read-only operation through the verb 'Get', and it specifies the returned data. However, it does not disclose potential side effects (none expected), authentication requirements, or rate limits. The description is adequate but not enriched beyond the basic read nature.

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

Conciseness5/5

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

The description is concise: two sentences that front-load the purpose and immediately describe the return value. No unnecessary words or repetitions. Every sentence earns its place.

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

Completeness4/5

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

Given the absence of an output schema, the description adequately describes the return value (LAG groups with member ports, mode, status). It also references a prerequisite tool. However, it could benefit from a brief contrast with sibling tools like getStackPorts to clarify when this specific tool is needed.

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

Parameters4/5

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

Schema coverage is 100% with good descriptions. The description adds value by providing context for the stackId parameter ('Use getSwitchStackDetail to get the stackId') and hints about customHeaders ('Rarely needed'). This supplements the schema's information, moving beyond the baseline of 3.

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

Purpose5/5

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

The description clearly states the tool's purpose: retrieving the LAG list for a switch stack. It specifies the resource ('Link Aggregation Group (LAG) list'), the action ('Get'), and the content of the response ('member ports, load balancing mode, and status'). This differentiates it from sibling tools like getStackPorts or getStackNetworkList.

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

Usage Guidelines3/5

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

The description provides a prerequisite hint ('Use getSwitchStackDetail to get the stackId') but does not explicitly state when to use this tool versus alternatives. There is no guidance on when not to use it or what scenarios are more suitable for other tools.

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

getPastClientNumA

Get historical client count trend over a time range. Returns a time-series of client counts to show how connected devices changed over the specified period. Requires start and end as Unix epoch seconds.

ParametersJSON Schema

Name	Required	Description
`end`	Yes	End of the time range as Unix epoch seconds.
`start`	Yes	Start of the time range as Unix epoch seconds.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.5/5.0

Behavior2/5

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

No annotations are provided, so the description must carry the full burden. It states the tool returns a time-series but does not disclose behavioral traits such as read-only nature, authentication requirements, rate limits, or potential side effects. The description is insufficient for a tool with no annotations.

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

Conciseness5/5

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

The description is two sentences long, no unnecessary words. It front-loads the purpose and then specifies the requirement. Every sentence earns its place.

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

Completeness3/5

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

Given no output schema and the tool's complexity (time-series data), the description is somewhat incomplete. It does not detail the format of the returned time-series (e.g., intervals, data points, units). However, parameters are well-documented in the schema, and the tool's purpose is clear. A 3 reflects adequate but not thorough completeness.

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

Parameters3/5

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

Schema coverage is 100%, and the description adds little beyond the schema: it reiterates that start and end are Unix epoch seconds (already in schema) and does not elaborate on siteId or customHeaders beyond what is in the schema. Baseline 3 is appropriate as the description provides minimal added value.

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

Purpose5/5

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

The description clearly states the tool gets a historical client count trend over a time range, specifying it returns a time-series of client counts. This is a specific verb and resource, and it distinguishes from sibling tools like getClient or listClientsPastConnections by focusing on the trend over a range.

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

Usage Guidelines3/5

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

The description mentions required parameters (start and end as Unix epoch seconds) but does not provide explicit guidance on when to use this tool versus alternatives. It does not list exclusions or conditions for use, leaving the agent to infer from context.

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

getRadiosConfigA

Get per-radio configuration for an access point. Returns settings for each radio (2.4GHz, 5GHz, 6GHz) including band, channel, transmit power, channel width, and enabled SSIDs. Use getApRadios for runtime radio status; this returns configuration.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.7/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It clearly describes a read operation ('Get') and details the return fields (band, channel, transmit power, channel width, enabled SSIDs). While it does not mention error conditions or authorization needs, the description is transparent enough about the tool's behavior for a straightforward get operation.

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

Conciseness5/5

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

The description is two sentences long, front-loading the main purpose in the first sentence and providing sibling differentiation in the second. No extraneous information is present; every sentence serves a clear purpose.

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

Completeness5/5

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

Given no output schema, the description adequately summarizes the return fields (per-radio settings for 2.4GHz, 5GHz, 6GHz including band, channel, etc.). It explains the tool's scope, mentions prerequisites (apMac), and distinguishes from a sibling. For a tool with 3 parameters and moderate complexity, the description is complete.

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

Parameters4/5

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

Schema description coverage is 100% (all three parameters have descriptions). The description adds contextual value by suggesting how to obtain the apMac value ('Use listDevices') and noting that siteId defaults to the configured site. This goes beyond the schema alone, justifying a score above the baseline of 3.

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

Purpose5/5

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

The description clearly states 'Get per-radio configuration for an access point' with a specific verb and resource. It lists the included settings (band, channel, etc.) and explicitly distinguishes from the sibling tool getApRadios, which returns runtime status instead of configuration.

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

Usage Guidelines5/5

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

The description provides explicit guidance: 'Use getApRadios for runtime radio status; this returns configuration.' It also hints at prerequisite tooling for the apMac parameter ('Use listDevices to find AP MACs'), helping the agent choose correctly between similar tools.

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

getRFScanResultA

[DEPRECATED] Get the last RF scan results for an access point. This endpoint is marked deprecated in the Omada OpenAPI spec. Returns detected neighbouring networks, per-channel utilization, interference levels, and RSSI data. Use triggerRfScan first to initiate a fresh scan; this returns the most recent stored results.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.3/5.0

Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses deprecation, that the endpoint returns stored results (not real-time), and lists the types of data returned. It does not discuss authentication or rate limits, but the read-only nature is implied by 'Get' and the lack of side effects mentioned.

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

Conciseness5/5

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

Three sentences, front-loading deprecation and purpose, then data content, then prerequisite. Every sentence adds value with no redundancy.

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

Completeness5/5

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

No output schema, but the description enumerates the kind of data returned (neighboring networks, per-channel utilization, interference, RSSI), which suffices. Parameter descriptions are covered by schema. The tool's role among 80+ siblings is clear from its name and description.

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

Parameters3/5

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

Schema coverage is 100%, so baseline is 3. The description adds no significant meaning beyond the schema descriptions; it mentions using listDevices to find AP MACs, which is already in the schema for apMac. No additional parameter semantics.

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

Purpose5/5

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

The description clearly states the verb (Get) and resource (last RF scan results for an access point), specifies it is deprecated, and lists the data returned (neighboring networks, per-channel utilization, interference, RSSI). It distinguishes itself from sibling tools by focusing on RF scan results, which is unique among the sibling list.

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

Usage Guidelines4/5

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

Explicitly mentions using triggerRfScan first to initiate a fresh scan, and notes this endpoint returns the most recent stored results. Also flags deprecation, which advises caution. Missing explicit when-not-to-use or alternative tool references, but the prerequisite is clear.

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

getSitesApsAvailableChannelC

Get available channels for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description must disclose behavioral traits but fails to do so. It does not state whether the operation is read-only, how performance is affected, or if any side effects occur.

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

Conciseness4/5

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

The description is a single sentence with no wasted words. While concise, it is slightly under-specified, but the structure is efficient.

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

Completeness2/5

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

The tool has three parameters and no output schema, yet the description provides no information about return values, response format, or expected behavior. Given the complexity of sibling tools, the description is incomplete.

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

Parameters3/5

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

Schema coverage is 100% with detailed descriptions for each parameter (e.g., apMac format, siteId default, customHeaders usage). The tool description adds no new meaning beyond the schema, so baseline 3 is appropriate.

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

Purpose4/5

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

The description clearly states 'Get available channels for an AP,' specifying a concrete verb and resource. However, it lacks detail on what constitutes 'available channels' and does not differentiate from closely related sibling tools like getApRadios or getSitesApsChannelLimit.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives is provided. The parameter descriptions include hints (e.g., using listDevices to find apMac), but no explicit context for selection among the many sibling tools.

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

getSitesApsBridgeC

Get P2P bridge config for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations provided. The description only says 'Get', implying read-only, but does not disclose error behavior, prerequisites, or any side effects. Minimal transparency.

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

Conciseness4/5

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

Extremely concise single sentence, front-loaded with the action. Could benefit from slightly more detail without being verbose.

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

Completeness2/5

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

No output schema, no annotations. The description fails to explain what P2P bridge config entails, what the response looks like, or any prerequisites beyond parameter hints.

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

Parameters3/5

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

Schema coverage is 100% with documented parameters. The description adds no extra parameter meaning, so baseline 3 applies.

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

Purpose4/5

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

The description clearly states 'Get P2P bridge config for an AP,' specifying a distinct config type among many sibling AP config tools. However, it does not elaborate on the scope or relation to siblings.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., getApGeneralConfig). The description lacks any usage context or exclusionary hints.

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

getSitesApsChannelLimitC

Get channel limit config for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

The description only says 'Get', implying a read operation, but provides no additional behavioral details such as authorization requirements, side effects, or rate limits. With no annotations, more context is needed.

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

Conciseness4/5

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

The description is a single clear sentence with no unnecessary words. While very short, it is appropriately concise and front-loaded with the action and subject.

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

Completeness2/5

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

Given the presence of three parameters (including customHeaders), no output schema, and many sibling tools, the description is insufficiently complete. It does not explain what the channel limit config consists of or how to interpret the response.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are already described in the schema. The description adds no extra meaning beyond what is in the schema, meeting the baseline but not exceeding it.

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

Purpose4/5

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

The description specifies a clear verb ('Get') and resource ('channel limit config for an AP'), making the basic purpose understandable. However, it does not differentiate from many similar sibling tools like getSitesApsAvailableChannel or getSitesApsLoadBalance.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives. The description does not indicate prerequisites, context, or exclusions, leaving the agent to infer usage from the name alone.

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

getSitesApsIpSettingC

Get IP settings for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits beyond the implicit read-only nature. It fails to mention any potential side effects, authorization requirements, or rate limits, leaving the agent without crucial context.

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

Conciseness4/5

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

The description is a single sentence that is front-loaded and concise. However, it could be expanded slightly to include more context without losing brevity.

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

Completeness2/5

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

Given the absence of an output schema, the description should at least hint at the structure of the returned IP settings (e.g., IP address, subnet mask, gateway). It does not, making it incomplete for the agent to understand the tool's full behavior.

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

Parameters3/5

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

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the parameter descriptions in the schema already provide, such as the format of apMac or the default behavior of siteId.

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

Purpose4/5

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

The description clearly states that the tool retrieves IP settings for an access point, using a specific verb and resource. However, it does not explicitly distinguish it from sibling tools like getApIpv6Config or getApGeneralConfig, which might overlap.

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

Usage Guidelines2/5

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

There is no guidance on when to use this tool versus alternatives. The description lacks context about prerequisites, typical use cases, or conditions under which other tools should be preferred.

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

getSitesApsLoadBalanceA

Get load balance config for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided, but description implies a read-only operation. It does not disclose potential edge cases (e.g., missing config), permissions, or side effects, but for a simple get config, it is minimally adequate.

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

Conciseness5/5

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

Single sentence, front-loaded, with zero superfluous content. Highly concise while still clear.

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

Completeness4/5

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

Given the simple read nature and 100% schema coverage, the description is nearly complete. It lacks output format details but that is compensated by clarity of purpose and schema. Slightly better than minimal.

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

Parameters3/5

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

Schema provides full parameter descriptions (100% coverage), so the tool description adds no extra meaning. Baseline of 3 is appropriate as the schema already clarifies parameters.

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

Purpose5/5

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

Description uses specific verb 'Get' and resource 'load balance config for an AP', clearly distinguishing it from sibling tools like getApGeneralConfig or getApQosConfig. It precisely states the action and target.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as getApGeneralConfig or getApRadios. The description does not mention context or exclusions, leaving the agent to infer.

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

getSitesApsOfdmaB

Get OFDMA configuration for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3/5.0

Behavior2/5

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

No annotations provided, so the description must cover behavioral traits. It only states the action without disclosing read-only nature, authentication requirements, side effects, or error conditions. The brevity leaves the agent without essential safety context.

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

Conciseness3/5

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

Single sentence is concise, but it under-specifies the tool's purpose and behavior. Could add more context without excessive length (e.g., mention OFDMA is for 802.11ax). Not concise in a helpful way.

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

Completeness2/5

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

No output schema, no description of return values or what 'OFDMA configuration' entails. Given the complexity of 3 parameters including a nested object, the description is insufficient for an agent to understand the tool's full behavior and output.

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

Parameters3/5

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

Schema description coverage is 100% with adequate param descriptions (e.g., apMac regex example, siteId fallback). The tool description adds no extra meaning beyond the schema, so baseline 3 applies.

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

Purpose5/5

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

The description 'Get OFDMA configuration for an AP' uses a specific verb and resource (OFDMA configuration for an AP), which clearly distinguishes it from sibling tools that target other AP settings like radios, VLAN, or general config.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus other AP configuration tools (e.g., getApDetail, getApRadios). The parameter descriptions hint at prerequisites (use listDevices for MAC, listSites for siteId) but no explicit when-to-use or when-not-to-use advice.

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

getSitesApsPowerSavingB

Get power saving config for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3/5.0

Behavior2/5

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

With no annotations, the description carries full burden, but it only says 'Get power saving config for an AP.' It does not state that the operation is read-only, whether errors occur for unsupported APs, or any prerequisites. The name implies a read, but formal transparency is lacking.

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

Conciseness3/5

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

The description is a single sentence, which is concise but lacks structure. It earns its place but could be expanded to include context about the return format or usage notes without becoming verbose.

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

Completeness2/5

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

Despite only 3 parameters, the description omits details about the return value (no output schema) and possible error conditions. The tool would benefit from explaining what the power saving config contains or how to interpret responses.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already documents all parameters. The tool description adds no extra meaning beyond the schema; it merely restates the action. Baseline 3 is appropriate.

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

Purpose5/5

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

The description 'Get power saving config for an AP.' uses a specific verb and resource, clearly distinguishing it from sibling tools like getApGeneralConfig or getApRadios. It directly states what the tool retrieves.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives (e.g., other AP config tools). The only implicit hint is in the input schema's apMac description referencing listDevices, but that does not address usage context or exclusions.

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

getSitesApsTrunkSettingC

Get trunk setting for an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are present, and the description only indicates a read operation ('Get') without explicitly stating it is non-destructive, required permissions, or potential side effects. The description fails to compensate for the lack of annotations.

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

Conciseness4/5

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

The description is a single concise sentence with no wasted words. It is front-loaded but lacks detail, which slightly reduces effectiveness.

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

Completeness2/5

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

With no output schema and minimal description, the tool lacks context about return values, prerequisites (e.g., does the AP need to be online?), or expected response format. A more complete description would improve agent decision-making.

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

Parameters3/5

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

Schema coverage is 100%, with each parameter described. The description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the action (get) and resource (trunk setting for an AP), distinguishing it from other get* AP tools. However, 'trunk setting' is not elaborated, which may cause ambiguity for agents unfamiliar with network terminology.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus the many sibling tools (e.g., getApDetail, getSitesApsChannelLimit). No when-not-to-use or alternative recommendations are provided.

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

getSitesDeviceWhiteListC

Get the device whitelist for a site.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations, the description should disclose behavioral traits. It fails to mention that this is a read-only operation (no destructive effect), that results are paginated, or other side effects. The minimal description leaves the agent guessing.

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

Conciseness4/5

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

The description is a single short sentence, which is efficient. However, it could be slightly more informative without sacrificing conciseness.

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

Completeness2/5

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

Given the tool has 4 parameters, pagination, and no output schema, the description is too brief. It does not explain what the whitelist represents, the return format, or behavior when siteId is omitted.

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

Parameters3/5

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

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema; it does not explain the purpose of the whitelist or how the parameters relate.

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

Purpose4/5

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

The description clearly states the verb ('Get') and the resource ('device whitelist for a site'), making it distinct from sibling tools like getAllDeviceBySite or getDevice. However, it does not specify that the result is a list or note pagination.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives like getAllDeviceBySite. The description lacks context for choosing this tool over similar getters.

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

getSitesGatewaysGeneralConfigC

Get gateway general config.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

No annotations are provided, so the description must disclose behavioral traits. It does not mention that the tool is read-only, potential side effects (none expected), or error conditions like invalid gateway MAC. This leaves the agent without critical behavioral context.

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

Conciseness4/5

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

The description is a single sentence with no wasted words. It is appropriately sized for a simple retrieval operation, though it could benefit from slightly more detail without becoming verbose.

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

Completeness2/5

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

The description lacks crucial context: no explanation of what 'general config' includes, no mention of output format (since there is no output schema), and no clarification on how this tool compares to similar ones like getGatewayDetail. This leaves significant gaps for an agent to correctly invoke the tool.

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

Parameters3/5

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

Schema coverage is 100%, so parameters are already well-documented. The description adds no additional meaning beyond what the schema provides. Baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the tool retrieves gateway general config, which is a specific verb-resource combination. However, it does not differentiate from sibling tools like getGatewayDetail or getApGeneralConfig, which also retrieve configurations.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool over alternatives, nor are there any exclusions or prerequisites mentioned. The description merely states the action without context for appropriate usage.

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

getSitesGatewaysPinC

Get PIN setting for a gateway (LTE model).

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

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

With no annotations provided, the description must fully disclose behavior. It states 'Get' which implies a safe, read-only operation, but it does not confirm that no state is modified, nor does it mention any required permissions, rate limits, or side effects. The lack of behavioral details is a significant gap.

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

Conciseness4/5

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

The description is highly concise with one clear sentence that front-loads the verb and resource. However, it omits any context or examples, which would improve usability without sacrificing conciseness.

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

Completeness2/5

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

The tool lacks an output schema, so the description should at least hint at what the PIN setting looks like (e.g., format, data type). It also does not explain what 'PIN setting' means, leaving the agent to infer. Given the tool's simplicity, more context is needed for complete understanding.

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

Parameters3/5

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

The input schema has 100% parameter description coverage, meaning the schema already explains each parameter in detail. The description adds no additional semantic value beyond the schema's descriptions. Baseline score of 3 is appropriate here.

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

Purpose4/5

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

The description clearly states the tool retrieves the PIN setting for a gateway, specifically an LTE model. It uses a specific verb ('Get') and resource ('PIN setting for a gateway'), distinguishing it from sibling tools like getGatewayDetail or getGatewayLanStatus. However, it could be more explicit about the data being read-only.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., gateway must be LTE model) or when not to use it. The single sentence lacks any contextual instructions for the agent.

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

getSitesGatewaysSimCardUsedC

Get SIM card used by a gateway.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior2/5

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

With no annotations provided, the description must convey behavioral traits. It only states the action without disclosing whether the operation is read-only, requires specific permissions, has rate limits, or any side effects. The lack of any behavioral context significantly reduces transparency.

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

Conciseness3/5

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

The description is extremely concise at one sentence, but this brevity sacrifices completeness. While there is no wasted text, the lack of additional context makes it minimally acceptable.

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

Completeness2/5

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is insufficiently complete. It does not explain return values, prerequisites (e.g., whether the gateway must be managed by the site), or how this tool fits among the many sibling getters.

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

Parameters3/5

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

The input schema has 100% coverage, already describing all three parameters including defaults and patterns. The description adds no additional meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

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

Purpose4/5

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

The description clearly states the purpose: retrieving the SIM card used by a gateway. It uses a specific verb ('Get') and resource ('SIM card used by a gateway'), which aligns well with the tool name and distinguishes it from sibling tools like getGatewayDetail that may return broader gateway information.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as getGatewayDetail or other getters. There is no mention of prerequisites, use cases, or scenarios where this tool is preferred.

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

getSitesHealthGatewaysWansDetailsC

Get WAN port health details for a gateway.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`gatewayMac`	Yes	MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior2/5

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

With no annotations, the description bears full responsibility for behavioral disclosure. It only states the high-level purpose, omitting details such as whether the gateway must be online, what 'health details' include, error handling, or performance implications. This is insufficient for a tool that likely requires specific permissions and depends on network state.

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

Conciseness3/5

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

The description is extremely concise at one sentence (8 words), but this brevity sacrifices informative content. While it contains no fluff, it does not earn its place because it omits necessary context. A rating of 3 reflects that it is neither verbose nor sufficiently detailed.

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

Completeness2/5

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

The tool has no output schema, so the description should explain what the tool returns (e.g., 'health details' could include port status, speed, errors, etc.). It also does not mention any side effects or that it is a read-only operation. For a tool with moderate complexity (nested objects), the description is incomplete.

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

Parameters3/5

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

The input schema has 100% coverage, so the schema already documents each parameter well (e.g., siteId, gatewayMac with examples, customHeaders). The description adds no additional meaning beyond what the schema provides, meeting the baseline of 3.

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

Purpose4/5

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

The description clearly states the action ('Get') and the resource ('WAN port health details for a gateway'). It is a specific verb+resource combination. However, it does not distinguish from similar sibling tools like getGatewayWanStatus, which may also return health information, 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.

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives such as getGatewayWanStatus or getGatewayPorts. The description does not mention any prerequisites or when not to use it. Usage is only implied by the tool name.

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

getSitesSwitchesEsC

Get easy managed switch info.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior2/5

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

No annotations are provided, so the description carries full burden. It implies a read operation but does not disclose any behavioral traits (e.g., authentication, rate limits, pagination, or side effects). The description is too minimal.

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

Conciseness3/5

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

The description is very short (one sentence). While concise, it lacks structure and omits important details, making it minimally adequate.

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

Completeness2/5

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

Given that there is no output schema and the tool returns complex info (nested objects), the description fails to explain what 'easy managed switch info' includes or how the response is structured. It is incomplete.

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

Parameters3/5

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

Schema coverage is 100%, with each parameter having a description. The tool description adds no new parameter semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

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

Purpose4/5

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

The description 'Get easy managed switch info' clearly identifies the resource (easy managed switch) and the action (get info). It distinguishes from siblings that target specific details (e.g., getSitesSwitchesEsGeneralConfig, getSwitchDetail), though 'info' is somewhat vague.

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

Usage Guidelines2/5

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

The description provides no guidance on when to use this tool versus alternatives. Siblings like getSitesSwitchesEsGeneralConfig or getSwitchDetail exist, but no usage context 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.

getSitesSwitchesEsGeneralConfigB

Get easy managed switch general config.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.1/5.0

Behavior2/5

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

No annotations are provided, so the description must bear all behavioral disclosure. The description only says 'Get', implying a read operation, but does not disclose authentication needs, rate limits, error behavior, or what happens on failure. This is insufficient for a tool with no annotation support.

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

Conciseness4/5

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

The description is a single short sentence, making it very concise. It is front-loaded with the key information. However, it could be slightly expanded to include more context without becoming overly long.

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

Completeness2/5

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

Given the tool has 3 parameters, no output schema, and no annotations, the description is too brief. It does not explain what 'general config' includes, how to interpret the response, or any prerequisites (e.g., switch must be online). It is incomplete for an AI agent to use confidently.

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

Parameters3/5

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

Schema description coverage is 100%, so each parameter is already documented in the schema. The description adds no additional meaning beyond the schema, such as clarifying what 'general config' includes or expected return format. Baseline score of 3 is appropriate.

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

Purpose4/5

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

The description 'Get easy managed switch general config' clearly states the verb (Get) and the resource (easy managed switch general config). It is specific to easy managed switches, but does not explicitly differentiate from sibling tool 'getSwitchGeneralConfig' which likely targets regular switches.

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

Usage Guidelines3/5

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

No explicit usage guidelines are provided. The tool is implied for easy managed switches based on naming, but there is no when-not or alternative guidance. Sibling tools exist for APs, gateways, and regular switches, but no contextual advice is given.

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

getSpeedTestResultsA

Get the last speed test results for an access point. Returns upload/download throughput measurements from the most recent speed test. Use triggerSpeedTest first to initiate a new test; this returns stored results.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.6/5.0

Behavior4/5

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

No annotations provided, so description bears full burden. It discloses the tool is a read-only operation returning stored results, which is key. However, it lacks details on error handling (e.g., if no prior test exists) or permissions.

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

Conciseness5/5

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

Two concise sentences with no fluff. Purpose is front-loaded, and critical usage guidance follows immediately.

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

Completeness4/5

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

Provides sufficient context for a simple read tool: what it returns, prerequisites (triggerSpeedTest), and param guidance. Lacks output format details but given no output schema, description could be slightly more complete.

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

Parameters4/5

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

Schema covers all parameters (100%), but description adds value by explaining the apMac format and suggesting listDevices, and clarifying siteId default behavior and cross-reference to listSites. This helps agent use parameters correctly.

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

Purpose5/5

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

The description clearly states the tool retrieves 'the last speed test results for an access point' with specific metrics (upload/download throughput). It differentiates from sibling tools like getApDetail by focusing on speed test results.

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

Usage Guidelines5/5

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

Explicitly instructs to use triggerSpeedTest first to initiate a new test, clarifying that this tool returns stored results. Gives clear when-to-use and a direct alternative.

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

getStackNetworkListA

Get the VLAN network list for a switch stack. Returns VLAN interface assignments across all stack members. Use getSwitchStackDetail to get the stackId.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`stackId`	Yes	Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.5/5.0

Behavior2/5

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

With no annotations, the description bears full responsibility. It indicates a read operation but lacks details on pagination, rate limits, authentication needs, or any side effects. The description does not go beyond the minimal verb+object.

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

Conciseness5/5

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

Two well-organized sentences with a clear action, output description, and a prerequisite tip. No redundant or extraneous information.

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

Completeness3/5

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

For a tool with 5 parameters and no output schema, the description only vaguely explains the return value ('VLAN interface assignments'). It lacks details on format, structure, or any example. While the schema covers parameter domains, the description should provide more context on the output to be minimally complete.

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

Parameters3/5

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

The input schema covers 100% of parameters with descriptive texts and constraints (e.g., page, pageSize, stackId). The description adds no additional parameter semantics beyond what the schema already provides, meeting the baseline for high schema coverage.

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

Purpose5/5

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

The description clearly states the action: 'Get the VLAN network list for a switch stack' and specifies the output: 'Returns VLAN interface assignments across all stack members.' This distinguishes it from sibling tools like getStackPorts or getSwitchStackDetail.

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

Usage Guidelines3/5

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

The description provides a prerequisite instruction: 'Use getSwitchStackDetail to get the stackId,' but does not explicitly state when to use this tool versus alternatives or any exclusion criteria. The guideline is helpful but limited.

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

getStackPortsC

Get all port information for a switch stack.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`stackId`	Yes
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior1/5

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

No annotations provided, and the description offers no behavioral details (e.g., read-only, rate limits, required permissions). It merely restates the tool name's purpose.

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

Conciseness4/5

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

The description is a single sentence that front-loads the core purpose. It is concise but could benefit from a brief note on typical usage without becoming verbose.

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

Completeness2/5

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

With no output schema and no annotations, the description fails to indicate return format, pagination, or limitations. Users are left uncertain about the data structure.

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

Parameters2/5

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

Schema coverage is 67%, but the description adds no parameter-level information. The required parameter stackId lacks description in both schema and description, and siteId's description is only in schema.

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

Purpose5/5

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

The description clearly states the verb 'Get' and the resource 'all port information for a switch stack.' It distinguishes from siblings like getGatewayPorts and getSwitchStackDetail by specifying port information for a stack.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., getSwitchDetail for individual switch ports or listSitesStacks for stack listing). No context about prerequisites or exclusions.

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

getSwitchDetailA

Fetch full configuration and status for a specific switch: model, firmware, CPU/memory, all port states, PoE usage, VLAN config, and STP status. Use listDevices to get the switchMac.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.2/5.0

Behavior3/5

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

No annotations are provided, so the description carries the full burden. The tool reads data without modification, but the description does not explicitly state it is read-only nor mention any behavioral quirks like rate limits or permissions. The 'Fetch' verb implies safety, but transparency could be improved.

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

Conciseness5/5

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

Two concise sentences. The first covers purpose and scope, the second provides a critical prerequisite. No redundant information, every word earns its place.

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

Completeness4/5

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

Given the complexity of the tool (detailed switch data) and the absence of an output schema, the description lists the fields returned (model, firmware, CPU/memory, port states, etc.), which is highly informative. It also notes the prerequisite and optional siteId. This is sufficient for an agent to understand the tool's output.

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

Parameters4/5

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

Schema coverage is 100%, so parameters are well-documented in the schema. The description adds value by linking switchMac to listDevices and siteId to listSites with a default behavior note. This context aids correct parameter usage beyond the schema.

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

Purpose5/5

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

The description uses a specific verb ('Fetch') and clearly enumerates the resources retrieved (model, firmware, CPU/memory, port states, PoE usage, VLAN config, STP status). It distinguishes from sibling tools like getSwitchGeneralConfig and getApDetail by stating it retrieves full configuration and status.

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

Usage Guidelines4/5

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

The description explicitly instructs to use listDevices to obtain the switchMac parameter, providing a clear prerequisite. While it doesn't contrast with alternative switch detail tools, the guidance is sufficient for correct invocation.

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

getSwitchDot1xSettingA

Get the 802.1X switch port authentication setting. Controls port-based network access control on managed switches.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.6/5.0

Behavior3/5

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

No annotations provided; description indicates a read operation but does not disclose any behavioral details beyond that. Adequate for a simple getter.

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

Conciseness5/5

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

Two concise sentences with no unnecessary content. Front-loaded with the core purpose.

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

Completeness4/5

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

While the tool is simple and parameters are fully documented, the description could briefly mention the return value (e.g., the authentication setting details) for completeness.

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

Parameters3/5

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

Schema description coverage is 100%, so parameters are well-documented. Description adds no extra meaning beyond what the schema provides.

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

Purpose5/5

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

The description clearly states the verb 'Get' and the specific resource '802.1X switch port authentication setting', distinguishing it from sibling getters like getSwitchGeneralConfig.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives (e.g., general config getters). No mention of prerequisites or context for using the setting.

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

getSwitchGeneralConfigB

Get general configuration for a switch including device name, LED settings, LLDP settings, flow control, and other global switch parameters. Use listDevices to get switchMac values.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, and the description does not disclose behavioral traits such as whether the tool is read-only, requires authentication, or has side effects. For a read operation, it is safe, but the description fails to explicitly state this.

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

Conciseness5/5

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

Two sentences: the first clearly states the tool's purpose, the second provides a critical usage hint. No unnecessary words, front-loaded with essential information.

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

Completeness3/5

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

Given the tool's simplicity and full schema coverage, the description is adequate but lacks details about the return format (e.g., it returns a configuration object). For a tool with no output schema and no annotations, a bit more context would be helpful.

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

Parameters4/5

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

Schema coverage is 100%, and the description adds value by advising to use listDevices to obtain switchMac values. This helps agents understand how to populate the required parameter beyond the schema's pattern constraint.

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

Purpose4/5

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

The description clearly states it retrieves general configuration for a switch, listing specific categories like LED settings, LLDP, flow control. This differentiates from sibling tools like getApGeneralConfig (for APs) and getSwitchDetail (which likely returns more detailed info), though not explicitly.

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

Usage Guidelines3/5

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

Provides one usage hint: 'Use listDevices to get switchMac values.' This helps with the required parameter, but there is no guidance on when to use this tool vs alternatives like getSitesSwitchesEsGeneralConfig, or prerequisites like siteId (though optional).

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

getSwitchStackDetailC

Fetch detailed information for a specific switch stack.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`stackId`	Yes
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior2/5

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

No annotations are provided, placing full burden on the description. It only states the tool fetches information but fails to disclose idempotency, required permissions, error scenarios, or return format (e.g., single object vs. array). Essential behavioral traits are missing.

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

Conciseness5/5

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

The description is extremely concise—a single sentence that directly states the tool's purpose. It is well front-loaded and contains no extraneous information. Every word is earned.

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

Completeness2/5

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

Given the absence of an output schema, the description does not explain what 'detailed information' entails (e.g., JSON structure, fields). The tool involves a nested object parameter (customHeaders), but no behavioral context is provided. The description is incomplete for a tool of this complexity.

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

Parameters2/5

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

With 67% schema coverage (siteId and customHeaders described), the description adds no parameter context. It omits explaining the required stackId (e.g., its origin from listSitesStacks) and does not clarify the role of optional parameters beyond the schema. No value added over the input schema.

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

Purpose4/5

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

The description uses a specific verb ('Fetch') and resource ('detailed information for a specific switch stack'), clearly distinguishing it from sibling tools like getSwitchDetail (for switches) and listSitesStacks (lists all stacks). However, 'detailed information' is somewhat vague; mentioning specific attributes like configuration or status would improve clarity.

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

Usage Guidelines2/5

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

No guidance on when to use this tool versus alternatives such as getStackNetworkList or getStackPorts. The description does not mention prerequisites, siteId handling, or the appropriate context for invocation.

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

getTrafficDistributionB

Get traffic distribution by protocol and application type over a time range. Shows breakdown of traffic by category (video, gaming, web, etc.) helping identify what is consuming bandwidth on the network. start and end are Unix timestamps in seconds.

ParametersJSON Schema

Name	Required	Description
`end`	Yes	End of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000)). Must be paired with start.
`start`	Yes	Start of the time range as a Unix timestamp in seconds (e.g. Math.floor(Date.now() / 1000) - 3600 for the last hour). Must be paired with end.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.4/5.0

Behavior2/5

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

No annotations are provided, so the description carries the full burden. It only restates the timestamp format already in the schema and does not disclose any behavioral traits (e.g., rate limits, auth requirements, or side effects).

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

Conciseness4/5

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

The description is concise at three sentences with minimal redundancy. The mention of Unix timestamps is partially redundant with the schema but not overly wasteful.

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

Completeness3/5

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

Given no output schema, the description adequately hints at return format (breakdown by category) but lacks details on pagination, error handling, or additional context like siteId behavior beyond the schema.

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

Parameters3/5

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

Schema coverage is 100% with each parameter described. The description adds no new semantic meaning beyond what is in the schema, meeting the baseline of 3.

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

Purpose5/5

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

The description clearly states the tool retrieves traffic distribution by protocol and application type over a time range, with specific categories like video and gaming. It distinguishes from siblings such as getClientsDistribution.

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

Usage Guidelines3/5

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

The description implies usage for bandwidth consumption analysis but provides no explicit guidance on when to use this tool versus alternatives like getClientsDistribution, nor when not to use it.

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

getUpgradeLogsB

Get firmware upgrade logs showing the history of upgrade operations performed on devices.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No

TDQS

B3.3/5.0

Behavior2/5

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

No annotations provided, and the description does not disclose behavioral traits such as read-only nature, scope (all devices vs. specific), or pagination behavior beyond schema defaults.

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

Conciseness5/5

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

Single sentence, 14 words, front-loaded verb, no redundant information. Every word earns its place.

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

Completeness3/5

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

Covers basic purpose but misses scope (all devices or filtered?), output format, and prerequisites. Adequate for a simple tool but insufficient given missing annotations and sibling context.

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

Parameters3/5

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

Schema description coverage is 67% (page and pageSize documented, customHeaders undocumented). The description adds no additional meaning for any parameter, so it meets baseline but does not compensate for the undocumented customHeaders.

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

Purpose5/5

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

The description explicitly states it retrieves firmware upgrade logs, which is a specific verb and resource. It distinguishes from upgrade-related siblings like getFirmwareInfo or getFirmwareUpgradePlan by focusing on logs of past operations.

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

Usage Guidelines2/5

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

No guidance on when to use this tool vs alternatives. With many upgrade-related siblings, the description lacks context on prerequisites or scenarios.

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

getUpgradeOverviewCriticalB

Get the number of critical firmware upgrades available across managed devices.

ParametersJSON Schema

Name	Required	Description	Default
`customHeaders`	No

TDQS

B3/5.0

Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic function, without any mention of side effects, permissions, rate limits, or return behavior. The agent has no information about the safety or side effects of this call.

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

Conciseness4/5

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

The description is a single sentence of 9 words, concise and front-loaded. However, it is so brief that it sacrifices necessary detail; still, it avoids unnecessary words.

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

Completeness2/5

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

The tool has one undocumented parameter and no output schema. The description does not hint at the return format (e.g., whether it returns a number, object, or list). Given the complexity of the sibling tools and the lack of schema coverage, the description is insufficient for complete understanding.

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

Parameters1/5

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

The input schema has one parameter (customHeaders) with no description in the schema (0% coverage) and the tool description does not explain its purpose, format, or usage. The description adds zero value beyond the schema for parameter understanding.

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

Purpose5/5

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

The description clearly states the verb 'Get', the resource 'the number of critical firmware upgrades', and the scope 'across managed devices'. It is specific and distinguishes from sibling tools like getFirmwareUpgradePlan which provides more detailed plans.

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

Usage Guidelines3/5

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for obtaining a count of critical upgrades, but does not specify when to prefer it over getFirmwareUpgradePlan or getUpgradeOverviewTryBeta.

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

getUpgradeOverviewTryBetaC

Get the try-beta firmware switch status for the controller.

ParametersJSON Schema

Name	Required	Description	Default
`customHeaders`	No

TDQS

C2.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the full burden. It states 'Get' implying a read-only operation, but does not disclose whether there are side effects, permissions required, or any nuances about the 'try-beta' status. The minimal description leaves significant behavioral uncertainty.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence (10 words) and is front-loaded. However, it is under-specified, so conciseness comes at the cost of completeness. Avoids verbosity but lacks necessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, no annotations, and only a vague description, the tool is incomplete. An agent cannot infer the return format or how 'try-beta switch status' relates to firmware upgrades. The presence of similar sibling tools increases the need for more context, which is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, customHeaders, is not mentioned in the description. Schema description coverage is 0%, and the description adds no meaning beyond the schema definition. This fails to help the agent understand how to use or why to set parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'Get' and the resource 'try-beta firmware switch status for the controller,' distinguishing it from sibling tools like getUpgradeOverviewCritical. However, the term 'switch status' is vague and does not clarify whether it returns a boolean, state string, or configuration.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as getFirmwareInfo, getUpgradeLogs, or getUpgradeOverviewCritical. The description lacks any context for when to invoke this specific tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getUplinkWiredDetailA

Get wired uplink detail for an access point. Returns the AP's Ethernet uplink port information including connected switch, port number, link speed, and PoE status. Useful for mapping physical network topology.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool returns data, implying a read operation. However, it does not disclose any potential side effects, authorization requirements, or rate limits. The description is adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the action and resource, followed by return fields. Every sentence provides essential information with no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description adequately explains the return data (switch, port, speed, PoE). For a simple query tool, this is sufficient to understand what the tool provides. The sibling context is large but the description helps differentiate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All three parameters (apMac, siteId, customHeaders) are fully described in the input schema. The description adds no additional parameter-level information beyond the schema, so a baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves 'wired uplink detail for an access point' and lists specific return fields (switch, port, speed, PoE). This distinguishes it from sibling tools like getApUplinkConfig (likely wireless) and getDownlinkWiredDevices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes 'Useful for mapping physical network topology' as a hint, but does not explicitly state when to use this tool versus alternatives or provide exclusions. With many sibling tools, more guidance would be beneficial.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listClientsA

List all network clients (wired and wireless) connected to a site. Returns client details including MAC address, IP, hostname, connected device, SSID (for wireless), signal strength, download/upload traffic, and online status. Use this to audit connected devices or find a specific client by name or MAC.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must convey behavioral traits. It indicates it returns a list of client details, but does not disclose potential pagination, rate limits, or performance characteristics. Additional context about response size limits would improve transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences deliver the purpose and return details efficiently with no redundancy. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 optional params, no output schema), the description covers purpose, input semantics, and output fields. It does not explain pagination or default behavior for large lists, but is adequate for a listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that siteId is optional and defaults to OMADA_SITE_ID, and that customHeaders are rarely needed. This clarifies usage beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool lists all network clients (wired and wireless) connected to a site, and specifies the returned details (MAC, IP, hostname, etc.). It distinguishes itself from sibling tools like getClient (specific client) and listClientsActivity (activity log).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description suggests use cases: 'audit connected devices or find a specific client by name or MAC.' It does not explicitly mention when not to use, but the context is clear. However, it could mention alternative tools like getClient for a single client detail.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listClientsActivityA

Get client activity statistics over time from the dashboard. Returns time-series data showing new, active, and disconnected clients (both wireless/EAP and wired/switch) for each time snapshot. Useful for monitoring client connection trends and activity patterns.

ParametersJSON Schema

Name	Required	Description
`end`	No	Optional end timestamp in seconds (e.g., 1682000000)
`start`	No	Optional start timestamp in seconds (e.g., 1682000000)
`siteId`	No	Optional site ID. If not provided, uses the default site from configuration.
`customHeaders`	No

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses the type of data (time-series) and client categories, but does not mention behavioral traits like data aggregation intervals, real-time vs historical, or authentication requirements. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences efficiently convey purpose and return type, with no redundant information. The first sentence is action-oriented, and the second adds context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description is brief for a time-series tool. It lacks details on the response structure, pagination, or how snapshots are timestamped. While it covers essential data points, more completeness would aid agent usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema provides descriptions for 3 of 4 parameters (75% coverage). The description mentions 'over time' correlating with start/end but adds no further meaning. customHeaders parameter is undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves client activity statistics as time-series data, specifying new, active, and disconnected clients for both wireless and wired types. This differentiates it from sibling tools like listClients or getClientDetail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description notes it is 'useful for monitoring client connection trends and activity patterns', implicitly guiding when to use. However, it does not explicitly state when not to use or mention alternatives among the many sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listClientsPastConnectionsA

Get client past connection list with historical connection data. Returns information about clients that have previously connected to the network, including connection timestamps, traffic data, duration, and device details. Supports pagination, filtering by time range and guest status, sorting by last seen time, and fuzzy search by name/MAC/SSID.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`guest`	No	Filter by guest status (true/false).
`siteId`	No	Optional site ID. If not provided, uses the default site from configuration.
`timeEnd`	No	Filter by time range end timestamp (milliseconds).
`pageSize`	No	Number of entries per page. Range: 1-1000.
`searchKey`	No	Fuzzy search by name, MAC address, or SSID.
`timeStart`	No	Filter by time range start timestamp (milliseconds).
`sortLastSeen`	No	Sort by last seen time. Values: asc or desc. When multiple sorts exist, first one takes effect.
`customHeaders`	No

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a read-only operation returning historical data, but lacks details on permissions, rate limits, or side effects. With no annotations, the description carries the burden and is moderately transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first clarifies purpose, second lists features. Every word adds value, and the structure is efficient and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers key features and parameters, but lacks details about the return format or pagination behavior. Given no output schema, this is a noticeable gap for a tool with 9 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high (89%), so the schema already documents most parameters. The description groups features (pagination, filtering, sorting) adding some value, but does not provide deep parameter semantics beyond what the schema offers.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool gets historical connection data for clients, using specific verbs and resources. It distinguishes itself from sibling tools like listClients (current clients) and getClientDetail (single client) by focusing on past connections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for historical data retrieval but does not explicitly compare with alternatives or state when not to use it. An agent would infer usage from context, but explicit guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listDevicesA

List all provisioned (adopted) network devices in a site: gateways, switches, and access points. Returns MAC address, model, firmware version, IP, uptime, CPU/memory usage, and status for each device. Use MAC addresses from this response as input to getGatewayDetail, getSwitchDetail, getApDetail, etc.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes a list operation (likely read-only) but does not explicitly state it is non-destructive, safe, or what side effects might exist. The verb 'list' and the nature of returning device details imply idempotency, but more direct disclosure would improve this score.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with action and scope, no extraneous words. Each sentence adds value: first defines purpose and output, second provides usage guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description lists key return fields (MAC, model, firmware version, etc.), which is mostly complete for a list tool. Lacks mention of pagination or sorting, but context signals do not indicate these are needed. The tool's complexity is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so parameters siteId and customHeaders are already documented in schema. Description adds that siteId is optional and defaults to OMADA_SITE_ID, but this is also implied by schema's description. No additional semantic value beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description specifies the tool lists provisioned network devices in a site, naming device types (gateways, switches, access points) and return fields (MAC, model, firmware, etc.). Distinguishes from siblings like searchDevices and getAllDeviceBySite by focusing on adopted devices with detailed fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states to use MAC addresses from this response as input to detail tools (getGatewayDetail, etc.), providing a clear downstream usage context. However, it does not mention when not to use this tool or alternatives such as searchDevices for filtered queries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listDevicesStatsA

Query statistics for global adopted devices with pagination and filtering. Supports fuzzy search by MAC address, name, model, or serial number, and filtering by tag or device series type (0: basic, 1: pro).

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`filterTag`	No
`searchSns`	No
`searchMacs`	No
`searchNames`	No
`searchModels`	No
`customHeaders`	No
`filterDeviceSeriesType`	No

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description lacks disclosure of side effects, permissions, or return format. Only mentions fuzzy search and filtering, missing key behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose and pagination, then filtering details. No redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description should explain what 'statistics' means (e.g., counts, aggregations). Missing response semantics and does not cover all parameters like customHeaders.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Adds meaningful context for most parameters (fuzzy search fields, filtering by tag and series type), compensating for low schema coverage. However, customHeaders is unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it queries statistics for global adopted devices with pagination and filtering, distinguishing it from sibling tools like listDevices and searchDevices.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for aggregated statistics rather than detailed device info, but no explicit when/when-not guidance relative to similar siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listMostActiveClientsA

Get the most active clients in a site, sorted by total traffic. Returns client name, MAC address, type, model, wireless status, and total traffic. This is a dashboard endpoint that provides a quick overview of top clients by traffic usage.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries the full burden. It discloses the sorted nature and return fields, but does not mention potential limits on number of clients, pagination, or authentication requirements. The read-only nature is implied but not explicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences that are concise and front-loaded with the primary action. Every sentence adds value without redundancy or unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description covers return fields and the overall purpose. However, it lacks details on result limits or sorting order, which would be helpful for a complete understanding. The context is adequate for a simple dashboard endpoint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with detailed descriptions for both parameters. The description does not add significant new meaning beyond the schema, such as clarifying the role of siteId in determining the default site.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool gets the most active clients in a site, sorted by total traffic. Specifies return fields and distinguishes from sibling tools like getClient or listClients by focusing on top traffic clients as a dashboard overview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Describes the tool as a dashboard endpoint for a quick overview, implying it's for summary rather than detailed client info. However, it does not explicitly exclude use cases or suggest alternatives like getClientDetail for more detailed client data.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listPendingDevicesA

List devices discovered on the network but not yet adopted into this site. Returns device type, MAC, IP, and model. These are devices waiting to be provisioned.

ParametersJSON Schema

Name	Required	Description	Default
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states the tool returns specific fields and implies read-only behavior by listing devices, but does not mention side effects, error handling, or permissions. Adequate but with gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with the key purpose, no unnecessary words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema or annotations, the description covers purpose, return fields, and context. It could mention pagination or error cases, but for a simple list tool it is mostly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already describes both parameters. The description adds no new information about parameters beyond what the schema provides; it merely implies siteId's role. Baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the tool lists devices discovered but not adopted, distinguishing it from siblings like listDevices which likely list adopted devices. It also mentions the returned fields (device type, MAC, IP, model).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: to find devices waiting to be provisioned. However, it does not explicitly state when not to use it or mention alternatives, but the scope is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listSitesApsPortsC

List ports on an AP.

ParametersJSON Schema

Name	Required	Description
`apMac`	Yes	MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full behavioral burden but only states 'List ports on an AP.' It does not disclose whether the operation is read-only, what permissions are needed, or any side effects. This is insufficient for an agent to understand the tool's impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the core purpose. It efficiently conveys the tool's function without extraneous text, though it omits details that could aid selection.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having three parameters and no output schema, the description lacks details about the returned data (e.g., port status, speed) and does not help an agent decide whether this tool is appropriate compared to many sibling tools. The minimal description leaves gaps for effective decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all three parameters adequately. The description adds no further semantic nuance beyond what is in the schema, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and the resource 'ports on an AP', making the tool's function obvious. It differentiates from sibling tools like getGatewayPorts and getStackPorts by specifically targeting AP ports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like listSitesCableTestSwitchesPorts or getApDetail. There are no prerequisites or usage scenarios mentioned beyond the parameter hints in the schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listSitesCableTestSwitchesIncrementResultsC

Get cable test incremental results for a switch.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

C2.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It only says 'get incremental results' without detailing behavior such as whether results are cumulative, paginated, or what data is returned. No side effects or safety info is disclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single brief sentence, which is concise but lacks structure. It could be expanded to cover key points without becoming overly long. Not wasteful but underinformative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of an output schema and the presence of sibling tools, more context is needed. The description does not explain what 'incremental results' means, how to interpret them, or how they relate to other cable test tools. Incomplete for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema itself documents all parameters well. The tool description adds no additional meaning beyond the schema. Meets baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'cable test incremental results for a switch'. It differentiates from siblings like 'getCableTestFullResults' and 'getCableTestLogs' by specifying 'incremental', but could be more explicit about scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not mention when to use this tool over alternatives (e.g., full results or logs), nor any prerequisites or context. This leaves the agent without guidance on selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listSitesCableTestSwitchesPortsB

List ports available for cable test on a switch.

ParametersJSON Schema

Name	Required	Description
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is minimal and does not disclose behavioral traits like authentication requirements, rate limits, or side effects. It only states the basic purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loads the action and context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Missing details about output format, pagination, error handling, and relationship to other cable test tools. The description is too minimal for a tool with no output schema and no annotations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the description adds no extra meaning beyond what's in the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list', the resource 'ports', and the context 'for cable test on a switch'. It distinguishes from siblings like getCableTestFullResults which retrieve results, not ports.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives such as listSitesCableTestSwitchesIncrementResults or getCableTestLogs. No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listSitesStacksB

List switch stacks in a site.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description is minimal and does not disclose behavioral traits such as read-only nature, authentication needs, or pagination behavior. The agent must infer safety from the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single-sentence description is concise with no waste. However, it could be more structured (e.g., front-loading key constraints) but remains efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and 4 parameters (with pagination), the description is too minimalist. It does not explain the return format, what a 'stack' is, or how pagination works beyond schema hints.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% with detailed parameter descriptions. The description adds no additional meaning beyond the schema, so baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (list) and resource (switch stacks in a site). It distinguishes from sibling tools like getSwitchStackDetail which gets details of a single stack.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives (e.g., getSwitchStackDetail, getStackNetworkList). No context on prerequisites or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listSwitchNetworksA

List VLAN network assignments for a switch. Returns which VLANs are assigned to which ports, including tagged and untagged configurations. Use listDevices to get switchMac values.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`siteId`	No	Site ID to target. If omitted, uses the default site from OMADA_SITE_ID config. Use listSites to discover available site IDs.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`switchMac`	Yes	MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs.
`customHeaders`	No	Optional HTTP headers to include in the Omada API request (e.g. {"X-Custom-Header": "value"}). Rarely needed.

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It describes the output in general terms but does not disclose potential side effects, error cases, pagination behavior (though page/pageSize are in schema), or any guarantees about data freshness. This is adequate but not detailed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with zero wasted words. The first sentence states purpose and output, the second provides essential prerequisite guidance. Front-loaded, efficient, and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, so the description should explain the return value structure. It only says 'Returns which VLANs are assigned to which ports', which is vague. Combined with 5 parameters and no further details on output format, completeness is moderate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter described. The description adds a cross-reference for switchMac ('Use listDevices to get switchMac values') but does not add significant new meaning beyond the schema. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a specific verb ('List') and a clear resource ('VLAN network assignments for a switch'), and specifies the output ('which VLANs are assigned to which ports, including tagged and untagged configurations'). This clearly distinguishes it from siblings like listDevices or getSwitchDetail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit guidance on a prerequisite ('Use listDevices to get switchMac values') and implies the tool is for network assignments. However, it does not list alternatives or state when not to use this tool (e.g., to list all network assignments across switches), which would strengthen the score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listUpgradeFirmwaresC

List uploaded firmware files available for manual upgrade.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No

TDQS

C2.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must disclose behavior. It only says 'list', implying a safe read, but omits details about pagination limits, authentication needs, or any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (one sentence) but minimally informative. It could be slightly expanded to include key details without being verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with no output schema, the description is basic. It lacks context about return format, filtering, or ordering. Still, it covers the core purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 67%, but the description adds no extra meaning to the parameters (page, pageSize, customHeaders). The customHeaders object lacks explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and the resource 'uploaded firmware files', indicating a read operation. It implicitly distinguishes from siblings like getFirmwareInfo or getFirmwareUpgradePlan by focusing on the list of available files.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites, filters, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listUpgradeOverviewFirmwaresC

List firmware pool entries in the upgrade overview.

ParametersJSON Schema

Name	Required	Description
`page`	No	Start page number. Start from 1.
`pageSize`	No	Number of entries per page. Range: 1-1000.
`customHeaders`	No

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description does not disclose whether the tool is read-only, destructive, or has any side effects. While 'list' implies reading, the agent has no explicit confirmation. No information about authorization, rate limits, or other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but lacks structure. It does not front-load key behavioral information or provide any sectioning. It is efficient but not particularly helpful.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the absence of output schema and annotations, the description is insufficient. It does not clarify what 'firmware pool entries' are, nor how this tool differs from other firmware-related sibling tools. The complexity is moderate, but the description leaves many gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no information beyond the input schema. Two of three parameters (page, pageSize) have schema descriptions already, but customHeaders is undocumented. The tool description does not explain the meaning of 'firmware pool entries' or how parameters affect results.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the verb 'list' and the resource 'firmware pool entries in the upgrade overview', making it clear what the tool does. However, it does not differentiate from the sibling tool 'listUpgradeFirmwares', which could cause confusion. The specificity is good but could be improved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus its siblings (e.g., 'listUpgradeFirmwares' or 'getFirmwareInfo'). There is no mention of preferred contexts or prerequisites. The description is purely declarative.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

searchDevicesC

Search for devices globally across all sites the user has access to. Returns devices matching the search key.

ParametersJSON Schema

Name	Required	Description	Default
`searchKey`	Yes
`customHeaders`	No

TDQS

C2.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose all behavioral traits. It only states the tool searches and returns matching devices, omitting details like search algorithm, case sensitivity, pagination, result limits, or side effects. This is insufficient for a global search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and front-loaded, using two efficient sentences. However, the brevity sacrifices critical details needed for proper tool invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (2 parameters, nested objects, no annotations, no output schema), the description lacks completeness. It does not cover output format, error handling, or usage constraints, making it insufficient for an AI agent to use reliably.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must clarify parameter meanings. It only mentions 'search key' without specifying what constitutes a valid key (e.g., name, MAC, partial match). The 'customHeaders' parameter is completely unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches for devices globally across all sites, which is a distinct purpose. However, it does not explicitly contrast with sibling tools like listDevices, which could also list devices across sites.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as listDevices or getDevice. No when-not-to or context scenarios are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

84 tool updatesv0.15.0Jul 5, 2026
- First observedgetAllDeviceBySite
- First observedgetApDetail
- First observedgetApGeneralConfig
- First observedgetApIpv6Config
- First observedgetApLldpConfig
- First observedgetApQosConfig
- First observedgetApRadios
- First observedgetApSnmpConfig
- First observedgetApUplinkConfig
- First observedgetApVlanConfig
- First observedgetCableTestFullResults
- First observedgetCableTestLogs
- First observedgetClient
- First observedgetClientDetail
- First observedgetClientsDistribution
- First observedgetDashboardMostActiveEaps
- First observedgetDashboardMostActiveSwitches
- First observedgetDashboardOverview
- First observedgetDashboardPoEUsage
- First observedgetDashboardSwitchSummary
- First observedgetDashboardTopCpuUsage
- First observedgetDashboardTopMemoryUsage
- First observedgetDashboardTrafficActivities
- First observedgetDashboardWifiSummary
- First observedgetDevice
- First observedgetDeviceTagList
- First observedgetDownlinkWiredDevices
- First observedgetFirmwareInfo
- First observedgetFirmwareUpgradePlan
- First observedgetGatewayDetail
- First observedgetGatewayLanStatus
- First observedgetGatewayPorts
- First observedgetGatewayWanStatus
- First observedgetGridAutoCheckUpgrade
- First observedgetGridClientHistory
- First observedgetGridKnownClients
- First observedgetIspLoad
- First observedgetMeshStatistics
- First observedgetOswStackLagList
- First observedgetPastClientNum
- First observedgetRadiosConfig
- First observedgetRFScanResult
- First observedgetSitesApsAvailableChannel
- First observedgetSitesApsBridge
- First observedgetSitesApsChannelLimit
- First observedgetSitesApsIpSetting
- First observedgetSitesApsLoadBalance
- First observedgetSitesApsOfdma
- First observedgetSitesApsPowerSaving
- First observedgetSitesApsTrunkSetting
- First observedgetSitesDeviceWhiteList
- First observedgetSitesGatewaysGeneralConfig
- First observedgetSitesGatewaysPin
- First observedgetSitesGatewaysSimCardUsed
- First observedgetSitesHealthGatewaysWansDetails
- First observedgetSitesSwitchesEs
- First observedgetSitesSwitchesEsGeneralConfig
- First observedgetSpeedTestResults
- First observedgetStackNetworkList
- First observedgetStackPorts
- First observedgetSwitchDetail
- First observedgetSwitchDot1xSetting
- First observedgetSwitchGeneralConfig
- First observedgetSwitchStackDetail
- First observedgetTrafficDistribution
- First observedgetUpgradeLogs
- First observedgetUpgradeOverviewCritical
- First observedgetUpgradeOverviewTryBeta
- First observedgetUplinkWiredDetail
- First observedlistClients
- First observedlistClientsActivity
- First observedlistClientsPastConnections
- First observedlistDevices
- First observedlistDevicesStats
- First observedlistMostActiveClients
- First observedlistPendingDevices
- First observedlistSitesApsPorts
- First observedlistSitesCableTestSwitchesIncrementResults
- First observedlistSitesCableTestSwitchesPorts
- First observedlistSitesStacks
- First observedlistSwitchNetworks
- First observedlistUpgradeFirmwares
- First observedlistUpgradeOverviewFirmwares
- First observedsearchDevices

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.9/5.0

Scored 2026-07-05 04:40 across 84 tools

Disambiguation3/5

Many tools have similar names (e.g., getApDetail vs getApGeneralConfig, getApRadios vs getRadiosConfig), but descriptions clarify differences. However, the sheer number of specific tools (e.g., 12 getSitesAps* tools) increases chance of misselection.

Naming Consistency4/5

Predominantly uses snake_case with verb_noun pattern (get_, list_). Minor inconsistencies like getClientsDistribution vs getClientDetail, and long names like getSitesHealthGatewaysWansDetails, but overall predictable.

Tool Count2/5

84 tools is excessive for most use cases. While the domain is broad, many tools could be consolidated (e.g., cable test logs vs full results). Presence of deprecated tools further inflates count.

Completeness2/5

Tool set is heavily read-oriented (get/list) with few mutation tools (missing triggerRfScan/triggerSpeedTest from provided list). Lacks create/update/delete for most resources, leaving agents unable to perform basic network management tasks.

Maintenance

ActivityInactive

ResponsivenessWithin a week

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

mcpOAuth
com.vibgrate
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Security Monitoring
2
nexusOAuth
com.civic
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Agent Orchestration Developer Tools App Automation
2
anythingmcp B
io.github.keysersoft
Self-hosted MCP gateway: turn any API, database or MCP server into AI connectors — no code.
Agent Orchestration Data Platforms App Automation
42197
StreamScannerOAuth
net.streamscanner
Query your Twitch streams, events, supporters, raids & rankings from an AI assistant via OAuth.
Entertainment & Media Social Media
2

Related MCP Servers

UniFi Network MCP Server
Home Automation & IoT
Ruashots
A
license
B
quality
D
maintenance
Enables AI assistants to manage UniFi network infrastructure through 50+ tools covering devices, clients, networks, WiFi, firewall rules, and guest access using the official UniFi Network API.
Updated 8 months ago (2026-01-09 01:11 UTC)
52
50
5
MIT
safe-omada-mcp
Networking & Infrastructure Observability Security
gaspareduard
A
license
B
quality
F
maintenance
Security-focused MCP server for TP-Link Omada Open API workflows, enabling network management via natural language.
Updated 5 months ago (2026-04-05 12:55 UTC)
87
21
MIT
UniFi Internal API MCP Server
Networking & Infrastructure Monitoring Security
sevaepsteyn
A
license
B
quality
D
maintenance
Provides 170+ tools to manage UniFi networks via the internal controller API, enabling AI assistants to perform full network management including clients, devices, WLANs, firewall, and more.
Updated 7 months ago (2026-02-13 03:06 UTC)
64
MIT
TP-Link Omada MCP server
Networking & Infrastructure Monitoring
Muggedadscher
A
license
B
quality
C
maintenance
A Model Context Protocol server that exposes TP-Link Omada controller APIs to AI copilots and automation workflows, enabling listing sites, devices, clients, and invoking arbitrary Omada endpoints.
Updated 2 months ago (2026-07-15 19:10 UTC)
84
MIT