A
licenseA
qualityD
maintenanceA Model Context Protocol server that enables AI assistants to read and safely modify TP-Link Omada networks through capability-gated tools, with a default read-only profile and dry-run writes for security.
11
MIT
safe-omada-mcp
by gaspareduard
Provides tools for managing TP-Link Omada network infrastructure, including sites, clients, devices, and configuration settings via the Omada Open API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@safe-omada-mcpshow me all access points on my network"
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.
Safe Omada MCP
Security-focused MCP server for TP-Link Omada Open API workflows.
At a Glance
Production-safe baseline uses
stdioOmada credentials are environment-only
Capability profiles and category gating control what tools are exposed
HTTP remains in the codebase only as an explicitly unsafe, lab-only path
Validated against live Omada Controller 6.x environments and designed around the documented 5.x/6.x Open API surface
Related MCP server: unifi-mcp
Quick Start
Option 1: Use with Claude Desktop via Docker
Pull or build an image:
docker pull ghcr.io/gaspareduard/omada-mcp:latestIf you do not publish an image yet, build locally instead:
npm run docker:buildEdit your Claude Desktop MCP config:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server entry:
{ "mcpServers": { "safe-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=true", "ghcr.io/gaspareduard/omada-mcp:latest" ] } } }Restart Claude Desktop and verify the server by listing sites or devices.
Option 2: Run the container directly
docker run --rm -it \
--env-file .env \
ghcr.io/gaspareduard/omada-mcp:latestOption 3: Run locally for development
npm install
npm run build
npm startConfiguration
The server reads configuration from environment variables. See .env.example for the complete reference.
Required Omada Variables
Variable | Required | Default | Description |
| Yes | - | Base URL of the Omada controller |
| Yes | - | OAuth client ID from Omada Platform Integration |
| Yes | - | OAuth client secret |
| Yes | - | Omada controller ID ( |
| No | - | Optional default site ID |
| No |
| Enforce TLS certificate validation |
| No |
| HTTP timeout in milliseconds |
Capability and Logging
Variable | Required | Default | Description |
| No |
| Built-in profile: |
| No | profile default | Explicit category override |
| No |
|
|
| No |
|
|
Capability Profiles
Profile | Intended use |
| Default read-only operational visibility |
| Limited operational write actions |
| Full documented tool surface, including admin mutations |
| Reserved for future controller-specific fallback modules |
Destructive Tool Confirmation Gate
The four restore tools (restoreController, restoreControllerFromFileServer, restoreSites, restoreSitesFromFileServer) enforce a two-step confirmation: without confirmDangerous: true the tool returns a warning explaining the action is irreversible and that a force recovery or factory reset may be required if something goes wrong.
Scope of this protection: this gate is effective in conversational AI sessions where the warning is surfaced to a human who then decides whether to confirm. It does not prevent a fully autonomous agent from passing confirmDangerous: true programmatically without human review.
True human-in-the-loop enforcement requires one or both of:
MCP client approval mode — Claude Desktop and compatible MCP hosts can be configured to require explicit human approval before any tool call executes. This is the only reliable technical gate against autonomous execution.
Capability profile restriction — the restore tools require
maintenance:rw, which is only granted underops-writeoradmin. Keeping the deployment on the defaultsafe-readprofile blocks all restore tools entirely.
Optional HTTP Lab Mode
HTTP is not part of the supported production baseline.
It only starts when both of these are set:
MCP_SERVER_USE_HTTP=trueMCP_UNSAFE_ENABLE_HTTP=true
Use it only for local lab/debug scenarios.
Variable | Required | Default | Description |
| No |
| Legacy lab-only switch |
| No |
| Explicit acknowledgement required |
| No |
| HTTP port |
| No |
| Loopback bind address only ( |
| No |
| MCP endpoint path |
| No |
| Enable health check |
| No |
| Health check path |
| No |
| Enable CORS |
| No |
| Allowed origins |
| No |
| Legacy placeholder; disabled in safe baseline |
| No | - | Legacy placeholder |
Development and Validation
Common Commands
Task | Command |
Run dev server |
|
Build |
|
Lint + type-check |
|
Unit tests |
|
Coverage gates |
|
Symlink integrity |
|
README/tool sync |
|
Tool/test mapping |
|
Inspector
Use the MCP Inspector when you want to test the built server interactively:
npm run inspector
npm run inspector:buildProject Notes
The safe baseline is
stdiofirst.HTTP remains a legacy, explicitly unsafe lab path.
The repo includes
docs/openapi/as the implementation reference for Omada endpoints.README tool tables below are kept in sync with the registered MCP tools.
Tools
Site & Client
Tool | Description |
| Lists all sites configured on the controller. |
| Get site capacity settings including maximum device and client counts. |
| Get detailed information about a site, including name, region, timezone, and configuration. |
| Get device account settings for a site. |
| Get NTP server status and configuration for a site. |
| Get the remember device setting for a site. |
| Get site specification including device limits and feature capabilities. |
| Get the URL associated with a site for OpenAPI access. |
| Get configuration settings for a site template. Requires |
| Get detailed information about a site template. Requires |
| List all site templates configured on the controller. |
| Lists active client devices for a site. |
| [DEPRECATED] Use |
| Gets the most active clients sorted by traffic usage. |
| Gets client activity statistics over time. |
| Gets past connection history for clients. |
| Sets custom bandwidth limits (download/upload) for a specific client. |
| Applies a predefined rate limit profile to a specific client. |
| Disables bandwidth rate limiting for a specific client. |
| Blocks a client from network access with an auditable mutation summary. |
| Restores a blocked client to network access with an auditable mutation summary. |
| Forces a client to reconnect with an auditable mutation summary. |
| Reboots a managed device with an auditable mutation summary. |
| Changes a device LED state with an auditable mutation summary. |
Device
Tool | Description |
| Lists provisioned devices for a given site. |
| [DEPRECATED] Use |
| Searches for devices globally across all sites the user has access to. |
| Queries statistics for global adopted devices with pagination and filtering. |
| Retrieves detailed configuration and status for a switch stack. |
| Fetches detailed configuration and status for a specific switch. |
| Fetches detailed configuration and status for a specific gateway. |
| Gets WAN port status for a specific gateway. |
| Gets LAN port status for a specific gateway. |
| Gets port information for a specific gateway. |
| Fetches detailed configuration and status for a specific access point. |
| Gets radio information for a specific access point. |
| Gets port information for a switch stack. |
| Lists devices pending adoption in a site. |
| Gets all devices in a site including offline and disconnected devices. |
| Gets the latest available firmware info for a device. Use |
| Gets the auto-check firmware upgrade plan list (paginated). |
| Lists VLAN network assignments for a switch (paginated). Requires |
| Gets general configuration for a switch. Requires |
| Gets cable test history for a switch. Requires |
| Gets full per-port cable diagnostics for a switch. Requires |
| Gets Link Aggregation Group (LAG) list for a switch stack. Requires |
| Gets VLAN network list for a switch stack (paginated). Requires |
| Gets uplink configuration for an AP (wired/mesh mode). Requires |
| Gets per-radio configuration for an AP (channel, power, width). Requires |
| Get VLAN configuration for an access point, including management VLAN and per-SSID VLAN tagging settings. |
| Gets mesh link statistics for an AP. Requires |
| Gets last RF scan results for an AP. Requires |
| Gets last speed test results for an AP. Requires |
| Gets SNMP configuration for an AP. Requires |
| Gets LLDP configuration for an AP. Requires |
| Gets general configuration for an AP (name, LED, country). Requires |
| Get wired uplink detail for an access point: uplink switch, port number, link speed, and PoE status. |
| Gets wired downlink devices on an AP's LAN ports. Requires |
| Get the firmware upgrade plan list for devices managed by the controller. |
| Get firmware upgrade logs showing the history of upgrade operations performed on devices. |
| Get the list of device tags defined in a site. |
| Get QoS configuration for a specific access point. Requires |
| Get IPv6 configuration for a specific access point. Requires |
| Get IP settings for an AP. Requires |
| Get channel limit configuration for an AP. Requires |
| Get list of available channels for an AP. Requires |
| Get load balance configuration for an AP. Requires |
| Get OFDMA configuration for an AP. Requires |
| Get power saving configuration for an AP. Requires |
| Updates AP power saving configuration with support checks and dry-run preview. Requires |
| Updates AP channel-limit configuration with support checks and dry-run preview. Requires |
| Updates documented AP configuration families with dry-run preview. Covers AP general, IP, IPv6, QoS, radio, service, load-balance, OFDMA, trunk, bridge, WLAN group, port, channel, AFC, and antenna settings. Setter-only families return planned payloads and an explicit warning when controller readback is unavailable. Requires |
| Get trunk port setting for an AP. Requires |
| Get bridge configuration for an AP. Requires |
| List ports for an AP. Requires |
| Get ES switch details. Requires |
| Get ES switch general configuration. Requires |
| List cable test port info for a switch. Requires |
| Get incremental cable test results for a switch. Requires |
| Get the number of critical models available for upgrade. |
| Get the current status of the try-beta firmware upgrade switch. |
| List available firmware packages for upgrade (paginated). |
| List firmware overview for upgradeable devices (paginated). |
| List switch stacks in a site (paginated). |
| Get the device adoption whitelist for a site (paginated). |
| Get general configuration for a gateway. Requires |
| Get PIN information for a gateway. Requires |
| Get SIM card usage info for a gateway. Requires |
| Get gateway WAN health details. Requires |
| Updates documented gateway configuration families with dry-run preview. Covers general, services, advanced, radios, WLAN, and port settings. Setter-only families return planned payloads and an explicit warning when controller readback is unavailable. Requires |
Network
Tool | Description |
| Gets internet configuration information for a site. |
| [DEPRECATED] Use |
| Gets WAN port summary/basic info for the site gateway. |
| Gets WAN load balancing configuration (failover/load balance). |
| Gets per-port WAN configuration including connection type and IP settings. |
| Gets WAN-LAN connectivity status for a site. |
| Gets virtual WAN list (paginated). |
| Gets ISP band scan results for a WAN port. Requires |
| Gets the list of wired networks with NAT disabled (paginated). |
| Gets LTE/cellular WAN port configuration. |
| [DEPRECATED] Use |
| Gets ISP scan profile result for a WAN port. Requires |
| Gets QoS configuration for gateway WAN ports. |
| [DEPRECATED] Alias for the WAN health tool; kept for backward compatibility. Requires |
| [DEPRECATED] Use |
| Gets one-to-one NAT rules (paginated). |
| Gets port forwarding status and rules. Required: |
| [DEPRECATED] Use |
| Get the LAN network list using the v2 API, with richer VLAN and DHCP data (paginated). |
| Gets interface-level LAN network bindings. Optional type filter (0=WAN, 1=LAN). |
| Get interface-level LAN network bindings (v2 API). Returns richer per-interface VLAN and network data. |
| Gets the list of LAN profiles configured in a site. |
| [DEPRECATED] Use |
| [DEPRECATED] Use |
| Get multicast rate limit settings for a site. |
| Gets the list of WLAN groups configured in a site. |
| Gets the list of SSIDs in a WLAN group. |
| Gets detailed information for a specific SSID. Required: |
| Lists wireless SSIDs across all WLAN groups. |
| Gets the site-global firewall settings returned by the official Omada firewall endpoint. |
| Updates site firewall settings with dry-run preview using the official Omada Open API firewall endpoint. |
| Updates the gateway ACL mode ( |
| Gets VPN settings for a site. |
| Lists site-to-site VPN configurations. |
| [DEPRECATED] Use |
| Lists gateway (OSG) ACL rules. |
| Creates a gateway ACL rule with dry-run preview using the official Omada Gateway ACL schema. |
| Updates a gateway ACL rule with dry-run preview after confirming the ACL exists. |
| Lists access point (EAP) ACL rules. |
| Creates an EAP ACL rule with dry-run preview using the official Omada EAP ACL schema. |
| Updates an EAP ACL rule with dry-run preview after confirming the ACL exists. |
| Deletes an ACL rule with dry-run preview after confirming the ACL exists. |
| [DEPRECATED] Use |
| Gets available interfaces for static routing. |
| [DEPRECATED] Use |
| Gets policy routing rules (paginated). |
| Gets OSPF process configuration for the site gateway. |
| Gets OSPF interface configuration for the site gateway. |
| Gets VRRP configuration for OSW devices. |
| Gets OSPF neighbor devices for the site gateway. |
| Gets 1:1 NAT rules (paginated). |
| Gets ALG (Application Layer Gateway) configuration. |
| Gets UPnP setting for the site gateway. |
| Gets DDNS entries (paginated). |
| Gets DHCP reservations (paginated). |
| Creates a DHCP reservation after validating the target LAN and optional IP address. |
| Updates a DHCP reservation after validating the target LAN and optional IP address. |
| Deletes a DHCP reservation by MAC address with a dry-run preview option. |
| Gets IP-MAC binding entries (paginated). |
| Gets IP-MAC binding global toggle setting. |
| Gets global bandwidth control configuration. |
| Gets bandwidth control rules (paginated). |
| Creates or updates a bandwidth control rule with dry-run preview after validating the target rule id plus referenced LAN and WAN identifiers. |
| Deletes a bandwidth control rule with dry-run preview after confirming the rule exists. |
| Gets session limit global setting. |
| Gets per-rule session limit rules (paginated). |
| Gets SNMP configuration (version, community string). |
| Gets LLDP global setting. |
| Gets remote logging (syslog) configuration. |
| Gets the DNS cache data list (paginated). |
| Gets IPTV service configuration for the site. |
| Gets NTP server configuration and synchronisation status. |
| Deprecated; alias of |
| Gets controller access control configuration. |
| Updates portal access control settings with dry-run preview and schema validation for pre-auth and free-auth policy entries. |
| Creates or updates an application control rule with dry-run preview after validating the create/update payload shape, existing rule id, and referenced application ids. |
| Deletes an application control rule with dry-run preview after confirming the rule exists. |
| Gets DNS cache setting. |
| Gets DNS proxy configuration. |
| Gets IGMP snooping and proxy setting. |
| Gets VLAN interface configuration for a specific switch. Requires |
| Gets LAN DNS rules for the site (paginated). |
| Gets EAP/switch device usage for a LAN profile. Requires |
| Gets client distribution breakdown across LAN segments. |
| Lists RADIUS authentication profiles. |
| Lists group profiles (IP, MAC, or port groups). |
| Gets application control status for a site. |
| Gets SSH settings for a site. |
| Lists time range profiles. |
| Gets the list of available rate limit profiles for bandwidth control. |
Firewall & ACL
Tool | Description |
| Get 802.1X switch port authentication setting. Alias for |
| Get global RADIUS proxy configuration (controller-level, no siteId). |
| [DEPRECATED] Get application control rules. Alias for |
Firewall Traffic & QoS
Tool | Description |
| Get gateway QoS class rules (paginated). |
| Get bandwidth control details for a site. |
| Get application control rules (paginated). |
| Get application control category list. |
| Get URL filter gateway rules. Alias for |
| Get URL filter MAC deny list. Alias for |
| Get URL filter MAC allow list. Alias for |
| Get MAC filter general setting. Alias for |
| Get QoS policy configuration for a site. |
| Get traffic priority rules for a site. |
| [DEPRECATED] Use |
| [DEPRECATED] Alias for |
| [DEPRECATED] Alias for |
| [DEPRECATED] Alias for |
Firewall IDS / IPS
Tool | Description |
| [DEPRECATED] Use |
Security & Threat Management
Tool | Description |
| Gets global threat management list. Required: |
| Gets top threats from the global threat management view. |
Composite Troubleshooting Tools
Single-call tools that internally aggregate multiple Omada API calls in parallel. Use these instead of chaining individual tools when you need a quick overview or are starting a troubleshooting session.
Tool | Description |
| Composite: combines dashboard overview (device/client counts), internet/WAN status, client distribution, and recent active threats into a single response. First call for any troubleshooting session. |
| Composite: auto-discovers the gateway then fetches its detail (CPU, memory, firmware), WAN port statuses, LAN interface statuses, and port list in one call. Use for internet/WAN diagnostics. |
| Composite: given a client MAC, IP, or hostname — fetches current connection status, detailed client info (VLAN, signal, policy), and recent connection history in one call. |
| Composite: combines active threat list (up to 20, newest first) and firewall settings into one response. Use for security posture checks or investigating alerts. |
Dashboard / Monitor
Tool | Description |
| Gets WiFi summary from the site dashboard. |
| Gets switch summary from the site dashboard. |
| Gets traffic activity data from the site dashboard. |
| Gets PoE usage data from the site dashboard. |
| Gets top CPU usage data from the site dashboard. |
| Gets top memory usage data from the site dashboard. |
| Gets most active switches from the site dashboard. |
| Gets most active access points from the site dashboard. |
| Get the site overview: device counts, client counts, connectivity graph, and overall health status. |
| Gets traffic distribution by protocol/app type over a time range. Requires |
| Gets wireless retry rate and dropped packet rate over a time range. Requires |
| Gets per-WAN ISP link load over a time range. Requires |
| Gets channel distribution and utilization across all APs. |
| Gets top RF interference sources detected by APs. |
| Gets VPN tunnel statistics. Required: |
| Gets IPsec tunnel statistics. |
| Gets OpenVPN tunnel statistics by type. Requires |
Insight
Tool | Description |
| Lists site-level threat management events. |
| Gets WIDS (Wireless Intrusion Detection) information for a site. |
| Gets rogue access points detected in a site. |
| Gets VPN tunnel statistics for a site. |
VPN
Tool | Description |
| List all site-to-site VPN (IPsec) tunnels. Alias for |
| Get detailed config for a specific IPsec tunnel by ID. Alias for |
| Get advanced VPN configuration settings for a site. Alias for |
| Get VPN users for a site (paginated). |
| Get users for a specific client-to-site VPN server. |
| Get status of client-to-site VPN clients. Alias for |
| [DEPRECATED] Use |
Profiles
Tool | Description |
| Get Google LDAP profile configuration for a site. |
| Get built-in RADIUS server user list (paginated). |
| [DEPRECATED] Alias for |
| List PPSK network profiles for a site by type. |
| Get PPSK user group details for a specific profile. |
| [DEPRECATED] Alias for |
| Get service type profiles (paginated). Alias for |
| Get rate limit profiles. Alias for |
| Get time range profiles. Alias for |
| Get group policy profiles filtered by group type. |
| [DEPRECATED] Get IP group profiles. Alias for |
| [DEPRECATED] Get URL/port group profiles. Alias for |
| [DEPRECATED] Get MAC group profiles. Alias for |
| Get LAN/VLAN profiles. Alias for |
| Get user role profiles from the controller (global, no siteId). |
| Get captive portal profiles for a site. |
Logs
Tool | Description |
| Lists site event logs. |
| Lists site alert logs. |
| Lists site audit logs. |
| Lists global event logs across all sites. |
| Lists global alert logs across all sites. |
Controller
Tool | Description |
| Get SSL/TLS certificate configuration for the controller. |
| Get the client history data collection enable setting. |
| Get the controller port configuration for device adoption. |
| Get data retention settings for the controller. |
| Get the experience improvement program setting (telemetry). |
| Get global controller dashboard overview without client data. |
| Get portal port configuration for the controller web interface. |
Maintenance
Tool | Description |
| List available controller backup files. |
| Get the result of the most recent controller backup operation. |
| Get the result of the most recent controller restore operation. |
| List available backup files for a site. |
| Get the backup result for a site. |
| Export Rogue AP scan results for a site in CSV or Excel format. |
| Trigger a controller configuration backup to the self/cloud server. |
| Trigger a controller configuration backup to an external file server (FTP/SFTP). |
| Restore controller configuration from a backup file on the self/cloud server. |
| Restore controller configuration from a backup file on an external file server. |
| Trigger a multi-site configuration backup to the self/cloud server (up to 300 sites). |
| Trigger a multi-site configuration backup to an external file server (up to 300 sites). |
| Restore multiple site configurations from backup files on the self/cloud server. |
| Restore multiple site configurations from backup files on an external file server. |
Account Users
Tool | Description |
| List all cloud users on the controller, excluding the root account. |
| List all local users on the controller, excluding the root account. |
| [DEPRECATED] Use |
| List all users (cloud and local) in grid view. |
| List roles available for user assignment. |
| Get detailed information about a specific role. Requires |
Account Cloud
Tool | Description |
| Get cloud access status for the controller. |
| Get cloud user account information. |
| Get global MFA (multi-factor authentication) status. |
| Get remote binding status between controller and cloud. |
Schedules
Tool | Description |
| List PoE schedules for a site. |
| List port schedules for a site. |
| List ports with port schedule assignments for a site. |
| List device reboot schedules for a site template. Requires |
| List firmware upgrade schedules for a site. |
Supported Omada API Operations
Operation ID | Description | Tool |
| List controller sites. |
|
| List devices assigned to a site. |
|
| Search for devices across all accessible sites. |
|
| Query statistics for global adopted devices. |
|
| Retrieve details for a switch stack. |
|
| Get detailed info for a specific switch. |
|
| Get detailed info for a specific gateway. |
|
| Get WAN port status for a specific gateway. |
|
| Get LAN port status for a specific gateway. |
|
| Get port info for a specific gateway. |
|
| Get detailed info for a specific access point. |
|
| Get radio info for a specific access point. |
|
| Get port info for a switch stack. |
|
| List devices pending adoption in a site. |
|
| List active clients connected to a site. |
|
| Get most active clients sorted by traffic. |
|
| Get client activity statistics over time. |
|
| Get client past connection history. |
|
| Set rate limit setting for a client. |
|
| Get rate limit profile list. |
|
| Get global view threat management list. |
|
| Get top threats from global threat management. |
|
| [DEPRECATED] Use |
|
| Get port forwarding status by type. |
|
| Get LAN profile list. |
|
| Get WLAN group list. |
|
| Get SSID list for a WLAN group. |
|
| Get detailed SSID configuration. |
|
| List SSIDs across all WLAN groups. |
|
| Get the site-global firewall settings returned by the official Omada firewall endpoint. |
|
| Update site firewall settings with dry-run support. |
|
| Get VPN settings for a site. |
|
| List site-to-site VPN configurations. |
|
| List NAT port forwarding rules. |
|
| List gateway ACL rules. |
|
| Get gateway ACL config mode for the site gateway. |
|
| Update gateway ACL config mode with dry-run support. |
|
| Create a gateway ACL with dry-run support. |
|
| Update a gateway ACL with dry-run support. |
|
| List access point ACL rules. |
|
| Create an EAP ACL with dry-run support. |
|
| Update an EAP ACL with dry-run support. |
|
| Delete an ACL rule with dry-run support. |
|
| List static routing rules. |
|
| List RADIUS authentication profiles. |
|
| List group profiles (IP, MAC, port groups). |
|
| Get application control status for a site. |
|
| Create an application control rule with dry-run support. |
|
| Update an application control rule with dry-run support. |
|
| Delete an application control rule with dry-run support. |
|
| Get SSH settings for a site. |
|
| List time range profiles. |
|
| Get WAN-LAN connectivity status for a site. |
|
| List site-level threat management events. |
|
| Get WIDS information for a site. |
|
| Get rogue access points detected in a site. |
|
| Get VPN tunnel statistics for a site. |
|
| List site event logs. |
|
| List site alert logs. |
|
| List site audit logs. |
|
| List global event logs across all sites. |
|
| List global alert logs across all sites. |
|
| Disable rate limiting for a specific client, removing any bandwidth.... |
|
| Get controller access control configuration. |
|
| Update portal access control configuration with dry-run support. |
|
| Get ALG (Application Layer Gateway) configuration for the site gateway. |
|
| Get all devices in a site including offline and disconnected devices. |
|
| Fetch full configuration and status for a specific access point: mo.... |
|
| Get general configuration for an access point. |
|
| Get LLDP (Link Layer Discovery Protocol) configuration for an acces.... |
|
| Get radio status for a specific access point: 2.4GHz and 5GHz band .... |
|
| Get SNMP configuration for an access point. |
|
| Get the uplink configuration for an access point. |
|
| Get the global bandwidth control configuration for the site. |
|
| Get cable test logs for a switch. |
|
| Get channel distribution and utilization across all APs. |
|
| [DEPRECATED] Use |
|
| Get PoE (Power over Ethernet) usage statistics for a site, showing .... |
|
| Get switch summary for a site dashboard: total switch count, total .... |
|
| Get the top devices by CPU usage for a site, useful for identifying.... |
|
| Get WiFi summary for a site dashboard: total APs, connected AP coun.... |
|
| Get DDNS (Dynamic DNS) entries for the site gateway. |
|
| [DEPRECATED] Use |
|
| Get DHCP reservations for the site. |
|
| Create a DHCP reservation for the site after LAN/IP validation and duplicate-IP preflight. |
|
| Update an existing DHCP reservation for the site. |
|
| Delete an existing DHCP reservation for the site. |
|
| Get DNS cache setting for the site gateway. |
|
| Get DNS proxy configuration for the site gateway. |
|
| Get the site-global firewall settings returned by the official Omada firewall endpoint. |
|
| Update site firewall settings with dry-run support. |
|
| Get the latest available firmware information for a device. |
|
| Fetch full configuration and status for a specific gateway: model, .... |
|
| Get LAN port status for a specific gateway: port link state, speed,.... |
|
| Get all WAN and LAN port details for a specific gateway: link statu.... |
|
| Get the WAN port status and connectivity information for a specific.... |
|
| Get bandwidth control rules for the site gateway. |
|
| Create a bandwidth control rule with dry-run support. |
|
| Update a bandwidth control rule with dry-run support. |
|
| Delete a bandwidth control rule with dry-run support. |
|
| Get IP-MAC binding entries for the site. |
|
| Get 1:1 NAT rules for the site gateway. |
|
| Get policy routing rules for the site gateway. |
|
| Get per-rule session limit rules for the site gateway. |
|
| Get virtual WAN list for the site gateway. |
|
| Get IGMP (Internet Group Management Protocol) setting for the site. |
|
| Get interface-level LAN network bindings. |
|
| Get top RF interference sources detected by APs. |
|
| [DEPRECATED] Use |
|
| Get WAN port summary / basic info for the site gateway. |
|
| Get internet configuration information for a site, including WAN se.... |
|
| Get WAN load balancing configuration for the site gateway. |
|
| Get ISP band scan results for a WAN port. Requires |
|
| Get per-WAN ISP link load over a time range. |
|
| Get client distribution breakdown across LAN segments (wired, wireless, guest). |
|
| Get LAN DNS rules configured for the site (paginated). |
|
| [DEPRECATED] Use |
|
| Get EAP/switch device usage for a specific LAN profile. Requires |
|
| Get the list of LAN profiles configured in a site. |
|
| Get LTE/cellular WAN port configuration for the site gateway. |
|
| Get LLDP (Link Layer Discovery Protocol) global setting for the site. |
|
| Get mesh link statistics for an access point. |
|
| Get Link Aggregation Group (LAG) list for a switch stack. |
|
| Get a paginated page of NAT port forwarding rules for the site gateway. |
|
| Get port forwarding status and rules for a site. |
|
| [DEPRECATED] Get the last RF scan results for an access point. |
|
| Get per-radio configuration for an access point. |
|
| Get the list of available rate limit profiles for a site. |
|
| Get remote logging (syslog) configuration for the site. |
|
| Get the DNS cache data list for the site (paginated). |
|
| Get the list of wired networks with NAT disabled (paginated). |
|
| Get IPTV service configuration for the site. |
|
| Get NTP server configuration and synchronisation status for the site. |
|
| Get OSPF interface configuration for the site gateway. |
|
| Get OSPF neighbor devices for the site gateway. |
|
| Get OSPF process configuration for the site gateway. |
|
| Get VLAN interface configuration for a specific switch. Requires |
|
| [DEPRECATED] Alias of |
|
| Get VRRP configuration for OSW devices on the site. |
|
| [DEPRECATED] Alias for the WAN health tool; kept for backward compatibility. Requires |
|
| Get ISP scan profile result for a WAN port. Requires |
|
| Get one-to-one NAT configuration (WAN NAT rules) for the site gateway (paginated). |
|
| [DEPRECATED] Use |
|
| Get QoS configuration for gateway WAN ports on the site. |
|
| [DEPRECATED] Use |
|
| Get wireless retry rate and dropped packet rate over a time range. |
|
| Get the list of rogue (unauthorized) access points detected by WIDS.... |
|
| Get the session limit global setting for the site gateway. |
|
| Get SNMP configuration for the site. |
|
| Get the last speed test results for an access point. |
|
| Get AP channel-limit configuration. |
|
| Update AP channel-limit configuration with dry-run support. |
|
| Update AP general configuration with dry-run support. |
|
| Update AP IP settings with dry-run support. |
|
| Update AP IPv6 settings with dry-run support. |
|
| Update AP QoS settings with dry-run support. |
|
| Update AP radio settings with dry-run support. |
|
| Update AP service settings with dry-run support. |
|
| Update AP load-balance settings with dry-run support. |
|
| Update AP OFDMA settings with dry-run support. |
|
| Get AP power saving configuration. |
|
| Update AP power saving configuration with dry-run support. |
|
| Update AP trunk settings with dry-run support. |
|
| Update AP bridge settings with dry-run support. |
|
| Update AP port settings with dry-run support. |
|
| Update AP channel configuration with dry-run support. |
|
| Update AP AFC configuration with dry-run support. |
|
| Update AP antenna gain settings with dry-run support. |
|
| Update AP WLAN group assignment with dry-run support. |
|
| Update gateway general configuration with dry-run support. |
|
| Update gateway config/general settings with dry-run support. |
|
| Update gateway services configuration with dry-run support. |
|
| Update gateway advanced settings with dry-run support. |
|
| Update gateway radio configuration with dry-run support. |
|
| Update gateway WLAN configuration with dry-run support. |
|
| Update a gateway port configuration with dry-run support. |
|
| Update multiple gateway ports with dry-run support. |
|
| Get SSH access settings for a site. |
|
| Get detailed information for a specific SSID (wireless network), in.... |
|
| Get the list of SSIDs (wireless networks) configured in a WLAN group. |
|
| Get the VLAN network list for a switch stack. |
|
| Get all port information for a switch stack. |
|
| Fetch full configuration and status for a specific switch: model, f.... |
|
| Fetch detailed information for a specific switch stack. |
|
| Get the global view threat management list. |
|
| Get the top threats from the global threat management view across a.... |
|
| Get traffic distribution by protocol and application type over a ti.... |
|
| Get UPnP (Universal Plug and Play) setting for the site. |
|
| Get VPN configuration settings for a site. |
|
| Get VPN tunnel statistics for a site (paginated), including active .... |
|
| Get the WAN and LAN connectivity status for a site. |
|
| Get WAN port settings for the site gateway. |
|
| Get Wireless Intrusion Detection System (WIDS) information for a si.... |
|
| Get the list of WLAN groups configured in a site. |
|
| List all wireless SSIDs across all WLAN groups in a site: SSID name.... |
|
| List all network clients (wired and wireless) connected to a site. |
|
| Get client activity statistics over time from the dashboard. |
|
| Get client past connection list with historical connection data. |
|
| List all provisioned (adopted) network devices in a site: gateways,.... |
|
| List EAP (access point) ACL rules for a site: wireless client acces.... |
|
| List alert logs across all sites on the controller: threshold breac.... |
|
| List system event logs across all sites on the controller. |
|
| List group profiles (IP groups, MAC groups, port groups) configured.... |
|
| Get the most active clients in a site, sorted by total traffic. |
|
| List gateway (OSG) ACL rules for a site: firewall rules controlling.... |
|
| List devices discovered on the network but not yet adopted into thi.... |
|
| [DEPRECATED] Use |
|
| [DEPRECATED] Use |
|
| List RADIUS authentication profiles configured for a site: server I.... |
|
| List alert logs for a site: threshold breaches, device failures, se.... |
|
| List admin audit logs for a site: who made what configuration chang.... |
|
| List system event logs for a site: device online/offline, client co.... |
|
| List site-level threat management events detected by IPS, with opti.... |
|
| List site-to-site VPN configurations: tunnel name, remote IP, statu.... |
|
| List all sites configured on the Omada controller. |
|
| [DEPRECATED] Use |
|
| List VLAN network assignments for a switch. |
|
| List time range profiles configured for a site. |
|
| Search for devices globally across all sites the user has access to. |
|
| Set custom rate limit (bandwidth control) for a specific client. |
|
| Get the ACL configuration type setting for the site gateway (L2 or .... |
|
| Get the DDoS and attack defense configuration, including flood prot.... |
|
| Get global audit log notification settings for the controller. |
|
| Get site-level audit log notification settings, including audit eve.... |
|
| Get global audit logs (paginated). |
|
| Get the band steering configuration. |
|
| [DEPRECATED] Use |
|
| Get the beacon control setting, which manages 802.11 beacon transmi.... |
|
| [DEPRECATED] Get the channel limit setting that restricts which cha.... |
|
| Get the client inactivity timeout setting. |
|
| Get full detail for a specific client by MAC address, including con.... |
|
| Get detailed configuration for a specific client-to-site VPN server.... |
|
| Get client count distribution by connection type and band (wired, 2.... |
|
| Get the Omada controller health and status, including running state.... |
|
| Get the device access management settings, controlling which device.... |
|
| Get the 802.1X EAP setting for access points, controlling port-base.... |
|
| Get the global general settings for the Omada controller, including.... |
|
| Get the IPS allow list (paginated). |
|
| Get the MAC address allow-list entries (paginated). |
|
| Get the IPS block list (paginated). |
|
| Get per-client connection history (paginated). |
|
| Get the MAC address deny-list entries (paginated). |
|
| Get the URL filter AP rules (paginated). |
|
| Get the URL filter gateway rules (paginated). |
|
| Get IPsec failover configuration (paginated). |
|
| Get historical known clients list (paginated). |
|
| Get the IPS signature list (paginated). |
|
| Get static routing rules for the site gateway with explicit pagination. |
|
| Get group profiles filtered by type (e.g. |
|
| Get the IPS (Intrusion Prevention System) global configuration, inc.... |
|
| Get IPsec VPN tunnel statistics for a site (paginated), including a.... |
|
| List all LDAP authentication profiles configured on the site. |
|
| Get global log notification settings (v1), including global alert r.... |
|
| Get global log notification settings (v2), with extended notificati.... |
|
| Get site-level log notification settings (v1), including alert reci.... |
|
| Get site-level log notification settings (v2), with extended notifi.... |
|
| Get the controller logging configuration, including log levels and .... |
|
| Get the MAC authentication global setting. |
|
| Get per-SSID MAC authentication settings showing which SSIDs have M.... |
|
| Get the MAC filtering global setting. |
|
| Get the mail server connection status for the controller. |
|
| Get the mesh networking configuration including mesh topology mode .... |
|
| Get the custom gateway ACL rules list (paginated). |
|
| Get the switch ACL list (paginated). |
|
| Get the OUI-based device profile list (paginated). |
|
| List Private PSK (PPSK) profiles for the site by type. |
|
| Get historical client count trend over a time range. |
|
| Get the RF planning configuration for the site, including frequency.... |
|
| Get the RF planning result for the site. |
|
| Get the global RADIUS server configuration for the controller. |
|
| List local RADIUS server users (paginated). |
|
| Get the global syslog/remote logging configuration, including syslo.... |
|
| Get the data retention configuration for the controller, including .... |
|
| Get the client roaming configuration, including 802.11r/k/v setting.... |
|
| Get the live routing table for a site filtered by type. |
|
| Get a summary of service type profiles for the site, including pred.... |
|
| Get detailed information about a specific site-to-site VPN by ID, i.... |
|
| Get a flat SSID list filtered by device type. |
|
| Get the SSL VPN server configuration, including port, protocol, and.... |
|
| Get the 802.1X switch port authentication setting. |
|
| Get the global threat count grouped by severity level (critical, hi.... |
|
| Get detailed information about a specific IPS threat event by its ID. |
|
| Get the UI interface settings for the controller, including timeout.... |
|
| Get the URL filter global setting, including whether URL filtering .... |
|
| Get the global webhook notification settings, including webhook URL.... |
|
| Get webhook dispatch logs (paginated). |
|
| Get the WIPS (Wireless Intrusion Prevention System) rogue AP blackl.... |
|
| Get a summary of WireGuard VPN configurations for the site, includi.... |
|
| List all client-to-site VPN client configurations on the site. |
|
| List all client-to-site VPN server configurations on the site, incl.... |
|
| Query statistics for global adopted devices with pagination and fil.... |
|
| List all Bonjour/mDNS service profiles configured on the site for c.... |
|
| List service type profiles (paginated). |
|
| List WireGuard VPN tunnels (paginated). |
|
| List WireGuard peers (paginated). |
|
| Get the most active access points from the site dashboard by traffic. |
|
| Get top memory usage data for devices from the site dashboard. |
|
| Get traffic activity data and throughput summary from the site dashboard. |
|
| Get VPN tunnel statistics for the grid dashboard view. |
|
| Apply a predefined rate limit profile to a specific client. |
|
| Get gateway QoS class rules (paginated). |
|
| Get bandwidth control details for a site. |
|
| Get application control rules (paginated). |
|
| Get application control category list. |
|
| Get QoS policy configuration for a site. |
|
| Get traffic priority rules for a site. |
|
| Get VPN users for a site (paginated). |
|
| Get users for a specific client-to-site VPN server by ID. |
|
| Get Google LDAP profile configuration for a site. |
|
| Get PPSK user group details for a specific profile ID. |
|
| Get captive portal profiles for a site. |
|
| Get user role profiles from the controller (global). |
|
| Get global RADIUS proxy configuration (controller-level). |
|
| Get site detail. |
|
| Get site URL. |
|
| Get NTP server status for a site. |
|
| Get site specification. |
|
| Get site remember device setting. |
|
| Get site device account setting. |
|
| Get site capacity setting. |
|
| List site templates. |
|
| Get site template detail. |
|
| Get site template configuration. |
|
| Get data retention settings. |
|
| Get controller port setting. |
|
| Get portal port setting. |
|
| Get certificate configuration. |
|
| Get experience improvement setting. |
|
| Get global dashboard overview without client data. |
|
| Get client history data enable setting. |
|
| List controller backup files. |
|
| Get controller backup result. |
|
| Get controller restore result. |
|
| Get site backup result. |
|
| List site backup files. |
|
| List all cloud users excluding root. |
|
| List all local users excluding root. |
|
| [DEPRECATED] Use |
|
| Get role detail. |
|
| List available roles. |
|
| List all users in app grid view. |
|
| Get cloud access status. |
|
| Get cloud user info. |
|
| Get global MFA status. |
|
| Get remote binding status. |
|
| List upgrade schedules for a site. |
|
| List reboot schedules for a site template. |
|
| List PoE schedules for a site. |
|
| List port schedules for a site. |
|
| List ports with port schedules. |
|
| Get multicast rate limit setting. |
|
| Get AP load balance configuration. |
|
| [DEPRECATED] Use |
|
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
87 toolsdiagnoseClientA
Composite client diagnostic — single call that combines a client's current connection status, detailed info (VLAN, signal, rate limit, group policy), and recent connection history (last 10 sessions). Use when troubleshooting why a device can't connect, has poor performance, or keeps disconnecting. Accepts MAC address, IP address, or hostname.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | Client MAC address, IP address, or hostname to look up. MAC format: XX:XX:XX:XX:XX:XX or XX-XX-XX-XX-XX-XX. | |
| siteId | No | Optional site ID. Uses default site if omitted. | |
| customHeaders | No |
TDQS
A4.1/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 discloses the composite nature and accepted identifier formats (MAC, IP, hostname) but does not describe authentication needs, rate limits, error handling, or return behavior beyond implied aggregation.
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 composite nature, second gives usage guidance. No wasted words. Front-loaded with key benefit and components.
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 complexity, description covers purpose, usage, and identifier format. Missing details on default site behavior, error handling, or return structure. Adequate but incomplete for a composite diagnostic 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 covers identifier and siteId with descriptions. Description adds valuable detail on identifier formats (MAC with colon/hyphen, IP, hostname) and states siteId is optional. Does not mention customHeaders, leaving some gap.
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 is a 'composite client diagnostic' that combines connection status, detailed info (VLAN, signal, rate limit, group policy), and recent connection history (last 10 sessions). It clearly distinguishes from sibling tools by being a single call aggregating multiple data points.
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 specific use cases: 'troubleshooting why a device can't connect, has poor performance, or keeps disconnecting.' Implicitly suggests when not to use (if only one piece of data needed, use getClient or getClientDetail), but lacks explicit exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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/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 it includes offline and disconnected devices, which is the key behavioral trait. However, it does not mention any other behaviors like pagination, rate limits, or whether the operation is read-only (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?
The description is concise with three short sentences. It front-loads the core action ('Get all devices in a site') and immediately adds the key differentiator. Every sentence adds value without 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?
Given no output schema, the description reasonably sets expectations: it returns the full device inventory including offline/disconnected devices, useful for auditing. It does not explain return structure or potential delays, but for a simple list tool with optional parameters, it is sufficiently 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 has 100% coverage with descriptions for both parameters. The tool description does not add additional meaning beyond what the schema already provides (e.g., siteId defaults to config, customHeaders rarely needed). 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 gets all devices in a site, including offline and disconnected devices. It distinguishes itself from the sibling tool listDevices by specifying that listDevices may filter to active-only, making the purpose and differentiation explicit.
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 this tool (for full inventory, auditing) and contrasts with listDevices (which may filter to active-only). It does not explicitly state when not to use it, but the comparison provides sufficient guidance for selection.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 must disclose behavioral traits. It describes the fetched data but does not mention that the tool is read-only, required permissions, or any potential side effects. The description is acceptable but not detailed enough to fully inform an AI agent about behavioral expectations.
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 that front-load the purpose and a prerequisite. Every word adds value, and there is no unnecessary text. It is optimally sized for quick reading.
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 complexity (3 parameters, no output schema), the description provides a reasonable summary of returned fields (model, firmware, CPU/memory, etc.). However, it could be more complete by explicitly stating that the output is a JSON object and mentioning any pagination or response structure.
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 provides parameter details. The description adds no new information beyond repeating the schema's guidance (e.g., 'use listDevices to get the apMac'). It does not enhance understanding beyond what the input schema already 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 fetches full configuration and status for a specific access point, listing key data fields. This distinguishes it from sibling tools that fetch specific sub-configurations (e.g., getApGeneralConfig, getApRadios). The verb 'Fetch' and the resource 'access point' are 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 gives a prerequisite: 'Use listDevices to get the apMac.' However, it does not provide guidance on when to use this tool vs. alternative sibling tools like getApGeneralConfig or getApRadios. This lack of comparison reduces its usefulness for tool selection.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 what the tool returns but does not disclose any behavioral traits such as side effects, rate limits, or authorization requirements. The read-only nature is implied by 'Get' and the description of returning configuration, which is acceptable 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?
Two sentences, zero waste. The first sentence clearly states purpose and returned data, the second directs to an alternative tool. 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?
The description lists several specific configuration fields (device name, LED settings, etc.), which gives a good sense of the output despite lacking an output schema. However, it ends with 'and other global AP parameters', which is vague. Overall, it is fairly complete for a read tool with good 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 coverage is 100% with detailed parameter descriptions for all three parameters. The description does not add any additional meaning beyond what the schema already provides, so it meets 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?
Description uses a specific verb ('Get') and resource ('general configuration for an access point'), lists specific returned fields, and explicitly distinguishes from sibling tool getApDetail which returns runtime status instead.
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?
Description provides clear guidance: use this for stored configuration, use getApDetail for runtime status. It gives an explicit alternative but does not provide further when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApIpv6ConfigC
Get IPv6 configuration for a specific access point.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 omits behavioral traits. It does not confirm the operation is read-only, mention authorization needs, or describe the response format. The description adds no value beyond 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is easy to parse. It is not verbose, but could be slightly expanded to include key usage context without becoming wordy.
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 (3 parameters, no output schema, no annotations), the description is insufficient. It does not explain what the configuration contains, any prerequisites beyond the required apMac, or the structure of 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?
The input schema covers 100% of parameters with descriptions. The tool description does not add additional meaning beyond 'get IPv6 configuration', so it contributes nothing beyond the 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 'Get' and resource 'IPv6 configuration for a specific access point', clearly indicating the tool's function. However, it does not differentiate from sibling tools like getApGeneralConfig or getApLldpConfig, which have similar naming patterns.
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. Given the many sibling getAp* tools, explicit comparisons or selection criteria would help the agent choose correctly.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
B3.4/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 discloses that the tool returns enabled state and advertised TLVs, which implies a read-only operation. However, it does not mention potential error conditions, authorization requirements, or rate limits. The background on LLDP is informative.
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 wasted words. The first sentence states the purpose and return values; the second provides useful background on LLDP. Excellent front-loading.
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 'get config' tool with a well-covered schema and no output schema, the description is complete enough. It mentions the key return fields and provides context about LLDP. It could add more about error handling or prerequisites, but is adequate.
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 all parameters described. The description does not add extra meaning beyond the schema; it does not elaborate on how parameters affect the request or provide examples beyond what is in 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get LLDP configuration for an access point' and specifies the return values (enabled state and advertised TLVs). It distinguishes from siblings like getApGeneralConfig by naming the specific protocol, but does not explicitly differentiate from other getAp*Config tools.
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. It does not mention prerequisites, when not to use it, or suggest alternative tools (e.g., getApGeneralConfig for general config). The description is purely descriptive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getApQosConfigB
Get QoS configuration for a specific access point.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 burden. It implies a read operation but lacks details on error handling, side effects, or what happens if AP is not found. 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence, no fluff. Could mention return format briefly but is efficient for a simple getter.
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 and description does not explain what the QoS configuration contains, leaving the agent without expectations of the return value.
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 parameter descriptions. Tool description adds no extra 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 'Get QoS configuration for a specific access point' with a specific verb and resource, distinguishing it from siblings like getApGeneralConfig or getApVlanConfig.
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 multiple AP config getters, it does not specify contexts or exclusions.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 implies a read-only operation by describing data retrieval, but does not explicitly state non-destructiveness, required permissions, or other behavioral aspects. The description adds moderate transparency by specifying the returned fields.
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 one sentence plus a succinct directive, front-loading the purpose without extra words. Every sentence earns its place, achieving maximum conciseness.
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 lacking an output schema, the description enumerates the key data fields returned, giving a clear picture of the tool's output. For a three-parameter tool with moderate complexity, this provides sufficient completeness for an agent to understand the response structure.
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%; the description does not add significant new meaning beyond the schema definitions. It reinforces the use of listDevices for the apMac parameter, which is already in the schema description. Baseline 3 is appropriate as the schema already documents parameters well.
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 that the tool retrieves radio status for a specific AP, listing concrete data elements (2.4GHz/5GHz config, channel, TX power, channel utilization, client count). It distinguishes from sibling tools that provide broader device details or configuration by focusing on per-AP radio status.
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 instructs users to use listDevices to obtain the apMac, which is helpful. However, it lacks guidance on when not to use this tool or how it differs from similar tools like getRadiosConfig. Usage context is partially provided but without exclusions or alternatives.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 full burden. It states that it returns specific SNMP fields, which is adequate. However, it does not disclose any potential side effects, authentication requirements, or rate limiting. The behavior described is consistent with a read 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: one stating the action and returned fields, and one providing a use case. No extraneous information. 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?
Given the tool has 3 parameters, no output schema, and no annotations, the description covers the purpose, returned fields, and use case adequately. It does not describe output format or prerequisites, but for a read operation with clear parameter instructions, it is largely 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%, and each parameter already has a detailed description in the schema. The tool description does not add any additional meaning or context for the parameters 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 gets SNMP configuration for an access point, lists returned fields (SNMP version, community strings, trap settings, enabled state), and provides a use case (auditing). This distinguishes it from sibling tools like getApDetail or getApGeneralConfig.
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 auditing SNMP configurations but does not provide explicit guidance on when to use it vs alternatives, nor does it mention when not to use it. With many sibling tools, more explicit usage context would help.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses that the tool returns specific data (uplink mode, settings, failover) and implies it is a read operation. It does not mention side effects, authentication needs, or rate limits, but the stated purpose is transparent enough.
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 states purpose and returns, second adds usage context. No redundancy, front-loaded, 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?
Without an output schema, the description explains return values at a high level (mode, settings, failover). This is adequate for most use cases, though details on data types or structure are missing. Given the tool's simplicity, 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%, with each parameter described in the schema (siteId includes default behavior, apMac includes pattern and reference to listDevices, customHeaders is explained). The description adds no further parameter details, 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 uplink configuration for an access point, listing specific return fields (mode, settings, failover). It distinguishes effectively from sibling tools like getApDetail or getUplinkWiredDetail by focusing on uplink 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 it is useful for understanding mesh topology and wired uplink assignments, providing implicit usage context. However, it does not explicitly state when to avoid this tool or compare with alternatives like getUplinkWiredDetail or getMeshStatistics.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is a read operation ('Get') and specifies the returned data (management VLAN, per-SSID VLAN tagging). With no annotations provided, the description carries the burden of behavioral disclosure; it does not mention authentication needs, rate limits, or error handling, but the core behavior is reasonably clear.
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 with no extraneous information. It front-loads the purpose and immediately follows with useful context on return values 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?
The description covers the main purpose, what is returned, and a practical use case. Although no output schema exists, the description adequately describes the return. It could be improved by noting potential error conditions or prerequisites, but overall it is sufficient for a simple getter 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%, so the baseline is 3. The description does not add further meaning beyond the schema for the parameters; it mentions the tool's output but not parameter-specific 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 specifies the tool's action ('Get VLAN configuration') and resource (access point). It differentiates from sibling tools by focusing on VLAN-specific settings, but does not explicitly contrast with other AP getters like getApGeneralConfig or getApUplinkConfig.
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 use case ('useful for verifying network segmentation on wireless infrastructure'), implying when to use it. However, it lacks explicit guidance on when not to use or how it compares to 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.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
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 the full burden. It explains the return data (cable status, length, fault location) but omits behavioral aspects like idempotency, required authentication, side effects, or error conditions. It is adequate but could be more 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 extremely concise: two sentences. The first sentence states the primary action clearly, and the second adds a comparison. 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 provides a good overview of the output content. The parameter schema is fully described. The sibling context shows a related tool. It lacks mention of whether results are paginated or the exact format, but overall it is complete enough for an 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?
All three parameters have schema descriptions with 100% coverage, so the description adds no extra meaning beyond what the schema provides. The baseline is 3, and no additional context is given in 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 clearly states the verb ('Get'), the specific resource ('full cable test results for all ports on a switch'), and the scope ('all ports'). It also differentiates from the sibling tool 'getCableTestLogs' by noting it provides more detailed data.
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 only implies when to use this tool by stating it's 'more detailed than getCableTestLogs', but it does not provide explicit usage guidelines, such as scenarios where one should choose this over the simpler log tool, or any prerequisites like switch access permissions.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
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 bears full responsibility for behavioral disclosure. It does not mention whether the operation is read-only, requires specific permissions, or any side effects. Only describes return content, missing important 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 concise sentences: first states purpose, second adds detail and use case. No wasted words. Information is 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 no output schema and no annotations, the description adequately explains what the tool returns (history, per-port results, lengths, fault detection). It lacks details on pagination, limits, or error handling, but is mostly complete for a 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?
Input schema has 100% description coverage, so the schema already documents all parameters. The tool description adds no additional semantic value beyond what the schema provides. 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?
Description clearly states the verb 'Get' and resource 'cable test logs for a switch' and specifies return content (history, per-port results, etc.). However, it does not differentiate from sibling tool getCableTestFullResults, which likely has 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 Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions usefulness for diagnosing physical layer issues but provides no explicit guidance on when not to use this tool or alternatives (e.g., getCableTestFullResults). Usage is implied but lacks exclusions.
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 | 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. | |
| clientId | Yes |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It explains the tool 'filters the site client list in-process to emulate a per-client lookup', indicating a non-optimal implementation. However, it could further note read-only nature and lack of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three sentences) and front-loaded with the most important deprecation warning. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the deprecated status and absence of output schema, the description covers key aspects: alternatives, mode of operation, and basic function. It could mention output format or additional limitations, but overall it's sufficiently complete for a simple fetch 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 67% (siteId and customHeaders have descriptions, clientId does not). The description adds no extra parameter details beyond the tool's purpose, but the required clientId is implicitly clear. Baseline score of 3 is appropriate for medium coverage without additional explanation.
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 details for a specific Omada client) and explicitly distinguishes from sibling tools by recommending listClients and getClientDetail as alternatives. It also notes the deprecated status, which adds context.
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 when-to-use and when-not-to-use guidance: it declares the tool deprecated and recommends 'Use listClients instead' and 'getClientDetail is also available' for MAC-based lookups, helping agents choose correctly.
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 | Default |
|---|---|---|---|
| clientMac | Yes | MAC address of the client to retrieve details for. | |
| 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.7/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 burden. It mentions the data returned (connection info, IP, etc.) but does not disclose behavioral traits such as read-only nature, error handling (e.g., if MAC not found), authentication needs, or rate limits. The description lacks transparency for a read 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 a single, front-loaded sentence that efficiently conveys the tool's action (get detail), target (specific client by MAC), and content (connection info, IP, VLAN, etc.). Every part earns its place with no wasted words.
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 the essential purpose and lists the return data, which is helpful given no output schema. However, it lacks context on error cases, prerequisites (e.g., client must exist), or how to interpret the details. Adequate for a simple get tool 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 coverage is 100% with descriptions for all three parameters. The description adds minimal extra meaning beyond the schema, such as noting that siteId defaults and customHeaders is rarely needed. This meets baseline expectations but does not significantly enhance 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 tool's purpose: retrieving full detail for a specific client by MAC address, listing connection info, IP, VLAN, signal strength, and traffic stats. It distinguishes from siblings like getClient (presumably basic) and other detail tools (getApDetail, getGatewayDetail).
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 hints at usage by mentioning that siteId can be omitted to use a default, and directs to listSites for discovering site IDs. However, it does not explicitly compare to siblings like getClient or diagnoseClient or state when to use this tool over others.
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 any behavioral aspects such as read-only nature, side effects, permissions, or limitations. It only describes the output briefly.
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) and front-loaded with the action and result. Every sentence earns its place 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?
For a simple read operation with no output schema, the description adequately explains what the tool returns. It could mention the format or aggregation details, but it's largely complete enough for 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 coverage is 100% with descriptions for both parameters. The tool description adds no additional parameter information 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 tool retrieves client count distribution by connection type and band, and provides a use case. It distinguishes from sibling tools that focus on individual clients or lists.
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's useful for understanding network composition at a glance, implying usage for summary analysis, but does not explicitly state when to use or avoid this tool compared to alternatives.
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.5/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 only states it 'Get's data. It does not disclose that this is a read-only operation, any permissions required, or potential side effects. The minimal behavioral detail (just retrieval) is insufficient for safe invocation.
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 contains no fluff. It succinctly conveys the primary action (get), the target resource (most active access points), the scope (in a site), and the ordering (sorted by traffic volume).
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 is adequate for a simple retrieval tool with two optional parameters. However, given the lack of an output schema, it would be beneficial to describe the return format (e.g., a list of EAPs with traffic metrics). As it stands, the description leaves the agent guessing about the response structure.
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 parameter descriptions already explaining siteId defaults and customHeaders rarity. The tool description adds value by specifying the output sorting (by traffic volume) and the context of 'most active', which goes beyond the schema's parameter-level details.
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 most active access points (EAPs) in a site, sorted by traffic volume. The verb 'Get' and resource 'most active access points' are specific, and the sorting detail distinguishes it from sibling tools 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 Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. Although it implies the need for a site context (via parameter), there is no explicit mention of when-not-to-use or which sibling tools are better suited for other types of active device queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardMostActiveSwitchesB
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
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It does not disclose how 'most active' is defined, whether results are paginated, limited to a top N, or the scope of 'site'. The absence of behavioral details (e.g., data freshness, sorting order) undermines agent understanding.
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, no wasted words. However, it prioritized brevity over completeness; adding a sentence about usage or return structure would improve without harming 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?
No output schema exists, yet the description does not hint at return fields (e.g., switch names, traffic volume values). It lacks details on aggregation or limits. Given the tool's data-returning nature, this is a significant gap.
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 parameter descriptions already informative (e.g., siteId fallback to OMADA_SITE_ID). The tool description adds no new parameter context beyond what's in the schema, so a 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 explicitly states the verb 'Get', the resource 'most active switches', and the criterion 'sorted by traffic volume'. It clearly distinguishes this tool from siblings like getDashboardMostActiveEaps (for EAPs) by specifying switches.
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. With over 60 sibling tools, especially similar dashboard tools like getDashboardMostActiveEaps, the lack of explicit usage context severely limits agent selection.
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
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so description must disclose behavior. It lists outputs but lacks details on side effects, performance, or error states. Adequate for a read-only overview.
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, concise and front-loaded with essential information. No redundant 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?
No output schema, but description covers key return data. For a high-level overview tool, this suffices, though more detail on data structure could help.
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 clear parameter descriptions. The description does not add extra meaning beyond what schema already provides, 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?
Description clearly states it retrieves site overview topology including device counts, client counts, connectivity graph, and health status. It positions itself as a first call, distinguishing from more specific sibling tools like getDashboardPoEUsage.
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 says 'Good first call to understand what's in the network', implying initial exploration. Does not list when not to use or alternatives, but context implies it's high-level.
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
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 lacks details on what exactly is returned (e.g., format, aggregation), 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words, effectively conveying the tool's 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?
The tool returns statistics but no output schema is provided, and the description fails to describe the return format or time range, leaving a significant information gap.
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?
Despite 100% schema coverage, the description adds value by explaining default site behavior and referencing listSites for discovery, and noting customHeaders is rarely needed.
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 per switch for a site, distinguishing it from other dashboard tools like getDashboardOverview or getDashboardSwitchSummary.
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 clear purpose but offers no guidance on when to use this tool versus alternatives, such as getDashboardSwitchSummary, 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.
getDashboardSwitchSummaryA
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
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 indicates a read operation (Get) and lists returned data, but does not explicitly state read-only nature, side effects, error conditions, or auth requirements. 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?
Single sentence with clear front-loaded purpose and enumerated data fields. No redundant information. Efficient and scannable.
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 specific return fields, sufficient for a summary tool. Parameters are fully covered. Missing details on error handling or format, but overall complete for expected use.
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 descriptions for both parameters (siteId and customHeaders) are present and add context beyond name/type. siteId description explains default behavior and how to get IDs; customHeaders notes it's rarely needed. This adds 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 action 'Get' and the resource 'switch summary for a site dashboard', listing specific data fields (switch count, ports, PoE, bandwidth). This differentiates it from sibling tools like getDashboardPoEUsage or getDashboardWifiSummary.
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 via 'for a site dashboard' but lacks explicit when-to-use or when-not-to-use guidance versus sibling tools. The siteId parameter description provides some guidance on default site and discovery via listSites, but no alternative comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardTopCpuUsageB
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
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 describes a read operation but does not mention any potential side effects, authentication requirements, rate limits, or how many devices are returned. The term 'top' is ambiguous.
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, well-structured sentence that conveys the core functionality. It is concise without being overly brief, though it could be slightly improved by front-loading the action.
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?
There is no output schema, and the description does not explain the return format or how data is ordered. For a tool returning 'top' devices, this lack of output context reduces 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%, with detailed descriptions for both parameters (siteId and customHeaders). The description does not add extra meaning beyond what the schema provides, 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 uses a specific verb-resource pair ('Get the top devices by CPU usage') and clearly states the tool's function. The name itself reinforces the purpose, and the output is distinct from sibling tools like getDashboardTopMemoryUsage.
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 identifying overloaded devices but provides no explicit guidance on when to use this tool versus alternatives. No when-not-to-use or alternative tools are mentioned.
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.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided and description lacks behavioral traits beyond 'get' (implying read). Omits details like pagination, ordering, number of devices, or whether results are aggregated.
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, directly to the point, no unnecessary words.
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, so description should clarify return format (e.g., list with device names, memory percentages). Currently only states 'top devices by memory usage', leaving agent to infer structure.
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%; description adds no extra parameter meaning. 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?
Clearly states it retrieves top devices by memory usage for a site, distinguishing it from siblings like getDashboardTopCpuUsage which focuses on CPU.
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?
Indicates usefulness for identifying memory-constrained devices but does not provide explicit when-to-use or 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.
getDashboardTrafficActivitiesC
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
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 carries the full burden. It does not disclose behavioral traits such as required permissions, data freshness, rate limits, or what happens with missing data. Only states the output type (trends), which 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 a single, front-loaded sentence with no wasted words. It efficiently conveys the core purpose without redundancy.
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 no output schema, the description does not elaborate on the returned data format, time intervals, aggregation, or other structural details. For a time-series tool, this minimalism leaves gaps in understanding 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%, with both siteId and customHeaders having clear descriptions. The tool description adds no additional parameter meaning beyond what the schema already provides. Baseline score of 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 the tool retrieves time-series data for traffic activities with upload and download trends. It uses specific verb 'Get' and resource 'traffic activity time-series data'. However, it does not differentiate from sibling tools like getTrafficDistribution, which may also involve traffic data.
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. The description only implies it's for time-series trends, but lacks when-not-to-use or context for selecting this tool over siblings like getDashboardOverview or getTrafficDistribution.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDashboardWifiSummaryA
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
A3.6/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 lists output fields without disclosing behavioral traits: no mention of read-only nature, required permissions, rate limits, error handling, or default behavior when siteId omitted. 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?
A single sentence that front-loads the purpose and efficiently lists the output components. No extraneous words or repetition. Every part 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 no output schema, the description adequately covers the return values by listing key components. However, it lacks details on error cases, pagination, or how channel utilization is reported. For a simple tool with two optional params, this 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 description coverage is 100%, so the input schema already documents both parameters. The tool description does not add any additional meaning beyond what the schema provides, meeting the baseline for full 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 tool retrieves a WiFi summary for a site dashboard, listing specific output components (total APs, connected AP count, wireless client count, channel utilization per band, SSID count). This distinguishes it from sibling dashboard tools like getDashboardOverview or getDashboardSwitchSummary.
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 no explicit guidance on when to use this tool versus alternatives like getDashboardOverview or getClientDetail. The purpose is implied but lacks context such as 'use for a quick WiFi health overview' or exclusions for detailed client data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getDeviceB
[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 | 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. | |
| deviceId | Yes |
TDQS
B3.2/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 behavior. It says 'Filters the site device list in-process' implying a read operation but does not mention side effects, permissions, error handling, or limitations beyond deprecation. Incomplete for a tool that may be unreliable.
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 each serve a purpose: deprecation, reason, and function. However, the mixed messaging (deprecated yet functional) slightly reduces clarity. Still reasonably 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 description does not fully guide the agent on how to use alternatives (e.g., listDevices combined with getApDetail/getGatewayDetail). It lacks explanation of when this tool might still be used or its limitations relative to siblings. No output schema mentioned.
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 67% with descriptions for siteId and customHeaders, but deviceId (required) lacks description. The description does not add meaning for deviceId beyond being required, so it adds minimal value over schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states deprecation and suggests using listDevices, but also claims to 'Fetch detailed information for a specific Omada device,' creating confusion about its actual function. The purpose is somewhat clear as a deprecated tool but the active capability is vague.
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 tells the agent to use listDevices instead, and explains why (no dedicated endpoint). This provides clear when-not and alternative guidance.
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 provided, so description carries full burden. It states a read operation but no disclosure of side effects, authentication needs, rate limits, or behavior when siteId is omitted. Minimal insight beyond action.
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, no redundancy. Front-loaded with the key action. Could be slightly expanded without losing conciseness, but current form is efficient.
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, yet description does not hint at return structure (e.g., list of tag names/IDs). With a complex context of many sibling tools, slight elaboration on response format or default behavior would improve 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% with detailed parameter descriptions. The description adds no parameter-specific 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 verb 'Get', resource 'device tags', and scope 'defined in a site'. It is specific and distinguishes from sibling tools that retrieve details of individual devices or other diagnostics.
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 mention prerequisites, context, or exclusions. With many sibling tools for different device info, guidance is lacking.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A3.9/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 the tool returns a list of devices with MAC addresses and connection details, implying a read-only operation. However, it lacks details on permissions, rate limits, error conditions (e.g., if an AP doesn't have switch ports), or whether data is live or cached.
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, highly concise, and front-loaded with the main action. Every sentence adds value, with no redundant or wasted words.
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 is adequate for a simple tool with well-documented parameters, but lacks completeness due to no output schema. It mentions return content but not structure, and does not cover potential errors, limitations, or prerequisites 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 description coverage is 100%, so baseline is 3. The description does not add extra meaning beyond the schema; it mentions return values (device MACs) but not parameter details. The schema already thoroughly describes the three 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 verb 'Get' and specific resource 'wired downlink devices connected to an access point's LAN port'. It distinguishes from sibling tools by focusing on wired downlink devices, which is unique among the many get commands for APs.
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 a clear context by specifying it is useful for APs with built-in switch ports (e.g., EAP615-Wall). However, it does not explicitly state when not to use it or suggest alternatives, though it is implied that it is for wired downlink devices only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getFirmwareInfoA
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 | 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. | |
| deviceMac | Yes | MAC address of the device (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find device MACs. |
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 burden. It discloses return values and implies read-only behavior, but doesn't mention permissions, error handling, or side effects. Adequate but not extra.
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 concise sentences front-load purpose and output, with a helpful prerequisite. 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?
No output schema exists, but description explains return fields sufficiently. Parameter documentation is in schema. For a simple info tool, it 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 descriptions cover 100% of parameters. Tool description repeats the 'use listDevices' hint already in the schema, adding no new semantics beyond what's already 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?
Description clearly states it gets firmware information for a device, listing specific return fields. It distinguishes from siblings like getFirmwareUpgradePlan by focusing on a single device's latest available firmware.
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 prerequisite (use listDevices for deviceMac) but lacks explicit guidance on when to use this vs alternatives, 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.
getFirmwareUpgradePlanC
Get the firmware upgrade plan list for devices managed by the controller.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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?
No annotations provided. The description does not disclose any behavioral traits like pagination handling, request limits, or side effects. It only states the basic 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?
One concise sentence that conveys the essential purpose with no wasted words. Well-structured for a tool 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?
Lacks details about what an upgrade plan includes or what the response looks like. With no output schema, more context is needed to interpret the result.
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 2 of 3 parameters with descriptions. The description adds no extra meaning beyond the schema, so it meets the baseline for 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?
The description clearly states it retrieves a firmware upgrade plan list. The verb 'Get' and resource 'firmware upgrade plan list' are specific. However, it does not differentiate from sibling tools like getFirmwareInfo or listUpgradeFirmwares.
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. There is no mention of when to prefer it over similar list tools or any prerequisites.
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry full behavioral transparency. It describes the tool as fetching data and lists the returned fields, but does not explicitly state it is read-only, mention potential side effects, or any required permissions. The description 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 two sentences: the first clearly explains what the tool does, and the second provides a helpful prerequisite hint. No extraneous information; each 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 three parameters and no output schema, the description lists key return items (model, firmware, etc.), which is sufficient for an agent to understand the tool's output. It does not discuss error conditions or response size, but for a simple fetch tool this is acceptable.
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 clear descriptions for each parameter. The description adds minimal semantic value beyond the schema—only the guidance to use listDevices for the gatewayMac. This meets the baseline for a tool with full 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 tool fetches 'full configuration and status for a specific gateway' and lists specific items like model, firmware, CPU/memory, etc. It distinguishes from sibling tools like getGatewayHealth or getGatewayPorts which focus on subsets.
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 advises to 'Use listDevices to get the gatewayMac,' which is a prerequisite. However, it does not explicitly state when to use this tool versus alternatives like getGatewayHealth or getGatewayLanStatus, nor does it provide exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayHealthA
Composite gateway health check — single call that auto-discovers the site gateway then retrieves its full detail (CPU, memory, firmware, ports), WAN port statuses (link state, IP, ISP), and LAN interface statuses. Use when diagnosing internet connectivity issues, WAN failover, or gateway performance problems. Optionally accepts a gatewayMac to skip discovery.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| siteId | No | Optional site ID. Uses default site if omitted. | |
| gatewayMac | No | Optional gateway MAC address. If omitted, the gateway is discovered automatically by listing site devices. | |
| customHeaders | No |
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 full burden. It mentions auto-discovery and optional skip-discovery, which is good. However, it does not state whether the tool is read-only or any side effects, leaving some behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main purpose and use cases. No filler words; every sentence adds value.
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 return fields (CPU, memory, firmware, ports, WAN/LAN statuses). It covers the composite nature and parameter behavior, making it complete for most use cases.
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 67% (customHeaders not described). The description adds meaning: siteId can be omitted to use default, and gatewayMac can be provided to skip discovery. These clarifications go 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 clearly states the tool is a 'Composite gateway health check' that auto-discovers the site gateway and retrieves full detail (CPU, memory, firmware, ports), WAN port statuses, and LAN interface statuses. This distinguishes it from sibling tools like getGatewayDetail, getGatewayWanStatus, getGatewayLanStatus.
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 scenarios: 'Use when diagnosing internet connectivity issues, WAN failover, or gateway performance problems.' However, it does not mention when NOT to use it or explicitly name alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGatewayLanStatusA
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
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 responsibility for behavioral disclosure. It states the output fields but does not mention any side effects, authorization requirements, or error behaviors (e.g., what happens if the gateway is offline). The description is adequate for a simple read operation but leaves some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of two sentences: the first defines the purpose and returned data, the second provides a prerequisite hint. There is no extraneous information, and the key action is front-loaded. Every word serves a clear function.
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 (3 parameters, no output schema, no nested objects in input), the description covers the essential aspects: what it does, what it returns, and how to get a required parameter. It could be more explicit about the output structure (e.g., indicating it returns an object per port), but overall it is sufficiently complete for an agent to understand its 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% (all three parameters have descriptions in the schema). The tool description adds the hint to use listDevices for gatewayMac, but this is already present in the parameter's description. The added value beyond the schema is minimal, 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 verb 'Get' and the resource 'LAN port status' for a specific gateway, listing the exact details returned (link state, speed, duplex, connected device, VLAN assignment). This distinguishes it from siblings like getGatewayPorts or getGatewayWanStatus, which target different port types or statuses.
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 includes a prerequisite directive ('Use listDevices to get the gatewayMac.'), which guides the agent on how to obtain a required parameter. However, it lacks explicit when-to-use or when-not-to-use guidance compared to alternative tools, such as specifying that this should be used only for LAN port details and not for WAN or general gateway information.
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
TDQS
A3.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 implies a read operation ('Get') and lists output fields, but lacks details on authentication, rate limits, response structure, or error behavior. 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?
Three sentences, each with a clear purpose: what the tool does, its advantage over siblings, and a prerequisite. No redundancy or fluff.
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?
Without an output schema, the description lists output fields but not the structure (e.g., array per port). Given 3 params and nested objects, it is somewhat complete but could specify return format more clearly.
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 well-described in schema. The description adds a hint for gatewayMac ('Use listDevices'), but otherwise adds no new semantic meaning 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 'Get all WAN and LAN port details' and resource 'gateway', listing output fields. It distinguishes from sibling tools getGatewayWanStatus and getGatewayLanStatus by noting it is more detailed.
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 states when to use (when detailed port info is needed) and mentions alternatives (less detailed siblings) and a prerequisite (use listDevices to get gatewayMac). No explicit when-not or exclusion, but sufficient guidance.
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find the gateway MAC. |
TDQS
A4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavior. It describes return fields (WAN IP, DNS, etc.) but does not mention permissions, rate limits, or whether the operation is read-only. For a status tool, this is adequate but not comprehensive.
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 superfluous content. The first sentence defines the action and return fields; the second adds a prerequisite. 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?
No output schema exists, but the description lists key return fields (WAN IP, DNS, uptime, link speed, TX/RX rates, connection type). It does not mention error cases or pagination, but for a straightforward status tool, coverage is good.
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 all parameters. The tool description adds only a repetition of the prerequisite for gatewayMac ('Use listDevices') and mentions return values, which are not parameter semantics. 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 'WAN port status and connectivity information for a specific gateway'. It lists specific return fields and distinguishes from sibling tools like getGatewayLanStatus by focusing on WAN.
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 includes a prerequisite hint: 'Use listDevices to find the gatewayMac.' It implies usage for checking WAN status but does not explicitly contrast with alternatives like getGatewayHealth or getGatewayLanStatus.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridAutoCheckUpgradeB
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 | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| customHeaders | No |
TDQS
B3.2/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 mention any behavioral traits such as side effects, permissions, or rate limits. It merely states what the tool does without additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the purpose, and contains no unnecessary information. Every word contributes to clarity.
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 (GET with pagination), the description sufficiently explains the output. However, no output schema is provided, so agents must infer return structure from the description alone.
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 input schema has 3 parameters with 67% description coverage (page and pageSize are described; customHeaders is not). The description adds no parameter-specific information, so it fails to add value beyond the 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 states 'Get the auto-check upgrade plan list showing scheduled firmware upgrade checks across devices.' This clearly identifies the specific verb (Get) and resource (auto-check upgrade plan list), distinguishing it from siblings like getFirmwareUpgradePlan, but could be more explicit about the difference.
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 auditing upgrade schedules and identifying devices due for automatic firmware updates,' which gives context. However, it does not specify when not to use it or mention alternative tools like getFirmwareUpgradePlan.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridClientHistoryA
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 | Default |
|---|---|---|---|
| clientMac | Yes | MAC address of the client to retrieve history for. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchKey | No | Search keyword to filter history entries. | |
| 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
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that the tool is a read operation returning paginated history with specific fields (timestamps, SSID/network, traffic, auth type). However, it does not provide details on potential behavioral traits like data retention, rate limits, or authentication requirements beyond what is implied by the tool name.
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 front-loading the key purpose and return content. No unnecessary words 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?
Given the complexity of 6 parameters and no output schema, the description is minimally adequate. It explains the purpose and high-level return fields but lacks detail on response structure, time range or how pagination works beyond parameter defaults. Could be more helpful with response format or common usage notes.
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 6 parameters have schema descriptions (100% coverage), so the baseline is 3. The description adds context about the returned fields (timestamps, traffic, etc.) but does not elaborate on individual parameter semantics beyond the schema. Thus, it meets the baseline but does not significantly enhance 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 'Get per-client connection history (paginated)', specifying the verb, resource, and pagination. It distinguishes from siblings like getClient (current status) and listClients (list all clients) by focusing on historical sessions per client.
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 given on when to use this tool versus siblings such as listClientsPastConnections or getClient. There is no mention of prerequisites, typical use cases, or when alternatives might be preferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getGridKnownClientsA
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 | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| sortLastSeen | No | Sort direction for lastSeen field (e.g. "asc" or "desc"). | |
| timeStart | No | Filter start time (Unix epoch milliseconds as string). | |
| timeEnd | No | Filter end time (Unix epoch milliseconds as string). | |
| guest | No | Filter by guest status ("true" or "false"). | |
| searchKey | No | Search keyword to filter clients by name, MAC, or IP. | |
| 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.7/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the burden. It indicates the operation is read-only (historical list) and paginated, but lacks explicit safety notes, rate limits, or effect on system state. Adequate but not comprehensive.
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 front-loads the core purpose and key features (paginated, historical, optional filters). Every word adds value; no filler 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?
Given the complexity (9 params, no output schema, no annotations), the description covers the main intent but could expand on pagination details, return structure, or behavior when no filters are applied. It is 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?
Schema coverage is 100%, with detailed descriptions for all 9 parameters. The description only adds minimal context ('optional time range and search filtering'), providing little extra value 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 clearly states the tool retrieves a paginated list of historical known clients with optional time range and search filtering. It uses a specific verb ('Get') and resource ('known clients list'), distinguishing it from sibling tools like getClient or listClients.
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 it is for historical known clients but does not explicitly contrast with active client lists or other related tools. No when-to-use or when-not-to-use guidance is provided, 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.
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 | 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. | |
| 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. | |
| 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. |
TDQS
A3.8/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description explains it retrieves traffic volume and utilization, but doesn't disclose potential rate limits, data availability, or that it targets a specific site's ISP links. Reasonable but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with core function, no redundancy. Every sentence adds value: operation, detail, use cases.
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?
With 4 params (2 required), no output schema, description covers what the tool does and parameter roles. Lacks indication of output structure (e.g., list of links with metrics), which would help agents parse results. Still, fairly complete for a 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% with descriptions for all parameters. Description reiterates that start/end are Unix timestamps but adds no new semantic info beyond schema. Baseline 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?
Description clearly states 'Get per-WAN ISP link load over a time range' with specific verb and resource. Lists use cases (load balancing, saturated links, failover) that distinguish it from sibling tools like getGatewayHealth or getTrafficDistribution.
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?
Description mentions useful scenarios but lacks explicit guidance on when not to use or alternatives. Does not state prerequisites like having a gateway with WAN links.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A4.2/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It explicitly states the tool is read-only and describes the output fields (backhaul link quality, signal strength, throughput, hop count). It does not mention any side effects, auth requirements, or rate limits, but for a read operation the provided information is 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?
The description consists of two short sentences, no redundant words, and is front-loaded with the key action and resource. 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?
Given the moderate complexity (3 parameters, no output schema, many sibling tools), the description sufficiently explains what the tool returns and its use case. It lacks explicit mention of prerequisites (e.g., mesh-enabled APs must exist) and does not explain the structure of the return value beyond listing fields. However, for a straightforward read tool this is acceptable.
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%: all three parameters have descriptive schema entries (siteId, customHeaders, apMac). The tool description does not elaborate on parameters further; it focuses on the return value. The description adds context about the default behavior of siteId and references to listSites and listDevices, but these are already covered in the schema. Baseline 3 is appropriate as the description adds no new parameter semantics 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 clearly states the verb 'Get' and the resource 'mesh link statistics for an access point', and specifies the returned fields (link quality, signal strength, throughput, hop count). This distinguishes it from sibling tools like getCableTestFullResults or getRFScanResult that focus on other diagnostics.
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 the tool is 'useful for diagnosing mesh network performance', providing clear context for when to use it. However, it does not explicitly exclude scenarios or mention alternatives among the many sibling tools (e.g., getNetworkHealthSummary). A direct reference to when not to use this tool would improve clarity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getNetworkHealthSummaryA
Composite health snapshot — single call that combines dashboard overview (device/client counts, connectivity), internet/WAN status, client distribution, and recent active threats. Use this as the first call when checking if everything is working or when starting any troubleshooting session. Individual sections gracefully degrade if an endpoint is unavailable.
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
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that individual sections gracefully degrade if an endpoint is unavailable, adding valuable behavioral context beyond a simple listing. With no annotations provided, this is a useful disclosure of error handling behavior.
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 concise sentences that front-load the tool's purpose and usage guidance. Every sentence adds value—no redundancy 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 the tool's composite nature and lack of output schema, the description adequately covers the main sections (dashboard, WAN, clients, threats) and graceful degradation. Minor omission of response format or pagination, but acceptable for a snapshot 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?
The input schema already covers both parameters (siteId, customHeaders) with 100% description coverage. The description does not add additional 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool is a 'composite health snapshot' that combines dashboard overview, internet/WAN status, client distribution, and recent active threats. It distinguishes from siblings (e.g., getDashboardOverview, getGatewayHealth) by being a single aggregated 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?
Explicitly recommends using this as the first call when checking if everything is working or starting a troubleshooting session. While it doesn't enumerate when not to use it, the guidance is clear and practical, implying deeper dives via other tools.
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 | 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. | |
| stackId | Yes | Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId. |
TDQS
A4/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 for behavioral disclosure. It states what the tool returns, but does not mention side effects, authorization needs, error conditions, or any destructive potential. As a read operation, it likely has no destructive side effects, but this is 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 extremely concise: two sentences. The first sentence states the purpose and return value; the second provides a crucial usage hint. Every sentence adds value with no fluff 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 the lack of an output schema, the description adequately explains what the tool returns ('configured LAG/trunk groups including member ports, load balancing mode, and status'). It also covers the key parameter requirement (stackId) and how to obtain it. It could mention the response format (e.g., array) or error cases, but overall it is sufficient for a straightforward read operation.
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?
The schema already has 100% coverage with descriptions for all three parameters. The description adds value by advising to use getSwitchStackDetail to find the stackId, which is not in the schema description. This helps the agent understand how to populate the required parameter.
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's purpose: getting the Link Aggregation Group (LAG) list for a switch stack. It names the resource (LAG/trunk groups), the action (get), and the details returned (member ports, load balancing mode, status). It also differentiates from siblings like getStackPorts by focusing on LAG configuration.
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 a key prerequisite: 'Use getSwitchStackDetail to get the stackId,' guiding the agent on how to obtain the required stackId parameter. However, it does not explicitly state when not to use this tool or compare it to siblings like getSwitchStackDetail or getStackPorts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getPastClientNumB
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 | Default |
|---|---|---|---|
| start | Yes | Start of the time range as Unix epoch seconds. | |
| end | Yes | End 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
B3.4/5.0
Behavior3/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 indicates a read operation (history), but does not mention if it is read-only, destructive, or has permission requirements. It also lacks details on rate limits or side effects. The time-series return is stated, but format and limitations are omitted.
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 that front-load the main purpose and include key input requirements. Every sentence is informative with no redundancy, making it highly concise.
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?
While the description covers the tool's purpose and key parameters, it lacks details on the return format of the time-series (e.g., array of objects, intervals), error conditions, or pagination. Given no output schema and many sibling tools, more completeness would be beneficial.
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 beyond the schema by explaining the default behavior for siteId (using OMADA_SITE_ID config) and that listSites can discover IDs, and by clarifying customHeaders as rarely needed. This exceeds the 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?
The description clearly states the tool gets a historical client count trend over a time range as a time-series. It uses a specific verb ('get') and resource ('historical client count'), and the phrase 'time-series' distinguishes it from sibling tools that might return single counts or client details.
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 is provided on when to use this tool versus alternatives like listClients, listClientsActivity, or listClientsPastConnections. The description only states input requirements but does not mention scenarios or exclusions, leaving the agent to infer usage.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 must fully disclose behavioral traits. It describes the return type (configuration) but does not explicitly state that the operation is read-only, idempotent, or free of side effects. It also does not mention authentication requirements 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?
The description is two sentences long with no redundant words. The first sentence states the core functionality, and the second provides differentiation from a sibling tool. 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?
Given the tool's moderate complexity (nested objects, no output schema), the description lists the return fields (band, channel, etc.) and mentions the radio bands (2.4GHz, 5GHz, 6GHz). It does not describe the structure of the output or note whether all radios are always present, but it provides sufficient context for typical 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?
The schema already provides 100% coverage with descriptions for each parameter, so the description adds limited semantic value beyond listing the returned fields. The description mentions 'band, channel, transmit power, channel width, and enabled SSIDs' which aligns with the parameters but does not elaborate on how parameters affect 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 uses a specific verb ('Get') and resource ('per-radio configuration for an access point'), listing detailed settings (band, channel, etc.), and explicitly distinguishes from the sibling tool 'getApRadios' by noting it returns 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?
The description explicitly states when to use this tool ('Returns configuration') and when to use an alternative ('Use getApRadios for runtime radio status'), providing clear context. However, it does not mention scenarios to avoid using this tool or prerequisites beyond the parameters.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 must carry the full burden. It discloses that the result is stored (not real-time) and that a scan is prerequisite, but lacks details on error handling, rate limits, or authorization requirements. The deprecation is a notable 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?
The description is two sentences plus a brief note, front-loaded with the deprecation marker. Every sentence adds value: deprecation warning, purpose, data returned, prerequisite. No unnecessary 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?
Without an output schema, the description lists the key data returned (neighbouring networks, utilization, interference, RSSI). It mentions the prerequisite scan. It does not detail structure or pagination, but for a deprecated tool, the information is sufficient 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%, and the description adds minimal value beyond the schema—only the workflow tip to use triggerRfScan first. The parameters are well-documented in the schema itself, so the description does not significantly enhance understanding of individual 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 it retrieves the last RF scan results for an access point, including specific data types (neighbouring networks, utilization, interference, RSSI). The deprecation note is upfront, and the purpose is distinct from sibling tools.
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 guidance: use triggerRfScan first before calling this tool. The deprecation warning serves as a strong indicator to avoid if possible. However, no explicit alternatives or when-not-to-use scenarios are mentioned beyond deprecation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsAvailableChannelB
Get available channels for an AP.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
B3.3/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does not disclose behavioral traits beyond being a read operation. It lacks details on return format, potential side effects, or authorization needs.
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, front-loaded sentence with no wasted words. Every part adds value.
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?
Adequate for a simple query tool: purpose and required parameter (apMac) are clear. Lacks output format details, but the tool's simplicity and schema descriptions fill most 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%, so parameter descriptions are complete. The main description adds no extra meaning beyond the schema, meeting the baseline.
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') and the resource ('available channels for an AP'). It distinguishes from sibling tools like getSitesApsChannelLimit which focuses on channel limits.
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 other AP channel or radio queries. No exclusions or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsBridgeA
Get P2P bridge config for an AP.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description bears full burden. It indicates a read operation, but does not disclose potential side effects, rate limits, or authorization requirements beyond what is obvious. The skimpy description suffices for a simple getter, but lacks extra 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?
Single, well-structured sentence. Front-loaded with action and subject. No extraneous words. Efficient for quick comprehension.
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 exists, and the description does not hint at the returned data structure (e.g., fields of the P2P bridge config). For a tool with three parameters and no return specification, the description is incomplete for an agent to fully anticipate the 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 coverage is 100%; all parameters have descriptions. The tool description adds no additional parameter meaning beyond what the schema already provides (e.g., siteId default, apMac pattern). Baseline is 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?
Description explicitly states the verb 'Get', the resource 'P2P bridge config', and the target 'an AP', clearly distinguishing it from sibling tools like getSitesApsAvailableChannel or getApGeneralConfig.
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 when P2P bridge config is needed, but provides no explicit when-not-to-use or alternatives. Parameter descriptions offer some context (default site, discovery methods), but overall guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsChannelLimitB
Get channel limit config for an AP.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only indicates a read operation ('Get') but omits details like potential errors (e.g., AP not found), rate limits, or authentication requirements. The lack of output schema further 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence. It is front-loaded with the tool's purpose and contains no unnecessary words. While it could be slightly expanded to include return value hints, it is concise and efficient.
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 (three parameters, no output schema), the description is minimally complete. However, it lacks information about the return format or any side effects, which is important since there is no output schema. For a getter, some context on what 'channel limit config' includes would improve 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?
The input schema has 100% description coverage, so the schema already explains the parameters adequately. The description adds no extra meaning beyond the schema. Baseline 3 is appropriate given the schema's thoroughness.
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 channel limit config for an AP.' clearly specifies the verb (Get) and resource (channel limit config for an AP). It distinguishes itself from sibling tools like getApsAvailableChannel or getApsBridge by focusing specifically on channel limit.
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 other AP configuration getters. It does not mention prerequisites, such as requiring the AP to exist or the need for certain permissions, nor does it explain when the channel limit config is relevant.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 disclose behavioral traits. It only states the tool retrieves IP settings, but does not indicate whether it is read-only (implied by 'Get'), error handling, permission requirements, or response behavior. This is insufficient for a tool with no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundancy. It is front-loaded and efficient, though it sacrifices detail for brevity. Could be expanded to include key behavioral or usage 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?
Given the lack of an output schema, the description should explain what IP settings are returned and any important limitations (e.g., only current settings, not historical). It also does not mention any side effects or prerequisites beyond the parameter hints. Incomplete for a tool with moderate parameter count.
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 schema already covers all three parameters with clear descriptions (100% coverage). The description does not add new semantics beyond the schema, but the schema itself is detailed. 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 the action ('Get') and the resource ('IP settings for an AP'), which distinguishes it from sibling tools that retrieve other AP configurations (e.g., getApGeneralConfig, getApIpv6Config). However, it could be slightly more specific by mentioning what type of IP settings (e.g., DHCP/static).
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 text does not provide any guidance on when to use this tool versus alternatives. It does not mention prerequisites, fallback tools, or exclusions. Although the parameter schema includes hints (e.g., 'Use listSites to discover available site IDs'), the description itself offers no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsLoadBalanceB
Get load balance config for an AP.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 disclose behavioral traits. The description only states the action without clarifying that it is read-only, whether it requires specific permissions, or what happens if the AP is not found. This 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 a single seven-word sentence, front-loading the core purpose without waste. Every word earns its place.
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 and no annotations, so the description should explain the return value and any side effects. It does neither, leaving the agent uninformed about what the response contains or how to handle errors.
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 tool description adds no additional meaning beyond the parameter descriptions in the schema, which already detail siteId, customHeaders, and apMac adequately.
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 load balance config for an AP.' uses a specific verb ('Get') and resource ('load balance config for an AP'), clearly distinguishing it from sibling tools that retrieve other AP configurations (e.g., getSitesApsBridge, getSitesApsChannelLimit).
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 usage is implied by the name and description, but there are no when-not conditions or sibling comparisons provided, limiting the agent's ability to select the correct tool in ambiguous cases.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
B3.4/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It implies a read-only operation ('Get'), which is appropriate. However, it does not disclose details such as authorization requirements, potential side effects, or output format, leaving some ambiguity for a tool that interacts with external systems.
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 extremely concise at six words, front-loading the core purpose. It is not verbose, though it might benefit from including a brief note on what OFDMA configuration entails without becoming bloated.
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 (a single configuration retrieval) and 100% schema coverage, the description is minimally adequate. However, the lack of an output schema and any hints about the response structure or content means the agent may need additional context 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?
The input schema covers 100% of parameters with descriptions, so the description adds no extra semantic value beyond what is already in the schema. The baseline score of 3 applies, as the description does not enhance the 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 'Get OFDMA configuration for an AP' clearly specifies the action (get), the resource (OFDMA configuration), and the scope (an AP). It effectively distinguishes this tool from sibling tools that retrieve other AP-specific configurations like getApRadios or getApGeneralConfig.
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 alternative tools for retrieving AP configurations. There is no mention of prerequisites, when not to use it, or how it compares to related siblings, leaving the agent to infer usage without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesApsPowerSavingC
Get power saving config for an AP.
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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 behavioral disclosure burden. It only states it 'gets' config, implying a read operation, but fails to disclose whether special permissions are needed, error behaviors, or whether it returns partial or full config. The description is too sparse for a mutation-free read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence). While brevity is good, it sacrifices informativeness. The sentence does not earn its place by providing unique insight beyond the tool name itself.
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, the description should indicate what the response contains (e.g., power saving settings structure). It does not. With many sibling tools, more context about scope and usage would be beneficial. The description is incomplete for a configuration retrieval 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%, so baseline is 3. The description adds no extra meaning beyond the schema parameter explanations. The schema already covers siteId, customHeaders, and apMac adequately, so the description offers no 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 the tool retrieves power saving configuration for an AP, using a specific verb and resource. However, it does not differentiate from numerous sibling tools with similar 'getSitesAps*' names, making it harder for an agent to select the correct one.
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 prerequisites, typical use cases, or conditions that might favor other tools. Only parameter descriptions hint at discovering IDs and MACs, but the main text is silent.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
C2.7/5.0
Behavior1/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 repeats the tool name, providing no information about side effects, permissions, rate limits, or read-only nature. This is insufficient for an agent to understand 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
While the description is extremely short, it under-specifies the tool's behavior, effectively being a tautology of the name. It fails to include valuable context that would justify its 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 lack of output schema and nested object parameters, the description should explain what a 'trunk setting' is or outline the response structure. Its single sentence is insufficient 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?
Schema coverage is 100%, so the input schema already documents each parameter's meaning. The description adds no new semantic information beyond the schema, but the baseline of 3 is appropriate given 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 it retrieves the trunk setting for an AP, using a specific verb and resource. It distinguishes from sibling tools that target other AP settings (e.g., getSitesApsBridge, getSitesApsChannelLimit) by explicitly naming 'trunk setting'.
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, nor are there exclusions or prerequisites mentioned. While parameter descriptions hint at usage (e.g., siteId defaulting), the description itself offers no context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesDeviceWhiteListB
Get the device whitelist for 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. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
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 carries full burden. It only states the basic action without disclosing behavioral traits such as read-only nature, authentication needs, or pagination behavior (though schema includes pagination params).
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 not front-loaded with key details. It omits important information like pagination or response structure, so conciseness comes at the cost of completeness.
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 4 parameters and no output schema, the description is too brief. It fails to explain what the whitelist contains, how pagination works, or how to interpret results, leaving significant gaps for an 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?
The schema already covers all parameters (100% coverage), so the baseline is 3. The description adds no additional meaning beyond what the schema provides; it does not explain parameters or their usage 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 clearly states 'Get the device whitelist for a site,' specifying the verb, resource, and scope. Among many sibling get* tools, this focuses on a distinct resource (device whitelist), making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives like listDevices or getDevice. Usage is only implied by the resource name, with no exclusion criteria or context.
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs. |
TDQS
C2.6/5.0
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose any behavioral traits such as side effects, required permissions, rate limits, or error handling. The agent has no information about what happens if the gatewayMac is invalid or if the site is misconfigured.
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, front-loaded phrase. It is concise but lacks structure; every word earns its place but the content is minimal and could be 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 absence of an output schema and the existence of numerous sibling tools (e.g., getGatewayDetail), the description does not explain the return value or how this tool fits into the broader API. It is incomplete for guiding an agent on 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?
The input schema has 100% coverage with detailed descriptions for all three parameters (siteId, customHeaders, gatewayMac). The tool description adds no additional semantics, 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 gateway general config' clearly specifies the verb ('Get') and resource ('gateway general config'), distinguishing it from sibling tools like getApGeneralConfig or getSwitchGeneralConfig. However, it does not elaborate on what 'general config' includes, which slightly reduces specificity.
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 such as getGatewayDetail or listDevices. It lacks any context about prerequisites, selection criteria, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesGatewaysPinB
Get PIN setting for a gateway (LTE model).
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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs. |
TDQS
B3.2/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the purpose without disclosing behavioral traits such as read-only nature, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words. Efficient and to the point.
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 and minimal description. Lacks context about return format, error handling, and prerequisites (e.g., gateway must be LTE model).
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 each parameter. The description adds no extra meaning, warranting the baseline score 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 action 'Get' and the resource 'PIN setting for a gateway (LTE model)', distinguishing it from sibling tools that target different devices or settings.
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 like getSitesGatewaysGeneralConfig. The description provides no context for selection.
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 | 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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs. |
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 carry the full burden of behavioral disclosure. The description only says 'Get SIM card used by a gateway,' which implicitly indicates a read operation but does not specify whether it is destructive, requires specific permissions, or if it caches results. It lacks any behavioral context beyond the verb 'Get'. A read-only hint would be helpful but is absent.
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 of 6 words. It is front-loaded with the purpose and contains no unnecessary information. Every word earns its place.
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 three parameters, no output schema, and no annotations, the description is too brief. It does not explain what a 'SIM card used by a gateway' means in the context of the network, what the output looks like, or any potential side effects or errors. The agent lacks contextual cues to use this tool correctly. For completeness, it should at least mention that it returns SIM card details like IMSI or ICCID.
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 with descriptions for all three parameters (siteId, customHeaders, gatewayMac). The description adds no extra meaning beyond what the schema already provides. Baseline is 3 because the schema is descriptive enough, and the description does not improve 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 clearly states the tool's purpose: 'Get SIM card used by a gateway.' It specifies the verb ('Get') and resource ('SIM card used by a gateway'). However, it does not distinguish this from sibling tools like getGatewayDetail or getSitesGatewaysGeneralConfig, which might also return SIM card information. The purpose is clear but not 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?
No guidance is provided on when to use this tool versus alternatives. There is no mention of when not to use it, or any reference to sibling tools that might provide similar information. An agent would have to infer usage context based solely on the tool name and description, which is insufficient for making an informed choice among many similar 'get' tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesHealthGatewaysWansDetailsA
Get WAN port health details for a gateway.
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. | |
| gatewayMac | Yes | MAC address of the gateway (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find gateway MACs. |
TDQS
A3.5/5.0
Behavior3/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. The word 'Get' implies a read-only operation, which is appropriate. However, the description does not disclose any potential side effects, rate limits, authentication requirements, or data freshness characteristics. It is minimally 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 a single, concise sentence with no extraneous information. It is front-loaded with the action and resource, making it efficient for an AI agent 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?
The tool has no output schema and involves nested objects (implied by context). The description does not explain what 'health details' includes or the structure of the response. While the tool's name hints at details, an agent might benefit from knowing key fields returned. It is adequate for simple use but not 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 100%, so the schema already documents all parameters including siteId, customHeaders, and gatewayMac. The description adds no additional meaning or usage nuances beyond what is in the schema. According to guidelines, baseline is 3 when coverage is high.
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 specific verb 'Get' and clearly identifies the resource as 'WAN port health details for a gateway.' This distinguishes it from sibling tools like getGatewayHealth (general health), getGatewayWanStatus (WAN status), and getGatewayPorts (ports listing), making the tool's purpose unambiguous.
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 specify prerequisites, integration with other tools, or mention when to prefer getGatewayHealth, getGatewayWanStatus, or similar tools. An agent must infer usage solely from the 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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
C2.5/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description lacks behavioral details such as read-only nature, data freshness, or any effects. The tool presumably reads data, but this is not stated.
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 (one sentence) but lacks front-loading of key details and feels incomplete for a tool with 3 parameters.
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 3 parameters, no output schema, and no annotations, the description fails to convey what the returned 'info' entails or how to use the parameters effectively.
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 with descriptions for all parameters, so the description adds no additional meaning. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get easy managed switch info' identifies a verb ('Get') and a resource ('easy managed switch info'), but does not specify what information is included or differentiate it from sibling tools like getSwitchDetail or getSitesSwitchesEsGeneralConfig.
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 guidance is provided. The description does not indicate when to use this tool over alternatives such as getSwitchDetail or getSitesSwitchesEsGeneralConfig.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getSitesSwitchesEsGeneralConfigC
Get easy managed switch general config.
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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
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 carries the full burden of disclosing behavioral traits. It only states a read-like operation ('Get'), but does not explicitly confirm it is read-only, idempotent, or non-destructive. No mention of required permissions, rate limits, or side effects. The description is insufficient for an agent to assess safety.
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 may be too terse. It lacks structure and front-loading of key information. Every word earns its place, but the brevity leads to ambiguity about the scope of 'general config'.
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 of the tool (3 params, no output schema, many sibling tools), the description is incomplete. It does not explain what 'general config' means, what the return value contains, or how this tool differs from similar ones. The schema covers parameters well, but the description fails to provide a complete picture of the tool's functionality.
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 no additional meaning to the parameters beyond what the schema already provides. The schema descriptions for siteId, customHeaders, and switchMac are clear and adequate. The description does not need to add more, but it also 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 states the verb 'Get' and the resource 'easy managed switch general config', which is specific enough to indicate the tool's purpose. However, it does not clarify what 'general config' includes, and the term 'easy managed' may be ambiguous without context. It distinguishes from sibling tools like getSwitchGeneralConfig by specifying 'easy managed', but 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 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 help the agent decide when to use this tool over alternatives like getSwitchGeneralConfig or other get*Config tools. No information about prerequisites, when not to use, or alternative tools 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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
TDQS
A4.4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes return data (upload/download throughput) and that it stores previous results, which is helpful. No annotations provided, so description carries full burden; it adequately discloses read-only behavior but could mention handling of missing results.
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 purpose and followed by usage guidance. No 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?
Covers key aspects: what it does, how to initiate a test, and required param. With no output schema, could detail return format but enough for typical 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 coverage is 100%, so description adds little beyond schema. It notes siteId default and customHeaders rareness but does not deepen understanding of 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?
Clearly states 'Get the last speed test results for an access point', specifying verb and resource. Distinguishes from sibling tools by focusing on speed test results and referencing triggerSpeedTest.
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; this returns stored results', providing clear context on when to use this tool vs alternatives.
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 | 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. | |
| stackId | Yes | Stack ID of the switch stack. Use getSwitchStackDetail to find the stackId. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
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 states the return value is 'VLAN interface assignments across all stack members', but does not disclose side effects, permissions, or confirm read-only behavior. For a simple GET, this is minimally 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 sentences with no extraneous information. The first sentence states the purpose, the second provides a key prerequisite reference. Efficient and well-structured.
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 is very brief. It does not explain pagination behavior, error conditions, or contrast with sibling tools like listSwitchNetworks. Given the tool's simplicity and rich schema, it is adequate but leaves gaps for a less-informed 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?
The input schema has 100% coverage, with all 5 parameters fully described in the schema. The description adds no additional parameter semantics beyond referencing getSwitchStackDetail for stackId, 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' and the resource 'VLAN network list for a switch stack', and distinguishes itself from sibling tools by noting which tool to use to obtain the required stackId.
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 that the tool is for retrieving VLAN network lists for a switch stack and provides a prerequisite hint to use getSwitchStackDetail for the stackId. It does not explicitly contrast with similar list tools like listSwitchNetworks, but the context is adequate.
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 | 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. | |
| stackId | Yes |
TDQS
C2.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must fully disclose behavioral traits. It only states 'Get all port information' without noting if the operation is read-only, has side effects, requires specific permissions, or has rate limits. This is insufficient for safe invocation.
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 and well-structured with no wasted words. However, it is too minimal and lacks essential details, sacrificing completeness for brevity. It scores 3 because while concise, it fails to provide sufficient information.
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 of switch stacks and the fact that there is no output schema or annotations, the description is incomplete. It does not specify what data is returned, how to handle errors, or prerequisites. With many sibling tools, more context is needed to distinguish this tool's precise function.
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 input schema has 3 parameters with 67% description coverage (siteId and customHeaders have descriptions, stackId does not). The description 'Get all port information for a switch stack' adds no extra meaning beyond the schema. It does not explain what stackId represents (e.g., how to obtain it) or hint at return values. For a tool with incomplete schema description, this is inadequate.
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 and resource: 'Get all port information for a switch stack.' It is specific and distinct from sibling tools like listSitesCableTestSwitchesPorts which deals with cable test results, so purpose is clear. However, it lacks additional context on what exactly 'port information' includes, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
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. It does not mention scenarios where a different tool might be more appropriate (e.g., for individual switch ports or cable test results). The description solely states the action without context.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
A3.6/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must carry the full burden. It does not explicitly state whether the tool is read-only, whether it requires specific permissions, or what happens if the switch is not found. While it lists the data returned, it lacks transparency on side effects and error handling.
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 wasted words: the first states the tool's purpose and data returned, the second provides a usage hint. 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?
Given no output schema, the description reasonably covers the return values (model, firmware, CPU, etc.). It lacks mentions of error scenarios or response structure, but is sufficiently complete for a single-item detail 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%, so the description adds marginal value. It reinforces the use of listDevices for the switchMac, but does not provide additional meaning beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool fetches full configuration and status for a specific switch, listing multiple specific data fields (model, firmware, CPU/memory, etc.), clearly distinguishing it from sibling tools like getSwitchGeneralConfig or getDevice.
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 advises to use listDevices to get the switchMac, providing a clear prerequisite. However, it does not specify when to prefer this tool over similar ones like getSwitchGeneralConfig or getSwitchStackDetail, leaving usage context implied.
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.7/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 'Get' and 'Controls', but does not explicitly confirm it is read-only, mention permissions, or describe side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, directly to the point, no redundant information. The first sentence states the action, the second clarifies the purpose. Ideal conciseness.
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 elaborate on the return value (e.g., structure or typical content of the setting). It only says 'setting' without details, leaving the agent unsure what to expect.
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%, but the tool description adds value by explaining the default site behavior and the optional nature of customHeaders. This enhances meaning beyond the schema alone.
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', resource '802.1X switch port authentication setting', and provides context ('Controls port-based network access control'). Differentiates from sibling get tools by specifying the exact 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?
No explicit guidance on when to use this tool versus alternatives like getSwitchGeneralConfig or getSwitchDetail. Usage is implied (for retrieving authentication settings) but 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.
getSwitchGeneralConfigA
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
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. It describes a read operation ('Get') with no mention of destructive actions, auth needs, rate limits, or side effects. This is minimally sufficient 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?
Two sentences cover purpose, scope, and a critical prerequisite. No wasted words; all content is essential 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 high schema coverage (100%) and simple parameter structure (3 params, 1 required), the description adequately covers what the tool does and how to use it. Without an output schema, it provides enough context about the returned data.
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?
The input schema has 100% parameter description coverage, so baseline is 3. The description adds value by clarifying how to obtain the 'switchMac' parameter via listDevices, providing practical guidance 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 ('Get'), names the resource ('general configuration for a switch'), and enumerates included items (device name, LED settings, LLDP, flow control, other global parameters). It clearly distinguishes this tool from siblings like getSwitchDetail, which focus on more specific aspects.
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 gives a direct prerequisite hint ('Use listDevices to get switchMac values'), implying when to use this tool (after listing devices). While it does not explicitly state when not to use it or list alternatives, the context is clear from the sibling list.
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 | 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. | |
| stackId | Yes |
TDQS
C2.6/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 only states 'fetch detailed information' without disclosing behavioral traits such as error handling, rate limits, authentication requirements, or effects of invalid stackId. 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is appropriately sized. However, it lacks structure such as bullet points or additional context, and it could be 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 complexity (3 parameters, no output schema, many siblings, no annotations), the description is insufficient. It does not explain the return format, how to obtain a stackId, or how this tool differs from similar tools like getSwitchDetail or listSitesStacks.
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 description coverage is 67% (siteId and customHeaders have descriptions, stackId does not). The description adds no additional meaning beyond the schema. It does not explain the format or expected value of stackId, nor does it elaborate on siteId or customHeaders beyond what is in the 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 clearly states it fetches detailed information for a specific switch stack. This distinguishes it from getSwitchDetail (individual switch) and other stack-related tools, but does not explicitly differentiate from siblings like listSitesStacks or getStackPorts.
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. Siblings include many similar get* tools, but the description provides no context about selection criteria, prerequisites, or when to choose this over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getTrafficDistributionA
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 | 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. | |
| 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. | |
| 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. |
TDQS
A4/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description communicates that this is a read-only retrieval of traffic data over a time range, with no mention of destructive side effects. It adds context on timestamp format but could be more explicit about its non-modifying 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 two sentences long, directly stating the purpose and providing context on what the breakdown reveals. No wasted words; information is 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 no output schema, the description hints at the output shape (breakdown by category) and time range constraints. It is fairly complete for a retrieval tool with well-documented parameters, though output structure could be more explicit.
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 4 parameters (siteId, customHeaders, start, end) with descriptions. The description only reiterates the timestamp format already in the schema, adding no significant new meaning beyond the structured data.
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 traffic distribution by protocol and application type over a time range, with a specific breakdown by categories like video and gaming. This differentiates it from sibling tools such as getDashboardTrafficActivities.
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 identifying bandwidth consumption but does not provide explicit guidance on when to use this tool versus alternatives like getDashboardTrafficActivities or other traffic-related tools. 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.
getUpgradeLogsC
Get firmware upgrade logs showing the history of upgrade operations performed on devices.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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?
No annotations provided, so description carries the burden. It only states the tool shows history but omits behavioral details like pagination, ordering, or whether it applies to all devices.
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, no filler. Efficient but could be slightly more structured.
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?
Minimal description for a tool with 3 parameters (including customHeaders) and no output schema. Lacks details on return fields, filtering, or sorting.
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%, with page and pageSize described, but customHeaders lacks description. The tool description adds no extra meaning 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 clearly states the tool retrieves 'firmware upgrade logs' showing history of upgrade operations. This distinguishes it from siblings like getFirmwareInfo (firmware details) and getFirmwareUpgradePlan (future plans).
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 versus other upgrade-related tools. No alternatives or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUpgradeOverviewCriticalC
Get the number of critical firmware upgrades available across managed devices.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customHeaders | No |
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 carries full responsibility for behavioral disclosure. It only states the function without revealing that it is a read-only operation, any authentication requirements, or potential rate limits. The description is insufficient for understanding 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the purpose. It contains no fluff, but could be improved by including parameter details. It is efficient given the tool's simplicity.
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 a single complex parameter, the description is too minimal. It does not specify the output format (e.g., a number) or explain the customHeaders parameter. The tool would benefit from additional context about what 'critical upgrades' means and how the count is scoped.
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 0% description coverage. The single parameter 'customHeaders' is a nested object with no explanation in the description. The tool description fails to add any meaning or usage hints for the parameter, forcing the agent to rely solely on the schema, which lacks documentation.
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 the verb 'Get' and the resource 'number of critical firmware upgrades available across managed devices', which is specific and helps the agent understand exactly what this tool returns. It clearly distinguishes from sibling tools like getFirmwareInfo or listUpgradeFirmwares by focusing on the count of critical upgrades.
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, getFirmwareUpgradePlan, or listUpgradeFirmwares. There is no mention of prerequisites or exclusions, leaving the agent to infer usage context 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.
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?
No annotations provided, and description only states it 'gets' status without disclosing side effects, permissions, or rate limits. As a read operation, it likely has minimal behavioral impact, but this is not stated.
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 lacks necessary detail. Could be expanded 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 parameter description, and minimal context about return values or scope. Incomplete for effective tool use.
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 sole parameter 'customHeaders' is not mentioned in the description. With 0% schema coverage, the description should explain the parameter but fails to do so.
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 specifies the action 'Get' and resource 'try-beta firmware switch status' for 'controller', distinguishing it from sibling tools like getUpgradeLogs. However, 'try-beta firmware switch status' 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?
No guidance on when to use this tool versus alternatives like getUpgradeOverviewCritical. Agent must infer usage from name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
getUplinkWiredDetailB
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 behavioral traits. It indicates a read-like operation but does not mention permissions, error handling, or whether it is destructive. It lacks transparency on required authorization or rate limiting.
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 redundant information. First sentence states the action, second elaborates on return content. 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 tool with no output schema, the description provides a reasonable list of returned fields. However, it does not mention potential error cases or null results if no uplink is connected, which would improve 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?
The input schema covers all 3 parameters with descriptions. The tool description adds value by listing return fields, but does not enhance parameter semantics 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.
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 wired uplink detail for an access point, specifying the returned data (connected switch, port number, link speed, PoE status). It is distinct enough from siblings like getApDetail and getApUplinkConfig, though no explicit differentiation is made.
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 getApUplinkConfig or getApDetail. The description only mentions it is useful for mapping topology, but does not specify when not to use it or provide exclusion criteria.
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.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It accurately describes the read-only retrieval behavior and output fields. However, it does not mention potential issues like pagination or response size limits, which is acceptable for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. Front-loaded with the action and resource, followed by output details. 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?
Despite no output schema, the description thoroughly enumerates the returned fields (MAC, IP, hostname, device, SSID, signal strength, traffic, online status). This covers the key information an agent would need to use the tool effectively.
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 both parameters (siteId, customHeaders) with descriptions. The tool description adds no additional meaning beyond what's in 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 uses a specific verb ('List all network clients') and clearly identifies the resource (clients connected to a site). It provides a comprehensive list of returned details (MAC, IP, hostname, etc.), distinguishing it from tools like 'getClient' (specific client) and 'listClientsActivity'.
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 use cases: 'Use this to audit connected devices or find a specific client by name or MAC.' While it doesn't directly mention when not to use it or alternatives, the guidance is clear and practical for typical scenarios.
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 | Default |
|---|---|---|---|
| siteId | No | Optional site ID. If not provided, uses the default site from configuration. | |
| start | No | Optional start timestamp in seconds (e.g., 1682000000) | |
| end | No | Optional end timestamp in seconds (e.g., 1682000000) | |
| customHeaders | No |
TDQS
A4/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 discloses the output type (time-series data) and content (new, active, disconnected clients), but does not mention potential behavioral traits like data granularity, pagination, or effects of missing parameters. It is adequate but not comprehensive.
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, no waste. First sentence states action and source, second specifies output, third suggests use case. Efficient and well-structured.
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 and the moderate complexity (4 optional parameters), the description covers the purpose and output well but lacks details on default behaviors (e.g., siteId, date range defaults) and output format specifics.
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 75% (3 of 4 parameters have descriptions). The description adds context about time-series data but does not improve understanding of individual parameters beyond the schema. Baseline is 3 due to high 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 'Get client activity statistics over time from the dashboard' with specific output details (new, active, disconnected clients for wireless and wired). This distinguishes it from sibling tools like listClients (current clients) and listClientsPastConnections (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 Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Useful for monitoring client connection trends and activity patterns,' which implies usage context. However, it does not explicitly state when not to use it or name alternative tools, so it lacks explicit exclusion guidance.
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 | Default |
|---|---|---|---|
| siteId | No | Optional site ID. If not provided, uses the default site from configuration. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| sortLastSeen | No | Sort by last seen time. Values: asc or desc. When multiple sorts exist, first one takes effect. | |
| timeStart | No | Filter by time range start timestamp (milliseconds). | |
| timeEnd | No | Filter by time range end timestamp (milliseconds). | |
| guest | No | Filter by guest status (true/false). | |
| searchKey | No | Fuzzy search by name, MAC address, or SSID. | |
| customHeaders | No |
TDQS
A4.3/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It discloses the read-only nature and return fields (timestamps, traffic, duration, device details), and mentions pagination, filtering, sorting, and fuzzy search, but could add more 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no fluff: first states purpose, second lists features. Every word adds value.
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 covers the main features and return fields, but given 9 parameters and absence of output schema, it could elaborate on how to combine parameters or the exact structure of returned data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant meaning beyond the schema by explicitly stating 'Supports pagination, filtering by time range and guest status, sorting by last seen time, and fuzzy search by name/MAC/SSID,' which maps directly to multiple parameters and their usage.
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 states 'Get client past connection list with historical connection data' with specific details on returned data and supported features, clearly distinguishing it from sibling tools like getClient (current) and listClients (current list).
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 historical connections but does not explicitly state when to use this tool over alternatives like listClientsActivity or getGridClientHistory, nor does it provide exclusions or preconditions.
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 exist, so the description carries full burden. It describes the output fields and that it lists provisioned devices, which is a read operation. However, it does not mention pagination, rate limits, or potential size of results, which could be important.
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: first covers purpose and return data, second gives direct guidance to sibling tools. No unnecessary 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 no output schema, the description explicitly lists key return fields (MAC, model, firmware, etc.) which is helpful. It lacks pagination details but overall provides sufficient context for agent to use effectively.
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 (siteId with default behavior, customHeaders as rare). The tool description itself does not add extra parameter detail, but the schema already provides adequate meaning; 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 it lists all provisioned network devices (gateways, switches, APs) in a site and lists the returned fields. It explicitly distinguishes from sibling detail tools by mentioning using MAC addresses from this output as input to getGatewayDetail, etc.
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 tells when to use the tool (to list all adopted devices) and how to use the output with detail tools. It does not explicitly state when not to use it or mention alternatives like listPendingDevices, but the context is clear.
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 | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| searchMacs | No | ||
| searchNames | No | ||
| searchModels | No | ||
| searchSns | No | ||
| filterTag | No | ||
| filterDeviceSeriesType | No | ||
| customHeaders | No |
TDQS
A3.7/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 of behavioral disclosure. While it states the tool 'queries statistics' (implying a read operation), it does not explicitly confirm safety, idempotency, or side effects. It also does not mention any required permissions, rate limits, or response structure. The description adds transparency about fuzzy search and filtering but is insufficient for a complete behavior profile.
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. The first sentence states the main purpose and capabilities (pagination, filtering), and the second elaborates on the fuzzy search and filter options. Every part is essential and no word is wasted.
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 should provide guidance on return values. It only says 'statistics', which is vague. The tool has 9 optional parameters, and the description covers most but does not mention any output structure, sorting, or how pagination is handled in results. This is a notable gap for a query tool with moderate complexity.
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?
The schema has 9 parameters with only 22% coverage (page and pageSize have descriptions). The description explains the purpose of 6 parameters: searchMacs, searchNames, searchModels, searchSns (fuzzy search) and filterTag, filterDeviceSeriesType (filtering). It compensates well for the low schema coverage by mapping these to user-facing concepts. The customHeaders parameter is not mentioned, but the overall value added is significant.
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 verb 'Query' and the resource 'statistics for global adopted devices', with explicit mention of pagination and filtering. This distinguishes it from sibling tools like listDevices (which lists devices without stats) and searchDevices (which searches but doesn't mention stats).
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 indicates the tool supports fuzzy search and filtering, implying use for querying device statistics with pagination. However, it does not provide explicit guidance on when to use this tool over alternatives, nor does it mention exclusions or prerequisites. The context is clear but lacks direct comparison to 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
A3.6/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description mentions 'quick overview' implying lightweight read, but does not detail pagination, limits, or destructive behavior. 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?
Two sentences, clear and front-loaded with no redundancy. Efficiently conveys purpose and returns.
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 return fields and sorting. Context as dashboard endpoint is sufficient 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?
Input schema has full descriptions for both parameters (siteId, customHeaders). Description adds no extra meaning beyond 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 clearly states the tool retrieves the most active clients sorted by total traffic, listing specific fields. It is distinct from siblings like listClients or getClient.
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 calls it a 'dashboard endpoint for quick overview' but does not specify when to use it over alternatives like listClients or getClientDetail.
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
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 full burden. It implies read-only list operation without side effects, but does not disclose pagination, permission requirements, error behavior, or any constraints. For a simple list, 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?
Description is extremely concise: one sentence stating the action, one sentence listing returns. No fluff, front-loaded with the key purpose. Every word adds value.
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 covers the essential context: what the tool does, what it returns, and the distinction from adopted devices. Could mention pagination or default site behavior more explicitly, but overall sufficient.
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 schema descriptions for siteId (default site config, discover via listSites) and customHeaders (rarely needed) are already detailed. The tool description adds no additional parameter information 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?
Description clearly states the tool lists devices discovered but not yet adopted, and specifies returned fields (type, MAC, IP, model). This distinguishes it from sibling tools like listDevices which likely list adopted devices.
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?
Description does not provide explicit guidance on when to use this tool versus alternatives like listDevices. There is no mention of prerequisites or context for adoption workflow, leaving usage decision implicit.
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 | 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. | |
| apMac | Yes | MAC address of the access point (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find AP MACs. |
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 carry the full burden. The description does not disclose that this is a read-only operation, any authentication needs, rate limits, or potential side effects. It is insufficient for safety-critical decisions.
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 extremely concise at three words, which is efficient. It is front-loaded and contains no filler. However, it may be slightly too minimal for a tool with three parameters and many siblings.
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 annotations, no output schema, and a simple listing purpose, the description is minimally adequate but lacks context about typical use cases, response structure, or behavior beyond the schema. More detail would improve 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 schema already documents all three parameters with descriptions. The tool description adds no additional information 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 'List ports on an AP' clearly states the verb (list) and resource (ports on an AP). It is specific and unambiguous, but does not differentiate from sibling tools that may also list ports (e.g., getApDetail, getSwitchDetail).
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, context, or exclusions, which is a significant gap given the large sibling list.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose whether the tool is read-only, destructive, requires permissions, or the nature of 'incremental results'. The name suggests listing, but description says 'get'; this ambiguity is not resolved.
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 at the expense of completeness. It efficiently states the core purpose but omits details about returns or context. It is not verbose, but could better use word count to cover key points.
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 and no explanation of what 'incremental results' means or the return format. The description is too brief for a tool that likely has complex return data. Sibling tools like getCableTestFullResults may provide contrast, but this tool's description lacks completeness.
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 each parameter described. The description adds value beyond schema by noting siteId defaults to config, customHeaders rarely needed, and switchMac hints to use listDevices. This is helpful context that aids correct invocation.
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 'Get' and resource 'cable test incremental results for a switch', clearly indicating the tool's action. However, it does not distinguish from siblings like getCableTestFullResults or getCableTestLogs, so it loses a point for lack of differentiation.
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. For example, it does not mention that full results are obtained via getCableTestFullResults or that logs are via getCableTestLogs. Also no prerequisites or context like the need for a compatible switch.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. |
TDQS
B3.1/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but only states the action. It does not disclose behavioral traits like read-only nature, side effects, or prerequisites beyond what is implied by parameter names.
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 quickly conveys the tool's purpose. It is front-loaded and earns its place without 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?
Given the tool has 3 parameters and no output schema or annotations, the description is too brief. It omits details like expected output format, error conditions, or prerequisites for using the switchMac.
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 baseline is 3. The description does not add extra meaning beyond the schema fields; it simply restates the overall purpose.
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 the specific verb 'List' and resource 'ports available for cable test on a switch', clearly distinguishing it from siblings like getCableTestFullResults or getCableTestLogs which deal with results rather than port listing.
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 when to invoke getCableTestFullResults instead. The description lacks any when/where context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
listSitesStacksC
List switch stacks 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. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
C2.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the minimal description does not disclose behavioral traits like pagination behavior, authentication requirements, or potential side effects. Only states basic listing action.
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, no filler. Could be considered too brief, but for a simple list tool it is concise. Front-loaded with the action 'List switch stacks in a site.'
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 4 parameters including pagination and no output schema. The description does not mention pagination, return format, or handling of defaults (e.g., siteId from config). Incomplete for a list operation with pagination.
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 descriptions (100% coverage), so the description adds no extra 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 lists switch stacks in a site. It is specific with verb and resource, but does not explicitly differentiate from sibling tools like getSwitchStackDetail or listSwitchNetworks.
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 getSwitchStackDetail (for a single stack) or listSwitchNetworks (for networks). Does not mention prerequisites or 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.
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 | 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. | |
| switchMac | Yes | MAC address of the switch (e.g. "AA-BB-CC-DD-EE-FF"). Use listDevices to find switch MACs. | |
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. |
TDQS
A3.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 carries full burden. It does not state whether the tool is read-only, destructive, or has any side effects. The pagination parameters (page, pageSize) imply paginated results but the description omits this behavior. Basic behavioral disclosure is 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?
Two sentences plus a brief note. No redundant information, front-loaded with main purpose. 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 tool has no output schema, so the description must cover return format and pagination. It briefly describes output (which VLANs assigned to ports) but does not mention pagination behavior or result structure. Given 5 parameters and common list tool patterns, the description is adequate but misses key details.
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 the context for switchMac (use listDevices) and siteId default behavior. It also clarifies the output briefly. However, some parameter descriptions (page, pageSize) add little 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 clearly states the tool lists VLAN network assignments for a switch, specifying output includes VLAN ports with tagged/untagged configuration. It mentions a prerequisite step (use listDevices to get switchMac). No sibling tool explicitly covers switch VLAN assignments, so it is well-distinguished.
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 a clear usage context: to retrieve VLAN assignments for a switch. It explicitly tells the user to use listDevices to obtain the switchMac parameter. However, it does not mention when not to use this tool or contrast with similar tools like getSwitchDetail or getSwitchGeneralConfig, leaving some ambiguity.
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 | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| customHeaders | No |
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 the full burden. It does not disclose any behavioral traits such as pagination, ordering, authentication requirements, or read-only nature. The description only restates 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?
The description is a single, clear sentence with no redundant information. It is front-loaded and efficient, earning a top score for 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?
For a list tool with no output schema and three parameters (one undocumented), the description is too minimal. It does not cover return format, pagination behavior, or the role of customHeaders, making it incomplete for effective use.
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 description coverage is 67% (page and pageSize have descriptions, customHeaders does not). The description adds no additional meaning beyond the schema, failing to explain the customHeaders parameter or provide usage context for any parameter.
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 'List uploaded firmware files available for manual upgrade,' which identifies the verb and resource. However, it does not distinguish this tool from the similar sibling 'listUpgradeOverviewFirmwares', so it loses the top score.
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 like 'getFirmwareInfo' or 'listUpgradeOverviewFirmwares'. It lacks any when-to-use or when-not-to-use information.
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 | Default |
|---|---|---|---|
| page | No | Start page number. Start from 1. | |
| pageSize | No | Number of entries per page. Range: 1-1000. | |
| customHeaders | No |
TDQS
C2.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 convey behavioral traits. It merely says 'list,' implying a read-only operation, but does not disclose any side effects, required permissions, or pagination behavior beyond what is in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one sentence), but it lacks substance. It is not front-loaded with key differentiators.
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, 3 parameters (one undocumented), and no behavioral details, the description is incomplete for an agent to fully understand the tool's return value and usage 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?
The schema covers 67% of parameters with descriptions for 'page' and 'pageSize'; the description adds no additional meaning. The 'customHeaders' parameter has no description in schema or description. Baseline score of 3 is appropriate given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List firmware pool entries in the upgrade overview,' which indicates a specific verb and resource. However, it does not differentiate from the sibling tool 'listUpgradeFirmwares,' making the purpose somewhat unclear without additional context.
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 'listUpgradeFirmwares' or other firmware-related tools. The description lacks context for selecting the correct tool.
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.9/5.0
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden but only states basic search and return. Missing details on pagination, rate limits, auth needs, or match semantics.
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-loading purpose with no redundant information.
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?
Lacks output schema and does not describe return format, pagination, or sorting. The customHeaders parameter is unexplained, leaving gaps for a search tool.
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 coverage is 0% and description adds no meaning beyond 'search key'. The customHeaders parameter is entirely 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?
The description clearly states the verb 'Search', the resource 'devices', and the global scope across all sites, distinguishing it from site-specific sibling tools like getAllDeviceBySite.
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 listDevices or getDevice. The description does not provide when-not-to-use or exclusions.
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. Dates show when Glama detected each change.
87 tool updates
v0.17.0- First observed
diagnoseClient - First observed
getAllDeviceBySite - First observed
getApDetail - First observed
getApGeneralConfig - First observed
getApIpv6Config - First observed
getApLldpConfig - First observed
getApQosConfig - First observed
getApRadios - First observed
getApSnmpConfig - First observed
getApUplinkConfig - First observed
getApVlanConfig - First observed
getCableTestFullResults - First observed
getCableTestLogs - First observed
getClient - First observed
getClientDetail - First observed
getClientsDistribution - First observed
getDashboardMostActiveEaps - First observed
getDashboardMostActiveSwitches - First observed
getDashboardOverview - First observed
getDashboardPoEUsage - First observed
getDashboardSwitchSummary - First observed
getDashboardTopCpuUsage - First observed
getDashboardTopMemoryUsage - First observed
getDashboardTrafficActivities - First observed
getDashboardWifiSummary - First observed
getDevice - First observed
getDeviceTagList - First observed
getDownlinkWiredDevices - First observed
getFirmwareInfo - First observed
getFirmwareUpgradePlan - First observed
getGatewayDetail - First observed
getGatewayHealth - First observed
getGatewayLanStatus - First observed
getGatewayPorts - First observed
getGatewayWanStatus - First observed
getGridAutoCheckUpgrade - First observed
getGridClientHistory - First observed
getGridKnownClients - First observed
getIspLoad - First observed
getMeshStatistics - First observed
getNetworkHealthSummary - First observed
getOswStackLagList - First observed
getPastClientNum - First observed
getRadiosConfig - First observed
getRFScanResult - First observed
getSitesApsAvailableChannel - First observed
getSitesApsBridge - First observed
getSitesApsChannelLimit - First observed
getSitesApsIpSetting - First observed
getSitesApsLoadBalance - First observed
getSitesApsOfdma - First observed
getSitesApsPowerSaving - First observed
getSitesApsTrunkSetting - First observed
getSitesDeviceWhiteList - First observed
getSitesGatewaysGeneralConfig - First observed
getSitesGatewaysPin - First observed
getSitesGatewaysSimCardUsed - First observed
getSitesHealthGatewaysWansDetails - First observed
getSitesSwitchesEs - First observed
getSitesSwitchesEsGeneralConfig - First observed
getSpeedTestResults - First observed
getStackNetworkList - First observed
getStackPorts - First observed
getSwitchDetail - First observed
getSwitchDot1xSetting - First observed
getSwitchGeneralConfig - First observed
getSwitchStackDetail - First observed
getTrafficDistribution - First observed
getUpgradeLogs - First observed
getUpgradeOverviewCritical - First observed
getUpgradeOverviewTryBeta - First observed
getUplinkWiredDetail - First observed
listClients - First observed
listClientsActivity - First observed
listClientsPastConnections - First observed
listDevices - First observed
listDevicesStats - First observed
listMostActiveClients - First observed
listPendingDevices - First observed
listSitesApsPorts - First observed
listSitesCableTestSwitchesIncrementResults - First observed
listSitesCableTestSwitchesPorts - First observed
listSitesStacks - First observed
listSwitchNetworks - First observed
listUpgradeFirmwares - First observed
listUpgradeOverviewFirmwares - First observed
searchDevices
TDQS
B3.1/5.0
Disambiguation4/5
Most tools have distinct purposes, but deprecated tools (getClient, getDevice, getRFScanResult) overlap with newer alternatives (listClients, listDevices). The large number of getSitesAps* tools are well-differentiated but could confuse agents due to their similar prefixes.
Naming Consistency4/5
The overwhelming majority of tools follow a clear verb_noun pattern (e.g., getApDetail, listDevices). Minor inconsistencies exist: 'searchDevices' vs. 'getAllDeviceBySite', and 'diagnoseClient' could be more consistent with 'getClientDetail'. However, overall pattern is strong.
Tool Count2/5
With 87 tools, the surface is extremely large and likely overwhelms agents. Many highly granular tools (e.g., separate tools for each AP configuration aspect) could be consolidated. This count far exceeds typical scope for a single server, making selection difficult.
Completeness2/5
The tool set is heavily read-oriented, with extensive get/list operations for devices, clients, and configurations. However, it lacks create, update, or delete operations for most resources (e.g., no add/remove client, no device adoption/removal). This creates dead ends for agents attempting full lifecycle management.
Maintenance
ActivityInactive
ResponsivenessUnresponsive
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
MCP server for Pentest-Tools.com: run scans, manage findings and reports via your preffered LLM.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server that turns Claude into a UniFi network specialist. Manage devices, optimize WiFi, audit security, and troubleshoot your network through natural language.31202MIT
- AlicenseNot gradedqualityBmaintenanceRead-only MCP server for TP-Link Omada SDN controllers, enabling querying controller, site, device, and WiFi state.Apache 2.0
- AlicenseBqualityCmaintenanceA 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.84MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gaspareduard/Omada-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server